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