com.bigdata.counters
Class History<T>

java.lang.Object
  com.bigdata.counters.History<T>

Type Parameters:

T - Which must be Double, Long, or String.

public class History<T>
extends Object

Retains history for N periods, where the period is expressed in milliseconds.

This class is thread-safe.

Version:

$Id: History.java 2265 2009-10-26 12:51:06Z thompsonbry $

Author:

Bryan Thompson

Nested Class Summary

class

History.SampleIterator Takes a snapshot of the samples in the History and then visits those samples.

Field Summary

protected static org.apache.log4j.Logger

log

Constructor Summary

protected	History(int capacity, History<T> source) Constructor used when aggregating from another collection period.
	History(T[] data, long period, boolean overwrite) Constructor used at the base collection period.

Method Summary

void	add(long timestamp, T value) Adds a sample to the history.
int	capacity() The #of samples that can be stored in the buffer.
T	getAverage() Computes the average of the samples.
T	getAverage(int nperiods) Compute the average of the samples over the last N reporting periods.
long	getPeriod() The period in milliseconds between each sample in the buffer.
IHistoryEntry<T>	getSample() Return a snapshot of the most recent value in the buffer -or- null if there are no samples in the buffer.
protected History<T>	getSink() The sink on which the history writes when it overflows -or- null if no sink has been assigned (it is assigned by the alternate ctor).
History	getSource() The source History which feeds this one.
Class	getValueType() The datatype for the individual values.
boolean	isDouble()
boolean	isLong()
boolean	isNumeric()
History.SampleIterator	iterator() Visits a snapshot of the samples in the buffer in timestamp order.
int	size() The #of non-missing samples that are stored in the buffer.
String	toString() Return a representation of a snapshot of the samples in buffer.
protected T	valueOf(double d) Convert a double to an instance of the generic type parameter for this class.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

log

protected static final org.apache.log4j.Logger log

Constructor Detail

History

public History(T[] data,
               long period,
               boolean overwrite)

Constructor used at the base collection period.

Parameters:

data - An array whose size is the capacity of the history buffer. The contents of the array will be used to store the data. (This API requirement arises since generics are fixed at compile time rather than runtime.)

period - The period covered by each slot in milliseconds.

overwrite - true iff overwrite of slots in the buffer is allowed (when false the buffer will fill up and then refuse additional samples if they would overwrite slots which are in use).

History

protected History(int capacity,
                  History<T> source)

Constructor used when aggregating from another collection period.

Parameters:

capacity - The #of slots in the history.

source - The source whose values are aggregated each time its history overflows.

Method Detail

getPeriod

public long getPeriod()

The period in milliseconds between each sample in the buffer. The buffer will not accept the next sample until this period has elapsed.

getSource

public History getSource()

The source History which feeds this one.

Returns:

The source History -or- null iff this is the base History.

capacity

public int capacity()

The #of samples that can be stored in the buffer.

size

public int size()

The #of non-missing samples that are stored in the buffer.

isNumeric

public boolean isNumeric()

isLong

public boolean isLong()

isDouble

public boolean isDouble()

getValueType

public Class getValueType()

The datatype for the individual values.

getSample

public IHistoryEntry<T> getSample()

Return a snapshot of the most recent value in the buffer -or- null if there are no samples in the buffer.

iterator

public History.SampleIterator iterator()

Visits a snapshot of the samples in the buffer in timestamp order. This includes all non-missing samples over the last N periods, where N is the capacity of the buffer.

toString

public String toString()

Return a representation of a snapshot of the samples in buffer.

Overrides:

toString in class Object

getAverage

public T getAverage()

Computes the average of the samples.

Returns:

The average -or- null if the samples are not numbers (no average is reported for dates, strings, etc).

TODO:

could report the most frequent value for non-numeric data or a list of the distinct values.

getAverage

public T getAverage(int nperiods)

Compute the average of the samples over the last N reporting periods.

Parameters:

nperiods - The #of reporting periods over which the average is to be computed. E.g., last 10 minutes. The reporting periods have to be read from the logicalSlot for 10 minutes ago up through the current logicalSlot.

Returns:

The average over the last N reporting periods.

Throws:

IllegalArgumentException - If you request data that is older (in reporting periods) that is stored within the history. E.g., you can not ask for more than a 60 minute average if the reporting period is minutes and the capacity is 60.

valueOf

protected T valueOf(double d)

Convert a double to an instance of the generic type parameter for this class.

Parameters:

d - The double value.

Returns:

The corresponding instance of the generic type parameter.

add

public void add(long timestamp,
                T value)

Adds a sample to the history. The sample is placed into a slot in this history that reflects its timestamp.

If the history wraps around into the next period and there is another history that aggregates this one, then the average for the last period will be added to the aggregating history.

Multiple samples in the same period are recorded as (a) the total of those samples in the period; and (b) the #of samples in the period.

Parameters:

timestamp - The timestamp associated with the sample.

value - The sampled value.

Throws:

IllegalArgumentException - if the timestamp is non-postitive.

TimestampOrderException - if the timestamp is way out of the current range for the history buffer.

getSink

protected History<T> getSink()

The sink on which the history writes when it overflows -or- null if no sink has been assigned (it is assigned by the alternate ctor).