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

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

All Implemented Interfaces:

java.io.ObjectInputValidation, java.io.Serializable

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

Thread-safe mutable value of a local or global system event variable. This is the mutable version of EventVariableValue as StringBuilder is to String.

The current stats should be collected in instances of this, then converted to EventVariableValue for longer-term storage and/or to return to users.

This is designed to be efficient and quick to mutate.

This class is thread-safe, and methods may be synchronized.

This attempts to conserve memory, at the cost of some CPU time, by attempting to effectively intern() event values. This therefore assumes that all event values are sensibly intern()able, eg immutable and with equals() and hashCode() methods that cover all visible state.

See Also:

Serialized Form

evvCache

private transient EventVariableValue evvCache

Private cache for toEventVariableValue(). Cleared on any change to the buffer, ie a new event or a merge.

Avoids having to expensively recreate a new evv when nothing has changed.

We do not serialise/persist this redundant state.

def

private final SimpleVariableDefinition def

The (immutable) variable definition; never null.

period

private final EventPeriod period

The (immutable) event period; never null.

intervalNumber

private final long intervalNumber

The (immutable) interval number; strictly positive.

totalEventCount

private int totalEventCount

Total event count; non-negative. Initially zero.

Mutable; accessed under the instance lock.

counts

private java.util.Map<java.lang.Object,EventVariableValueBuffer.Count> counts

Map from event value to count of events of that value. Initially empty.

Not thread-safe (access should be protected by other means).

REPLACE_ON_UPDATE

private static final boolean REPLACE_ON_UPDATE

If true, replace our data rather than merge on update().

See Also:

Constant Field Values

serialVersionUID

private static final long serialVersionUID

Unique Serialisation class ID generated by http://random.hd.org/.

See Also:

Constant Field Values

EventVariableValueBuffer

public EventVariableValueBuffer(SimpleVariableDefinition def,
                                EventPeriod period,
                                long intervalNumber)
                         throws java.lang.IllegalArgumentException

Construct a single variable value. This type-checks the value, vetoing construction if invalid.

Parameters:

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

period - the event period for this sample; never null

intervalNumber - the period number, zero means "all"; non-negative

Throws:

java.lang.IllegalArgumentException - if the arguments are invalid

toEventVariableValue

public EventVariableValue toEventVariableValue()

Convert to (immutable) non-authoritative EventVariableValue. If the cached value is non-null then we return that, else we compute it, cache it, and return it.

getDef

public SimpleVariableDefinition getDef()

Get the variable definition; never null.

getPeriod

public EventPeriod getPeriod()

Get the event period; never null.

getIntervalNumber

public long getIntervalNumber()

Get the interval number; strictly positive.

getTotalEventCount

public int getTotalEventCount()

Get the total event count; non-negative.

toString

public java.lang.String toString()

Generate human-readable summary of state.

Overrides:

toString in class java.lang.Object

addEvent

public void addEvent(SimpleVariableValue svv)

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

The total event count is incremented and if appropriate the value and/or count of occurrences of that value will be incremented.

Note that null values are not recorded in the map, but the totalCount is still incremented.

If the totalEventCount would be about to overflow, then we halve it and halve the count of all extant entries (removing any that become zero).

Parameters:

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

update

public void update(EventVariableValue upstream)

Update/merge the value with upstream data. This is taken to be a set of (usually non-authoritative) values from upstream which possible contains the events from all (or more) participants in the distributed system.

We compute an approximate merge, which is assumed to be OK to do at all but the master node since downstream nodes will eventually get overridden with correct authoritative values from upstream.

The approximation consists of increasing the event count to the maximum found in this item and the supplied value, and then adjusting the total event count suitably (allowing for events not stored as values in the map) This may result in a total event count higher than either this or the upstream data.

This should not be used at the very top-level master store to avoid double-counting values, etc.

This may be quite slow.

compactValue

private java.lang.Object compactValue(boolean shouldIntern,
                                      java.lang.Object value)

Return the compacted form of a value or the original, possibly intern()ing.

equals

public boolean equals(java.lang.Object obj)

Equality is based on the definition, period and interval number, but not the event values.

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

The hash is built on a subset of the fields. This implementation uses the hash of the definition and the interval number and period values.

Overrides:

hashCode in class java.lang.Object

readObject

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

Deserialise.

Throws:

java.io.IOException

java.lang.ClassNotFoundException

writeObject

private void writeObject(java.io.ObjectOutputStream oos)
                  throws java.io.IOException

Customise how we save state when serialising.

Throws:

java.io.IOException

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