001/*
002 * Copyright (c) 2016-2017 Chris K Wensel <chris@wensel.net>. All Rights Reserved.
003 * Copyright (c) 2007-2017 Xplenty, Inc. All Rights Reserved.
004 *
005 * Project and contact information: http://www.cascading.org/
006 *
007 * This file is part of the Cascading project.
008 *
009 * Licensed under the Apache License, Version 2.0 (the "License");
010 * you may not use this file except in compliance with the License.
011 * You may obtain a copy of the License at
012 *
013 *     http://www.apache.org/licenses/LICENSE-2.0
014 *
015 * Unless required by applicable law or agreed to in writing, software
016 * distributed under the License is distributed on an "AS IS" BASIS,
017 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
018 * See the License for the specific language governing permissions and
019 * limitations under the License.
020 */
021
022package cascading.operation;
023
024import cascading.tuple.Fields;
025import cascading.tuple.TupleEntry;
026import cascading.tuple.TupleEntryCollector;
027
028/**
029 * Interface AggregatorCall provides access to the current {@link Aggregator} invocation arguments.
030 * <p>
031 * This interface is generic, allowing the user to set a custom 'context' object when {@link Aggregator#start(cascading.flow.FlowProcess, AggregatorCall)}
032 * is called. The {@link OperationCall#setContext(Object)} and {@link OperationCall#getContext()} methods are
033 * inherited from {@link OperationCall}.
034 *
035 * @see Aggregator
036 * @see OperationCall
037 */
038public interface AggregatorCall<C> extends OperationCall<C>
039  {
040  /**
041   * Returns the current grouping {@link TupleEntry}.
042   *
043   * @return TupleEntry
044   */
045  TupleEntry getGroup();
046
047  /**
048   * Returns {@link TupleEntry} of argument values.
049   * <p>
050   * Will return {@code null} unless called in {@link Aggregator#aggregate(cascading.flow.FlowProcess, AggregatorCall)}.
051   * <p>
052   * Note that the returned TupleEntry should not be cached (stored in a Collection), nor should the underlying Tuple
053   * instance. Where possible Cascading will re-use both TupleEntry and Tuple instances.
054   * <p>
055   * To get a safe copy that can be cached, use {@link TupleEntry#getTupleCopy()}.
056   *
057   * @return TupleEntry
058   */
059  TupleEntry getArguments();
060
061  /**
062   * Return the resolved {@link cascading.tuple.Fields} declared by the current {@link Operation}.
063   *
064   * @return Fields
065   */
066  Fields getDeclaredFields();
067
068  /**
069   * Returns the {@link cascading.tuple.TupleEntryCollector} used to emit result values.
070   * <p>
071   * Will return {@code null} unless called in {@link Aggregator#complete(cascading.flow.FlowProcess, AggregatorCall)}.
072   *
073   * @return TupleCollector
074   */
075  TupleEntryCollector getOutputCollector();
076  }