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  }