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

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

All Implemented Interfaces:

java.io.ObjectInputValidation, java.io.Serializable

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

Immutable value of a local or global system event variable. This contains the type/definition plus a total event count and a Map of event values.

To retrieve the very latest value that was set a SimpleVariableValue should be retrieved instead.

This is serialisable to enable it to be sent over network connections, persisted, etc.

Note that the interval number is strictly positive, the interval number multiplied by the period is the starting time of the interval in ms, and the starting time is always representable as a positive long.

May hold state in a compacted form internally to reduce memory footprint. In particular, String values may be held as more compact CharSequence forms, though are returned, matched and serialised as String.

See Also:

Serialized Form

SV_COMPARATOR

static final java.util.Comparator<java.lang.CharSequence> SV_COMPARATOR

Case-sensitive comparator for nominally String-type values, even mixed compact and raw String items; not null.

NO_VALUES

private static final java.lang.Object[] NO_VALUES

Private shared (immutable) value meaning no values, to save memory.

NO_COUNTS

private static final int[] NO_COUNTS

Private shared (immutable) value meaning no counts, to save memory.

def

private SimpleVariableDefinition def

The variable definition; never null.

period

private EventPeriod period

The event period; never null.

intervalNumber

private long intervalNumber

The interval number; strictly positive.

authoratitive

private boolean authoratitive

If true, this variable has come from the authoritative end-point. Due to an old typo now fossilised in old data, the spelling of this should remain "authoratitive" even though wrong! Thank goodness for encapsulation!

totalEventCount

private int totalEventCount

Total event count; non-negative.

counts

private int[] counts

Counts of the different (non-null) values in non-increasing-count order (ie best first); never null. All counts are non-negative.

Same length as values[].

values

private java.lang.Object[] values

Values of the different (non-null) events in non-increasing-count order (ie best first); never null. All values are non-null and valid values as determined by the def though note that some values may be substituted with compact alternatives.

Same length as counts[].

The general case is that a value's rank is its position in this array.

valuesSortedRank

private transient volatile short[] valuesSortedRank

Rank of each item in valuesSorted[]; CURRENTLY never null after construction. All access should be via getValuesSortedRank() (with the value set by _compactAndSort()) so that this can be lazily created in future.

Marked volatile for thread-safe lock-free access.

LAZY_SORT

static final boolean LAZY_SORT

If true then defer (expensive) sorting where possible. Even if we are compressing internal state, if all values appear to be in a compressed form already, then we can postpone sorting until the first direct use of the sorted state.

See Also:

Constant Field Values

COMPRESS_INTERNAL_STATE

static final boolean COMPRESS_INTERNAL_STATE

If true then try to compress the internal in-memory state to reduce footprint. All APIs and the serialised form remain unchanged.

This flag may also be used by EventVariableValueBuffer to optimise its internal state and interactions with this class; thus package-visible.

See Also:

Constant Field Values

AVOID_RECOMPRESSING

static final boolean AVOID_RECOMPRESSING

If true then avoid attempting to re-compact already nominally compact data. This may lose a little potential compression, but save a great deal of time.

See Also:

Constant Field Values

serialVersionUID

private static final long serialVersionUID

Unique Serialisation class ID.

See Also:

Constant Field Values

EventVariableValue

public EventVariableValue(boolean isAuthoritative,
                          SimpleVariableDefinition def,
                          EventPeriod period,
                          long intervalNumber,
                          int totalEventCount,
                          java.lang.Object[] values,
                          int[] counts)
                   throws java.lang.IllegalArgumentException

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

May attempt to compact and/or intern() key values to minimise memory consumption at the cost of some performance at construction/deserialisation/access.

Parameters:

isAuthoritative - if true, this is authoritative data from the master data store

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

period - the event period for this sample; never null

intervalNumber - the period number; strictly positive

totalEventCount - the total event count; non-negative

values - event values in decreasing order of count; null == empty, not containing duplicates, same length as counts[] argument

counts - event counts for each item in values[], in non-increasing order, with a sum no more than total-event count; null == empty, not containing negative values, same length as values[]

Throws:

java.lang.IllegalArgumentException - if the arguments are invalid

EventVariableValue

EventVariableValue(boolean isAuthoritative,
                   SimpleVariableDefinition def,
                   EventPeriod period,
                   long intervalNumber,
                   int totalEventCount,
                   java.lang.Object[] valuesIn,
                   int[] countsIn,
                   boolean tryIntern)

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

May attempt to effectively intern() key values to minimise memory consumption at the cost of some performance at construction/deserialisation.

Package-visible so that only classes in this package (that we trust) can avoid having their values intern()ed.

Parameters:

isAuthoritative - if true, this is authoritative data from the master data store

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

period - the event period for this sample; never null

intervalNumber - the period number; strictly positive

totalEventCount - the total event count; non-negative

valuesIn - event values in decreasing order of count; null == empty, not containing duplicates, same length as counts[] argument

countsIn - event counts for each item in values[], in non-increasing order, with a sum no more than total-event count; null == empty, not containing negative values, same length as values[]

tryIntern - if false then we do not try hard to intern()/compress any of the values

Throws:

java.lang.IllegalArgumentException - if the arguments are invalid

_compactAndSort

private void _compactAndSort(SimpleVariableDefinition def,
                             boolean tryIntern)

Creates _valuesSortedRank[] and compacts values[] as a side-effect if needed.

allowCompactStringValues

static boolean allowCompactStringValues(SimpleVariableDefinition def)

If true then Name is a valid value type (in lieu of String). This may also be used by EventVariableValueBuffer to optimise its internal state and interactions with this class; thus package-visible.

shouldIntern

static boolean shouldIntern(SimpleVariableDefinition def)

Returns true if we should probably automatically intern() the value. We will do this if the value is likely to be bulky (eg is a String), or may be long-lived (eg persistent) or in multiple copies.

makeAuthoritative

public EventVariableValue makeAuthoritative()

Return a (new) authoritative value with the same content as the current value; never null. This instance is unaltered, and it and the value returned remain immutable, though they may or may not share state.

(If this instance is already authoritative, then "this" is returned to avoid wasting memory.)

Returns:

instance with "authoritative" flag set

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.

isAuthoritative

public boolean isAuthoritative()

Returns true if this variable has come from the authoritative end-point.

getTotalEventCount

public int getTotalEventCount()

Get the total event count; non-negative.

getValuesSortedRank

private short[] getValuesSortedRank()

Get rank of each values[] item in sorted order; never null. Will do sorting and compaction if not already done.

toString

public java.lang.String toString()

Generate human-readable summary of important state.

Overrides:

toString in class java.lang.Object

getIndexInSortedValues

private int getIndexInSortedValues(java.lang.Object key)

Return the index in a sorted version of values[] of the given value/key; -negative if not present. This works indirectly via the valuesSortedRank() array.

getTotalDistinctValues

public int getTotalDistinctValues()

Get total number of distinct event values recorded; non-negative.

getDistinctValuesInRankOrder

public java.util.List<java.lang.Object> getDistinctValuesInRankOrder()

Get an immutable RandomAccess List of the distinct values in rank order; never null but may be empty. This is very lightweight, and preferable to (say) getDistinctValuesSorted() if only the values are required.

getDistinctValuesSorted

public java.util.List<java.lang.Object> getDistinctValuesSorted()

Get an immutable RandomAccess List of the distinct values in value-sorted order; never null but may be empty. This is fairly lightweight, and preferable to (say) getInfo().keySet() if only the values are required.

getCount

public int getCount(java.lang.Object value)
             throws java.lang.IllegalArgumentException

Get count of this event value; never negative. A result of zero may indicate either that no events with the specified value were seen, or that they were seen but were later displaced due to capacity limits.

Throws:

java.lang.IllegalArgumentException - if the argument is null or not a legal type/value

checkExternalLookupValueTypeAndNonNull

private void checkExternalLookupValueTypeAndNonNull(java.lang.Object value)
                                             throws java.lang.IllegalArgumentException

Checks that the supplied value is non-null and a legitimate value of the definition. Where internal value compression is in place then this may accept the compact form where appropriate.

Throws:

java.lang.IllegalArgumentException

getRank

public int getRank(java.lang.Object value)
            throws java.lang.IllegalArgumentException

Get rank/ranking of this event value; never negative. Zero means the highest count of all values seen, one means the next highest, etc. So low values are good.

If we have no count recorded for this value, ie no ranking, the routine returns Integer.MAX_VALUE.

Throws:

java.lang.IllegalArgumentException - if the argument is null or not a legal type/value

convertValueToPrimaryForm

private java.lang.Object convertValueToPrimaryForm(java.lang.Object o)

Convert value to primary form.

convertValueToPrimaryFormNoIntern

private java.lang.Object convertValueToPrimaryFormNoIntern(java.lang.Object o)

Convert value to primary form, NOT intern()ing any generated String values as assumed short-lived.

getValueByRank

public java.lang.Object getValueByRank(int rank)

Get value by rank.

Parameters:

rank - of value to select in range [0,getTotalDistinctValues()-1]

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the rank is out of bounds

getValueByRankNoIntern

public java.lang.Object getValueByRankNoIntern(int rank)

Get value by rank and do not intern() any on-the-fly generated values as assumed to be short-lived.

Parameters:

rank - of value to select in range [0,getTotalDistinctValues()-1]

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the rank is out of bounds

getCountByRank

public int getCountByRank(int rank)

Get count by rank; strictly positive.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the rank is out of bounds

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

writeObject

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

Customise how we save state when serialising.

Throws:

java.io.IOException

readObject

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

Deserialise. This explicitly recovers state for fields by name.

This does not attempt to build some of the transient state assembled by the constructor, nor do defensive copying or significant validation.

Throws:

java.io.IOException

java.lang.ClassNotFoundException

readResolve

protected java.lang.Object readResolve()

Deserialise: use constructor for validation, defensive copying, conversion from old formats, etc. Also allows us to intern() keys, etc, to conserve memory.

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