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.flow.FlowProcess;
024    import cascading.tuple.TupleEntry;
025    
026    /**
027     * Class GroupAssertion is a kind of {@link Assertion} used with the {@link cascading.pipe.Every} pipe Operator.
028     * <p/>
029     * Implementers should also extend {@link BaseOperation}.
030     *
031     * @see Aggregator
032     */
033    public interface GroupAssertion<C> extends Assertion<C>
034      {
035      /**
036       * Method start initializes the aggregation procedure and is called for every unique grouping.
037       * <p/>
038       * The AggregatorCall context should be initialized here if necessary.
039       * <p/>
040       * The first time this method is called for a given 'process', the AggregatorCall context will be null. This method should
041       * set a new instance of the user defined context object. When the AggregatorCall context is not null, it is up to
042       * the developer to create a new instance, or 'recycle' the given instance. If recycled, it must be re-initialized to
043       * remove any previous state/values.
044       * <p/>
045       * For example, if a Map is used to hold the intermediate data for each subsequent
046       * {@link #aggregate(cascading.flow.FlowProcess, GroupAssertionCall)} call,
047       * new HashMap() should be set on the AggregatorCall instance when {@link cascading.operation.AggregatorCall#getContext()} is null.
048       * On the next grouping, start() will be called again, but this time with the old Map instance. In this case,
049       * map.clear() should be invoked before returning.
050       *
051       * @param flowProcess   of type FlowProcess
052       * @param assertionCall of type GroupAssertionCall
053       */
054      void start( FlowProcess flowProcess, GroupAssertionCall<C> assertionCall );
055    
056      /**
057       * Method aggregate is called for each {@link TupleEntry} value in the current grouping.
058       *
059       * @param flowProcess   of type FlowProcess
060       * @param assertionCall of type GroupAssertionCall
061       */
062      void aggregate( FlowProcess flowProcess, GroupAssertionCall<C> assertionCall );
063    
064      /**
065       * Method doAssert performs the assertion.
066       *
067       * @param flowProcess   of type FlowProcess
068       * @param assertionCall of type GroupAssertionCall
069       */
070      void doAssert( FlowProcess flowProcess, GroupAssertionCall<C> assertionCall );
071    
072      }