AbstractTimedAggregator (Apache Commons Functor 1.0-SNAPSHOT API)

java.lang.Object
- org.apache.commons.functor.aggregator.AbstractTimedAggregator<T>

Type Parameters:
T - type of data to aggregate

All Implemented Interfaces:

Aggregator<T>, Functor, NullaryFunction<T>, NullaryFunctor

Direct Known Subclasses:

AbstractListBackedAggregator, AbstractNoStoreAggregator
```
public abstract class AbstractTimedAggregator<T>
extends Object
implements Aggregator<T>
```
An aggregator which automatically resets the aggregated data at regular intervals and sends a notification when it is about to do so, so listeners can decide to gather the information before it is being reset (and log it etc). This allows for smaller memory footprints for instance in the case of List-based aggregators, as regularly the list is emptied. Also it allows for the call to evaluate to represent an "aggregated" value over a certain period of time. Note that you can still have a regular aggregator extending this class by specifying an interval less than or equal to zero. The regular flush/reset will be triggered from a timer which will always be started as a daemon thread (so it will stop when there are no more non-daemon threads in the JVM); this class allows 2 types of timers:
- (default) per instance Timer -- each instance of this class will create a new Timer and this Timer will have a single TimerTask scheduled, which is the one that resets this Aggregator regularly and sends notifications. This way, when the Aggregator instance is destroyed, the Timer goes as well.
- shared Timer instance -- this class will create a static instance of Timer which can be shared by other instances of this class. While this is a bit more effective from a memory and thread management point of view, it has the downside that if the TimerTask's are not managed properly this can create memory leaks. So if you decide to take this route make sure when you are finished with this instance, to always stop the timer at the end.
Synchronization: This class provides a thread safe framework so when doAdd(Object), reset() and evaluate() is called, access is synchronized via a read-write lock. evaluate() is considered a read operation and doAdd(Object) and reset() are considered write operations.

Field Summary

Fields
Modifier and Type	Field and Description
`static long`	`NO_TIMER` As per `timer` javadoc, if the interval specified is zero or less there will be no `Timer` created/assigned to this instance.
`static String`	`TIMER_NAME` Name of the shared timer which will run all the TimerTasks resulted from creating instances of this class which are set to used the shared timer.

Constructor Summary

Constructors
Constructor and Description
`AbstractTimedAggregator()` Default constructor -- creates an instance of this aggregator with no `Timer`.
`AbstractTimedAggregator(long interval)` Creates an aggregator which has a timer at the specified interval (miliseconds) and uses its own timer rather than the shared `MAIN_TIMER`.
`AbstractTimedAggregator(long interval, boolean useSharedTimer)` Creates an aggregator which has a timer at the specified interval and also allows control over using the `shared timer` or its own per-instance timer.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`add(T data)` Adds the data to this aggregator.
`void`	`addTimerListener(TimedAggregatorListener<T> listener)` If this `Aggregator` has been started with timer support, it will add the given listener, so it receives `timer events`.
`protected abstract void`	`doAdd(T data)` Function provided to allow subclasses to perform the actual adding of the data to the aggregator.
`protected abstract T`	`doEvaluate()` Allows subclasses to perform the actual evaluation of the aggregated result in a thread-safe manner.
`protected abstract void`	`doReset()` Function provided to allow subclasses to perform the actual reset of the aggregator.
`T`	`evaluate()` Aggregates all the data this object has been "fed" via calls to `add(Object)`.
`protected void`	`finalize()`
`int`	`getDataSize()` Retrieves the size of the currently-stored data series.
`long`	`getInterval()` Getter for `interval`.
`boolean`	`isSharedTimer()` Checks whether this instance uses its own timer or `the shared timer` for scheduling `the timer task`.
`boolean`	`isTimerEnabled()` Checks whether this instance has a timer associated with it or not.
`boolean`	`removeTimerListener(TimedAggregatorListener<T> listener)` Removes a listener from the timer listeners list if previously added.
`void`	`reset()` Resets this aggregator.This function first locks `dataLock` for writing then calls `doReset()`, which allows subclasses to perform the actual resetting of the aggregator and then at the end it unlocks `dataLock`.
`protected abstract int`	`retrieveDataSize()` Function provided to allow subclasses to retrieve the actual size of the data series.
`void`	`stop()` Cancels the current timer task (if set) -- which means from there on the data will not be reset anymore.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - NO_TIMER
```
public static final long NO_TIMER
```
    As per timer javadoc, if the interval specified is zero or less there will be no Timer created/assigned to this instance. This constant is defined to make it easier to read code which creates instances of this class and doesn't assign them a timer.
    
    See Also:
    Constant Field Values
  - TIMER_NAME
```
public static final String TIMER_NAME
```
    Name of the shared timer which will run all the TimerTasks resulted from creating instances of this class which are set to used the shared timer. This is useful when looking at thread dumps. For instances which use their own timer task, the name will be TIMER_NAME + hashCode().
    
    See Also:
    Constant Field Values
- Constructor Detail
  - AbstractTimedAggregator
```
public AbstractTimedAggregator()
```
    Default constructor -- creates an instance of this aggregator with no Timer. Equivalent to AbstractTimedAggregator(NO_TIMER).
    
    See Also:
    AbstractTimedAggregator(long)
  - AbstractTimedAggregator
```
public AbstractTimedAggregator(long interval)
```
    Creates an aggregator which has a timer at the specified interval (miliseconds) and uses its own timer rather than the shared MAIN_TIMER. Equivalent to AbstractTimedAggregator(interval,false).
    
    Parameters:
    interval - interval in miliseconds to set the timer for.
    See Also:
    interval, timer, AbstractTimedAggregator(long, boolean)
  - AbstractTimedAggregator
```
public AbstractTimedAggregator(long interval,
                       boolean useSharedTimer)
```
    Creates an aggregator which has a timer at the specified interval and also allows control over using the shared timer or its own per-instance timer.
    
    Parameters:
    interval - interval in miliseconds to set the timer for.
    useSharedTimer - if set to true, timer will be set to TIMER_NAME, otherwise a new instance of Timer will be created.
- Method Detail
  - getInterval
```
public final long getInterval()
```
    Getter for interval.
    
    Returns:
    Current value of interval.
  - add
```
public final void add(T data)
```
    Adds the data to this aggregator. This function first locks dataLock for writing then calls doAdd(Object), which allows subclasses to perform the actual adding to the aggregator and then at the end it unlocks dataLock.
    
    Specified by:
    
    add in interface Aggregator<T>
    
    Parameters:
    data - Data to be added to the aggregator.
    See Also:
    doAdd(Object), dataLock
  - doAdd
```
protected abstract void doAdd(T data)
```
    Function provided to allow subclasses to perform the actual adding of the data to the aggregator. This function is wrapped by add(Object) so that access to any internal data series (implemented by subclasses) via add(Object) or evaluate() or reset() is prohibited during this call, as a write lock is acquired prior to this function call to ensure this function is the only one which has access to the data.
    
    Parameters:
    data - Data to be aggregated
    See Also:
    add(Object)
  - evaluate
```
public final T evaluate()
```
    Aggregates all the data this object has been "fed" via calls to add(Object). Note that this object delegates the call to doEvaluate() after it secured read-only access to dataLock -- so any data series access can be safely read (however, subclasses should NOT try to modify any data series they might implement at this point!). The lock is released after doEvaluate() returns.
    
    Specified by:
    
    evaluate in interface NullaryFunction<T>
    
    Returns:
    result of aggregating the data, as returned by doEvaluate()
    See Also:
    doEvaluate()
  - doEvaluate
```
protected abstract T doEvaluate()
```
    Allows subclasses to perform the actual evaluation of the aggregated result in a thread-safe manner. When this function is called, write access to data (via add(Object) and reset()) is prohibited until this function finishes. However, please note that other read access (via calls to the same evaluate()) is possible.
    
    Returns:
    Result of evaluating the aggregated data
  - reset
```
public final void reset()
```
    Resets this aggregator.This function first locks dataLock for writing then calls doReset(), which allows subclasses to perform the actual resetting of the aggregator and then at the end it unlocks dataLock.
    
    Specified by:
    
    reset in interface Aggregator<T>
    
    See Also:
    doReset()
  - doReset
```
protected abstract void doReset()
```
    Function provided to allow subclasses to perform the actual reset of the aggregator. This function is wrapped by reset() so that access to data (via add(Object) or evaluate() or reset()) is prohibited during this call, as a write lock is acquired prior to this function call to ensure this function is the only one which has access to the data.
  - getDataSize
```
public final int getDataSize()
```
    Retrieves the size of the currently-stored data series. This function first locks dataLock for reading then calls retrieveDataSize(), which allows subclasses to compute the data series size and then at the end it unlocks dataLock.
    
    Returns:
    Size of the current data series, which will be aggregated at the next call to evaluate()
  - retrieveDataSize
```
protected abstract int retrieveDataSize()
```
    Function provided to allow subclasses to retrieve the actual size of the data series. This function is wrapped by getDataSize() so that access to data (via add(Object) or reset()) is prohibited during this call, as a read lock is acquired prior to this function call. (However, calls to evaluate() are allowed as that locks for reading too.)
    
    Returns:
    Size of the current data series. Zero means no data stored.
  - addTimerListener
```
public final void addTimerListener(TimedAggregatorListener<T> listener)
```
    If this Aggregator has been started with timer support, it will add the given listener, so it receives timer events. If no timer support has been configured for this Aggregator, this call has no effect.
    
    Parameters:
    listener - Listener to be added to received timer events from this aggregator.
    See Also:
    timerListeners
  - removeTimerListener
```
public final boolean removeTimerListener(TimedAggregatorListener<T> listener)
```
    Removes a listener from the timer listeners list if previously added. If this Aggregator has been configured with no timer support, this call will always return false.
    
    Parameters:
    listener - Listener to be removed from the list. NullPointerException thrown if this is null.
    
    Returns:
    true if this Aggregator has timer support and the listener passed in was previously added (via addTimerListener(TimedAggregatorListener)) or false if either the Aggregator has no timer support or it has timer support but the listener was never registered with this Aggregator.
    See Also:
    timerListeners
  - isTimerEnabled
```
public final boolean isTimerEnabled()
```
    Checks whether this instance has a timer associated with it or not. If there is a timer for this Aggregator, then the task member should be set to a non-null value.
    
    Returns:
    true if task is not null, false otherwise (in which case there is no timer).
  - isSharedTimer
```
public final boolean isSharedTimer()
```
    Checks whether this instance uses its own timer or the shared timer for scheduling the timer task.
    
    Returns:
    true if timer == MAIN_TIMER or false otherwise.
  - stop
```
public final void stop()
```
    Cancels the current timer task (if set) -- which means from there on the data will not be reset anymore. Also, if timer is not set to the shared timer then it will be cancelled as well Also releases all the listeners from the list.
  - finalize
```
protected final void finalize()
                       throws Throwable
```
    Overrides:
    
    finalize in class Object
    
    Throws:
    
    Throwable
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class AbstractTimedAggregator<T>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

NO_TIMER

TIMER_NAME

Constructor Detail

AbstractTimedAggregator

AbstractTimedAggregator

AbstractTimedAggregator

Method Detail

getInterval

add

doAdd

evaluate

doEvaluate

reset

doReset

getDataSize

retrieveDataSize

addTimerListener

removeTimerListener

isTimerEnabled

isSharedTimer

stop

finalize

toString