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

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

All Implemented Interfaces:

java.io.ObjectInputValidation, java.io.Serializable

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

Current and historical entries for all periods/intervals one event forming one "set". 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.

Mutator calls are synchronized, so that serialisation can take place on an instance providing that a lock is held on that instance.

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

Notes the last time an event was add()ed or a whole slot value was "set" so as to allow an observer to tell quickly when this instance may need a save.

See Also:

Serialized Form

def

private final SimpleVariableDefinition def

The variable definition; never null.

byPeriod

private final java.util.EnumMap<EventPeriod,EventVariableValuePeriodRow> byPeriod

Non-empty Map from period to period row; never null. Logically immutable once created (and thus thread-safe), though the values remain mutable.

lastEventTime

private transient volatile long lastEventTime

Time last event was added, or zero if none recorded or instance just deserialised. Is transient (not retained though serialisation).

Is volatile to allow access without a lock.

serialVersionUID

private static final long serialVersionUID

Unique Serialisation class ID.

See Also:

Constant Field Values

EventVariableValueSet

public EventVariableValueSet(SimpleVariableDefinition def)
                      throws java.lang.IllegalArgumentException

Construct a single event variable value set (for all periods/intervals).

Parameters:

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

Throws:

java.lang.IllegalArgumentException - if the arguments are invalid

EventVariableValueSet

private EventVariableValueSet(SimpleVariableDefinition def,
                              java.util.EnumMap<EventPeriod,EventVariableValuePeriodRow> byPeriod)
                       throws java.lang.IllegalArgumentException

Constructor for defensive copying on deserialisation.

Parameters:

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

byPeriod - the extant mapping from period to "period row" entries; never null

Throws:

java.lang.IllegalArgumentException - if the arguments are invalid

getDef

public SimpleVariableDefinition getDef()

Get the variable definition; never null.

getLastEventTime

public long getLastEventTime()

Get time last event was added, or zero if none recorded or instance just deserialised.

addEvent

public void addEvent(SimpleVariableValue svv)

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

Note that for some types, not all periods/intervals are selected, ie we record data for some periods and not others.

Updates the lastEventTime to the current time.

Parameters:

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

getEventValues

EventVariableValue[] getEventValues(EventPeriod intervalSelector,
                                    long intervalNumber,
                                    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.

If data is requested for an interval/period excluded in the definition, an empty array is returned.

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

Parameters:

intervalSelector - never null

intervalNumber - 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

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

readResolve

protected java.lang.Object readResolve()

Deserialise: use constructor for validation, defensive copying, etc.

validateObject

public void validateObject()
                    throws java.io.InvalidObjectException

Check that the object state is consistent and legal.

Specified by:

validateObject in interface java.io.ObjectInputValidation

Throws:

java.io.InvalidObjectException