001/*
002 * Copyright (c) 2007-2022 The Cascading Authors. All Rights Reserved.
003 *
004 * Project and contact information: https://cascading.wensel.net/
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.nested.core;
022
023import java.io.Serializable;
024
025import cascading.tuple.Fields;
026import cascading.tuple.Tuple;
027import cascading.tuple.type.CoercibleType;
028
029/**
030 * Interface NestedAggregate provides a basic abstraction for aggregating set of values collected from
031 * a set of parent objects.
032 * <p>
033 * See {@link cascading.nested.core.aggregate.SimpleNestedAggregate} for a convenient base implementation.
034 *
035 * @see NestedGetAllAggregateFunction
036 */
037public interface NestedAggregate<Node, Context> extends Serializable
038  {
039  /**
040   * @return the fields this aggregate function will return
041   */
042  Fields getFieldDeclaration();
043
044  /**
045   * @return a new function specific context object
046   */
047  Context createContext( CoercibleType<Node> nestedCoercibleType );
048
049  /**
050   * This method receives each collected value to be applied to the current aggregation.
051   *
052   * @param context the context object created by {@link #createContext(CoercibleType)}
053   * @param node    the Node container object that should be aggregated
054   */
055  void aggregate( Context context, Node node );
056
057  /**
058   * This method completes the aggregate operation and insert the results into a Tuple instance.
059   * <p>
060   * Note the Tuple may be created (indirectly) by the {@link #createContext(CoercibleType)} method and reused.
061   *
062   * @param context the context object created by {@link #createContext(CoercibleType)}
063   * @return a Tuple containing the aggregate value(s), the Tuple may be reused
064   */
065  Tuple complete( Context context );
066
067  /**
068   * This method is called after {@link #complete(Object)} so that any resources can be freed and the result
069   * context instance can be used in the next aggregation.
070   *
071   * @param context the context object created by {@link #createContext(CoercibleType)}
072   * @return either a cleared or new context instance to be used in further aggregations
073   */
074  Context resetContext( Context context );
075  }