org.hd.d.pg2k.svrCore.vars
Class EventVariableValuePeriodRow

java.lang.Object
  org.hd.d.pg2k.svrCore.vars.EventVariableValuePeriodRow

All Implemented Interfaces:

java.io.ObjectInputValidation, java.io.Serializable

public final class EventVariableValuePeriodRow
extends java.lang.Object
implements java.io.Serializable, java.io.ObjectInputValidation

Current and historical entries for one event forming one "row". This is mutable and used to hold live event stats in memory.

This maintains state incrementally on each new event, for example, shuffling out and discarding old historical event values if need be.

Thread-safe, with methods synchronized as necessary.

Serializable for direct persistence if required, though an XML format rather than a binary one would probably be more robust.

See Also:

Serialized Form

def

private final SimpleVariableDefinition def

The variable definition; never null.

period

private final EventPeriod period

The event period; never null.

all

private EventVariableValueBuffer all

All events being collected, never null. Captures all events ever seen, but may be rescaled to prevent overflow, so should simply be regarded as a reasonably representative sub-sample.

Will never be authoritative.

current

private EventVariableValueBuffer current

"Current" events being collected, never null. Will be replaced with new instance as the current one stops being current.

Initially created with value suitable to receive a new event immediately.

Will never be authoritative.

historical

private final EventVariableValue[] historical

Set of "historical" periods, most-recent at index 0, possibly containing nulls; never null. Initially all nulls.

The intervalNumber of any entry at index i must be current.getIntervalNumber()-1-i.

FIXME: copy defensively during deserialisation.

_NO_EVENT_VALUES

static final EventVariableValue[] _NO_EVENT_VALUES

Zero-length array corresponding to "no results", immutable so made available to the package; non-null.

serialVersionUID

private static final long serialVersionUID

Unique Serialisation class ID.

See Also:

Constant Field Values

EventVariableValuePeriodRow

public EventVariableValuePeriodRow(SimpleVariableDefinition def,
                                   EventPeriod period)
                            throws java.lang.IllegalArgumentException

Construct a single event variable value period "row".

Parameters:

def - the variable definition; never null and must be an event

period - the event period for this sample; never null

Throws:

java.lang.IllegalArgumentException - if the arguments are invalid

getDef

public SimpleVariableDefinition getDef()

Get the variable definition; never null.

getPeriod

public EventPeriod getPeriod()

Get the event period; never null.

addEvent

public void addEvent(SimpleVariableValue svv)

Record/add event to the tally for this period. Note that the event must match the definition that this instance is constructed with or an IllegalArgumentException will be thrown.

If the "current" event buffer is too old to accept this incoming event, we move all the historical data up and insert an immutable copy of the buffered data as appropriate (though we must cope with the case where we have to move data up several slots due to an extended interval between updates).

Parameters:

svv - event to be recorded; must be non-null and of event type

_canonicaliseState

private void _canonicaliseState()

Canonicalise our internal state, so that the current event collector covers "now". If current event collector is too old, then create a new one and age the historical data. If the clock seems to have gone backwards for whatever reason, we'll simply carry on collecting as we were until things get sane.

getEventValues

EventVariableValue[] getEventValues(long firstIntervalNumber,
                                    java.util.BitSet whichValues)

Get the specified event sets for the specified intervals; never null. This allows retrieval of zero or more event sets for the specified interval size.

Requests for more than SystemVariables.EVENT_SAMPLES_RETAINED in the past (or for the future!) cannot be satisfied and data will not be returned for them.

Usually not more than SystemVariables.EVENT_SAMPLES_RETAINED samples will be returned in response to any one request as a safety measure.

Parameters:

firstIntervalNumber - the number of the first interval for which data is potentially required; if too far in the past or future then possibly no data will be available; using zero accesses the "all" bucket

whichValues - each true bit represents a slot for which data is required, bit 0 indicating data from the slot within which firstIntervalTime is located, bit 1 the previous slot, etc

Returns:

as many of the requested values as available, at least long enough to return all the available values, with [0] corresponding to bit 0 in the BitSet; may contain nulls or be zero-length but is never null

setEventValue

public void setEventValue(EventVariableValue evv)

Set/override the specified event sets for the specified intervals; never null. This is used to set values that have been fetched from upstream (ie closer to the master data store).

This may ignore the call, and certainly will if the intervalNumber is outside the current time window it holds.

This will generally accept the value and store it if:

• The intervalNumber is within the current window.
• The intervalSelector is a period for which this event has data.
• The supplied value is "better" than any current one held, ie:
  • We hold a null and evv is non-null.
  • We hold a non-authoritative value and evv is authoritative.
  • The authoritative-ness is the same bu we hold an entry with a lower total count than evv.

  Parameters:

  evv - non-null event value

readObject

private void readObject(java.io.ObjectInputStream ois)
                 throws java.io.IOException,
                        java.lang.ClassNotFoundException

Deserialise.

Throws:

java.io.IOException

java.lang.ClassNotFoundException

validateObject

public void validateObject()
                    throws java.io.InvalidObjectException

Check that the object state is consistent and legal. Is synchronized to prevent changes of state while this instance is examined.

Specified by:

validateObject in interface java.io.ObjectInputValidation

Throws:

java.io.InvalidObjectException