|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.sf.jagg.Aggregator
public abstract class Aggregator
This abstract class allows for the state necessary to implement aggregate functions. Subclasses define the following steps of the Aggregation algorithm:
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.
iterate
method. This adds a value to
the aggregation. This will be called exactly once per object to
aggregate.
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).
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
).
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 |
---|
public static final java.lang.String PROP_SELF
Constructor Detail |
---|
protected Aggregator()
Aggregator
can be instantiated.
Method Detail |
---|
public static Aggregator getAggregator(Aggregator archetype)
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.
archetype
- The Aggregator
whose properties (and type)
need to be matched.
Aggregator
object. It could be
archetype
itself if it's not already in use, or it could
be null
if archetype
was null.public static Aggregator getAggregator(java.lang.String aggSpec)
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.
aggSpec
- The String specification of an Aggregator
.
Aggregator
object.
java.lang.IllegalArgumentException
- If the aggregator specification was mal-
formed.protected static java.lang.Object getValueFromProperty(java.lang.Object value, java.lang.String property)
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.
value
- The object on which to lookup a property value.property
- The property to lookup.
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
.iterate(java.lang.Object)
protected void setProperty(java.lang.String property)
property
- The property name.getProperty()
public final boolean isInUse()
Aggregator
is in use.
public final void setInUse(boolean inUse)
Aggregator
is in use.
inUse
- The boolean indicating whether it's in use.public abstract Aggregator replicate()
Aggregator
object,
with the same property(ies) to analyze.
Aggregator
object.public abstract void init()
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 iterate(java.lang.Object value)
getValueFromProperty
,
which accesses a cache of Methods
to find the property's
value in the given object.
value
- The value to aggregate.getValueFromProperty(java.lang.Object, java.lang.String)
public abstract void merge(Aggregator agg)
Aggregator
into this own
Aggregator
's state. Called when parallel execution
yields more than one Aggregator
to combine into one.
agg
- The Aggregator
whose state needs to be merged
into this one.public abstract java.lang.Object terminate()
public DoubleDouble terminateDoubleDouble()
DoubleDouble
. This is used mainly
when other Aggregators
that use this result must maintain a
high precision.
DoubleDouble
representing the result of the
aggregation. The default implementation returns
DoubleDouble.NaN
.DoubleDouble
public boolean equals(java.lang.Object o)
Aggregator
is equivalent to
this Aggregator
. This is necessary because
Aggregator
objects will be stored in a HashMap
.
equals
in class java.lang.Object
o
- Another Aggregator
.
true
if equivalent, false
otherwise.public int hashCode()
Aggregator
. This is
necessary because Aggregator
objects will be stored in a
HashMap
.
hashCode
in class java.lang.Object
Aggregator
. It is computed by
taking the hash of the result of the toString
method.toString()
public java.lang.String getProperty()
Aggregator
aggregates.
public java.lang.String toString()
Aggregator
, in the form
"className(property)".
toString
in class java.lang.Object
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |