net.sf.jagg.AggregateFunction Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of jagg-core Show documentation

jAgg is a Java 5.0 API that supports “group by” operations on Lists of Java objects: aggregate operations such as count, sum, max, min, avg, and many more. It also allows custom aggregate operations.

The newest version!

package net.sf.jagg;

/**
 * An AggregateFunction is an object that can compute aggregate
 * statistics on a list of values.  Implementations define the following steps
 * of the Aggregation algorithm:
 * 
 * Initialization, with the init method.  This initializes
 *    the state of the Aggregator.  Aggregators may be reused, so
 *    this method must be prepared to instantiate or reset any state objects it
 *    maintains.
 * Iteration, with the iterate method.  This adds a value to
 *    the aggregation.  This will be called exactly once per object to
 *    aggregate.
 * Merging, with the merge method.  In parallel execution,
 *    this merges results from two Aggregator objects resulting
 *    from parallel execution.  After the merge method completes,
 *    then this Aggregator reflects the combined state of both
 *    this Aggregator and another Aggregator. Merging
 *    takes place during parallel execution and during super aggregation
 *    (rollups, cubes, and grouping sets).
 * Termination, with the terminate method.  At this point, all
 *    aggregation is complete, and only a final result needs to be constructed.
 * 
 *
 * @author Randy Gettman
 * @since 0.9.0
 */
public interface AggregateFunction
{
   /**
    * Initializes the Aggregator.  Subclasses should override this
    * method to instantiate state objects that will hold the state of the
    * aggregation.  E.g., a "sum" aggregation will initialize a sum object to
    * zero.  This Aggregator may be reused, so any objects may
    * already be instantiated, but their state must be reset.
    */
   public abstract void init();

   /**
    * Processes the given value into the aggregation.  E.g., a "sum"
    * aggregation will add this object's property value to a sum object.
    *
    * @param value The value to aggregate.
    */
   public abstract void iterate(Object value);

   /**
    * Merges the state of the given Aggregator into this own
    * Aggregator's state.  Called when parallel execution
    * yields more than one Aggregator to combine into one.
    *
    * @param agg The Aggregator whose state needs to be merged
    *    into this one.
    */
   public abstract void merge(AggregateFunction agg);

   /**
    * At this point the aggregation of values is complete, and a final result
    * needs to be constructed.  This method constructs that final result.
    *
    * @return A value representing the result of the aggregation.
    */
   public abstract Object terminate();

   /**
    * Retrieves the property that this Aggregator aggregates.
    *
    * @return A property name.
    */
   public abstract String getProperty();

   /**
    * Determines whether this AggregateFunction is in use.
    * @return A boolean indicating whether it's in use.
    */
   public boolean isInUse();

   /**
    * Sets whether this AggregateFunction is in use.
    * @param inUse A boolean indicating whether it's in use.
    */
   public void setInUse(boolean inUse);

   /**
    * Returns an uninitialized copy of this AggregateFunction object,
    * with the same property(ies) to analyze.
    * @return An uninitialized copy of this AggregateFunction object.
    */
   public AggregateFunction replicate();
}