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

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

All Implemented Interfaces:

java.io.ObjectInputValidation, java.io.Serializable

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

Immutable value of a simple local or global system variable. This contains the type and value and date-of-change of a system variable.

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

The types of all legitimate values are immutable, thus preserving the immutability of instances of this class.

This class is not Internable because some fields are ignored by equals(); the value may be worth intern()ing however.

We ensure that the timestamp is unique (and monotonically increasing) in combination with the definition name for this class loader, so that in combination with an originating system ID value it should be possible to recognise and discard duplicate messages reasonably accurately without adding any more data to each message (eg some sort of unique ID which might be bulky and slow to create).

See Also:

Serialized Form

TIMESTAMP_TOLERANCE_MS

public static final int TIMESTAMP_TOLERANCE_MS

Effective tolerance in timestamp value (ms); non-negative. This allows us to produce timestamps slightly different to reported time by the number of miliseconds specified.

This allows values to be issued in (efficient) small bursts without pause, and allows for the fact that not all JVMs have a true 1ms clock tick, eg often granularity may be 10ms or 20ms or even more.

A value of 10 to 100 is probably reasonable, though this must remain much smaller than the skew tolerance to avoid confusion.

See Also:

Constant Field Values

_timestamps

private static final java.util.concurrent.ConcurrentMap<java.lang.String,java.util.concurrent.atomic.AtomicLong> _timestamps

Shared concurrent map from definition name to last-issued timestamp (null if none yet); never null. Used in conjunction with the various atomic primitives, this is thread-safe, lock-free and race-free.

Limited in size to the number of distinct definitions.

def

private final SimpleVariableDefinition def

The variable definition; never null.

value

private final java.lang.Object value

The variable value; null or a type allowed by the definition.

timestamp

private final long timestamp

The time at which the value object was constructed; strictly positive. This value comes with a deserialised object.

globalMap

private final java.util.Map<InstanceID,SimpleVariableValue> globalMap

An immutable Map from InstanceID keys to SimpleVariableValues each of the same definition and with no global map. This contains an encapsulation of the constiuent values from each particpating system.

It must be null for local variables.

For global variables where this is non-null it must contain only keys that are distinct InstanceID values, and only values that are SimpleVariableValues with exactly the same definition and a null globalMap.

Is immutable (if non-null) so that it can be returned directly.

Never an empty Map; null is used in this case.

compByDef

public static final java.util.Comparator<SimpleVariableValue> compByDef

A simple comparator that sorts by definition (and thus name) alone. This is useful for ordering values in lists when at most one of each type is present, eg for display or for compression sending over the wire.

serialVersionUID

private static final long serialVersionUID

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

See Also:

Constant Field Values

SimpleVariableValue

private SimpleVariableValue(SimpleVariableDefinition def,
                            java.lang.Object value,
                            java.util.Map<InstanceID,SimpleVariableValue> globalMap,
                            long timeStamp)
                     throws java.lang.IllegalArgumentException

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

This is private because though all parameters are checked we generally only want to add or remove map entries one at a time, and we want to handle timestamp values carefully.

We attempt to intern() the value to economise on memory if we think that it will be worthwhile to so do.

Parameters:

def - the variable definition; never null

value - the variable value; null or correct type

globalMap - if non-null the Map from InstanceID to SimpleVariableValue; a private copy is taken in the constructor and an empty Map is converted to a null

Throws:

java.lang.IllegalArgumentException - if the arguments are invalid

SimpleVariableValue

public SimpleVariableValue(SimpleVariableDefinition def,
                           java.lang.Object value)
                    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

value - the variable value; null or correct type

Throws:

java.lang.IllegalArgumentException - if the arguments are invalid

createUniqueTimestamp

private static long createUniqueTimestamp(SimpleVariableDefinition def)

Create the timestamp for a new message; strictly positive. The stream of timestamps produced is monotonically increasing separately for each definition, so although maximum message rate may be effectively capped for each definition, there is no interaction between independent variable/event streams.

This may wait to be able to create a new timestamp.

If the clock is set backwards this may wait a long time.

Returns:

positive partially-unique timestamp

getDef

public SimpleVariableDefinition getDef()

Get the variable definition; never null.

getValue

public java.lang.Object getValue()

Get the variable definition; null or a type allowed by the definition.

getTimestamp

public long getTimestamp()

Get the time at which the value object was constructed.

getGlobalMap

public java.util.Map<InstanceID,SimpleVariableValue> getGlobalMap()

Gets immutable Map from InstanceID to SimpleVariableValue; may be null or non-empty. Maps from the ID of the participating system that provided a value of this global to the value.

Never an empty Map.

shouldIntern

private static boolean shouldIntern(SimpleVariableDefinition def)

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

toString

public java.lang.String toString()

Human-readable summary of variable value. Simply the raw value rendered as a String.

This also makes it easy to use directly in (say) a JSP where if the variable is missing entirely we'll get a benign "null", and to render it simply we don't have to risk calling a method on a possibly null value.

Overrides:

toString in class java.lang.Object

getFullDescription

public java.lang.String getFullDescription()

Routine to print a full techie-readable description of a variable. This includes the definition, current value, timestamp, and all the globalMap values.

This will be a long (single line) of text with values embedded.

equals

public boolean equals(java.lang.Object obj)

Equality is based on the definition (name, type, etc) and value. The timestamp and globalMap values are ignored for the purposes of equality.

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 of the value.

Overrides:

hashCode in class java.lang.Object

put

public SimpleVariableValue put(InstanceID client,
                               SimpleVariableValue mapEntryValue)

Make a new value identical except for a new/updated globalMap mapping. The new instance has a globalMap which contains the mapping from client to value, creating the Map if need be, and adding or replacing a mapping for client as required.

Both the client and value must be non-null, and the value:

• must not have a globalMap
• must have the same definition (or an equal one).

put

public SimpleVariableValue put(InstanceID client,
                               SimpleVariableValue mapEntryValue,
                               boolean useNewValue)

Make a new value identical except for a new/updated globalMap mapping. The new instance has a globalMap which contains the mapping from client to value, creating the Map if need be, and adding or replacing a mapping for client as required.

Both the client and value must be non-null, and the value:

• must not have a globalMap
• must have the same definition (or an equal one).

  Parameters:

  useNewValue - if true, the basic value and timestamp are taken from the new map entry, rather than from this

removeAllKeysOlder

public SimpleVariableValue removeAllKeysOlder(long oldestAllowed)

Return instance with all mappings older than specified limit removed. The argument is a time, presumably in the past.

Used for trimming away data from dead systems.

Returns unchanged any instance with a null or empty globalMap, or where all of the keys in the globalMap are in the specified Set. Else returns a new, modified value.

Parameters:

oldestAllowed - any key older than this excluded from the result

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