    001    /*
    002     * Copyright (c) 2007-2014 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      }