    001/*
    002 * Copyright (c) 2007-2017 Xplenty, 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
    021package cascading.operation;
    022
    023import cascading.flow.FlowProcess;
    024import 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 */
    033public 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  }