net.sf.jagg
Class Aggregator

java.lang.Object
  extended by net.sf.jagg.Aggregator
Direct Known Subclasses:
AbstractVarianceAggregator, AvgAggregator, CollectAggregator, ConcatAggregator, CountAggregator, GeometricMeanAggregator, HarmonicMeanAggregator, MaxAggregator, MinAggregator, ModeAggregator, MultiPropAggregator, ProductAggregator, SumAggregator, TwoPropAggregator

public abstract class Aggregator
extends java.lang.Object

This abstract class allows for the state necessary to implement aggregate functions. Subclasses define the following steps of the Aggregation algorithm:

  1. 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.
  2. Iteration, with the iterate method. This adds a value to the aggregation. This will be called exactly once per object to aggregate.
  3. 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).
  4. Termination, with the terminate method. At this point, all aggregation is complete, and only a final result needs to be constructed.

The factory method getAggregator creates Aggregators and marks them as in use. They are stored in a cache (a HashMap) so they may be reused. After an Aggregator is used, it will be marked as not in use; it remains in the cache and it may be reused.

The abstract method replicate must be defined for every Aggregator. This method returns an uninitialized copy of the Aggregator, with the same type and the same properties to analyze as the original Aggregator.

The concrete method terminateDoubleDouble may be overridden by Aggregators that operate on floating-point numbers. This allows other Aggregators to use the high-precision result, a DoubleDouble, internally in their calculations. The default implementation simply returns DoubleDouble.NaN.

Currently, Aggregators do not need to be thread-safe. The Aggregation class is the only class that uses Aggregators, and only one Thread at a time uses any Aggregator.

However, internally, the Aggregator class uses synchronized access to internal HashMaps to cache Aggregators (and Methods).

Since:
0.1.0
Author:
Randy Gettman
See Also:
DoubleDouble

Field Summary
static java.lang.String PROP_SELF
          Special pseudo-property indicating that the object itself is to be aggregated, instead of a property of the object.
 
Constructor Summary
protected Aggregator()
          Default constructor is protected so that only subclasses of Aggregator can be instantiated.
 
Method Summary
 boolean equals(java.lang.Object o)
          Determines whether the given Aggregator is equivalent to this Aggregator.
static Aggregator getAggregator(Aggregator archetype)
          Adds the given Aggregator to an internal cache.
static Aggregator getAggregator(java.lang.String aggSpec)
          Adds the given Aggregator to an internal cache.
 java.lang.String getProperty()
          Retrieves the property that this Aggregator aggregates.
protected static java.lang.Object getValueFromProperty(java.lang.Object value, java.lang.String property)
          Gets a specific Method from an internal cache, or creates it using reflection if it does not exist.
 int hashCode()
          Calculates a hash code for this Aggregator.
abstract  void init()
          Initializes the Aggregator.
 boolean isInUse()
          Determines whether this Aggregator is in use.
abstract  void iterate(java.lang.Object value)
          Processes the given value into the aggregation.
abstract  void merge(Aggregator agg)
          Merges the state of the given Aggregator into this own Aggregator's state.
abstract  Aggregator replicate()
          Returns an uninitialized copy of this Aggregator object, with the same property(ies) to analyze.
 void setInUse(boolean inUse)
          Sets whether this Aggregator is in use.
protected  void setProperty(java.lang.String property)
          Sets the property name.
abstract  java.lang.Object terminate()
          At this point the aggregation of values is complete, and a final result needs to be constructed.
 DoubleDouble terminateDoubleDouble()
          Return the result as a DoubleDouble.
 java.lang.String toString()
          A String representation of this Aggregator, in the form "className(property)".
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

PROP_SELF

public static final java.lang.String PROP_SELF
Special pseudo-property indicating that the object itself is to be aggregated, instead of a property of the object.

See Also:
Constant Field Values
Constructor Detail

Aggregator

protected Aggregator()
Default constructor is protected so that only subclasses of Aggregator can be instantiated.

Method Detail

getAggregator

public static Aggregator getAggregator(Aggregator archetype)
Adds the given Aggregator to an internal cache. If it's not in use, then it marks it as "in use" and returns it. Else, it searches the cache for an Aggregator that matches the given Aggregator and is not already in use. If none exist in the cache, then it replicates the given Aggregator, adds it to the cache, and returns it.

Parameters:
archetype - The Aggregator whose properties (and type) need to be matched.
Returns:
A matching Aggregator object. It could be archetype itself if it's not already in use, or it could be null if archetype was null.

getAggregator

public static Aggregator getAggregator(java.lang.String aggSpec)
Adds the given Aggregator to an internal cache. Does not mark it as in use. Does not add it to the internal cache. This is meant to aid the caller in creating an Aggregator based on the following specification string format: aggName(property/-ies). This assumes that the desired Aggregator has a one-argument constructor with a String argument for its property or properties.

Parameters:
aggSpec - The String specification of an Aggregator.
Returns:
An Aggregator object.
Throws:
java.lang.IllegalArgumentException - If the aggregator specification was mal- formed.

getValueFromProperty

protected static java.lang.Object getValueFromProperty(java.lang.Object value,
                                                       java.lang.String property)
Gets a specific Method from an internal cache, or creates it using reflection if it does not exist. The method is looked up via the name "get<Property>", with the given property name, on the given value object. Invokes the Method and returns the value. This is expected to be called in the iterate method, so that it can access the object's property, although it can be called from any Aggregator method. This method is here to standardize the "bean" method naming convention specified by Aggregator and to cache Method objects for internal use.

Parameters:
value - The object on which to lookup a property value.
property - The property to lookup.
Returns:
The object's property value.
Throws:
java.lang.UnsupportedOperationException - If the desired Method does not exist, if the Method cannot be invoked because of Java language access control (e.g. private, etc.), or if the invoked Method throws an Exception.
See Also:
iterate(java.lang.Object)

setProperty

protected void setProperty(java.lang.String property)
Sets the property name. Subclasses may override this method if they want to extract more information from the property string, e.g. "Name(property, addlInfo)". The default implementation simply stores the entire string to be made available via "getProperty".

Parameters:
property - The property name.
See Also:
getProperty()

isInUse

public final boolean isInUse()
Determines whether this Aggregator is in use.

Returns:
A boolean indicating whether it's in use.

setInUse

public final void setInUse(boolean inUse)
Sets whether this Aggregator is in use.

Parameters:
inUse - The boolean indicating whether it's in use.

replicate

public abstract Aggregator replicate()
Returns an uninitialized copy of this Aggregator object, with the same property(ies) to analyze.

Returns:
An uninitialized copy of this Aggregator object.

init

public abstract void init()
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.


iterate

public abstract void iterate(java.lang.Object value)
Processes the given value into the aggregation. E.g., a "sum" aggregation will add this object's property value to a sum object. An implementation will likely want to call getValueFromProperty, which accesses a cache of Methods to find the property's value in the given object.

Parameters:
value - The value to aggregate.
See Also:
getValueFromProperty(java.lang.Object, java.lang.String)

merge

public abstract void merge(Aggregator agg)
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.

Parameters:
agg - The Aggregator whose state needs to be merged into this one.

terminate

public abstract java.lang.Object terminate()
At this point the aggregation of values is complete, and a final result needs to be constructed. This method constructs that final result.

Returns:
A value representing the result of the aggregation.

terminateDoubleDouble

public DoubleDouble terminateDoubleDouble()
Return the result as a DoubleDouble. This is used mainly when other Aggregators that use this result must maintain a high precision.

Returns:
A DoubleDouble representing the result of the aggregation. The default implementation returns DoubleDouble.NaN.
Since:
0.4.0
See Also:
DoubleDouble

equals

public boolean equals(java.lang.Object o)
Determines whether the given Aggregator is equivalent to this Aggregator. This is necessary because Aggregator objects will be stored in a HashMap.

Overrides:
equals in class java.lang.Object
Parameters:
o - Another Aggregator.
Returns:
true if equivalent, false otherwise.

hashCode

public int hashCode()
Calculates a hash code for this Aggregator. This is necessary because Aggregator objects will be stored in a HashMap.

Overrides:
hashCode in class java.lang.Object
Returns:
The hash code of this Aggregator. It is computed by taking the hash of the result of the toString method.
See Also:
toString()

getProperty

public java.lang.String getProperty()
Retrieves the property that this Aggregator aggregates.

Returns:
A property name.

toString

public java.lang.String toString()
A String representation of this Aggregator, in the form "className(property)".

Overrides:
toString in class java.lang.Object


Copyright © 2010-2013 jAgg Team. All Rights Reserved.