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

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

All Implemented Interfaces:

java.io.ObjectInputValidation, java.io.Serializable, java.lang.Comparable<SimpleVariableDefinition>, MemoryTools.Internable

public final class SimpleVariableDefinition
extends java.lang.Object
implements java.io.Serializable, java.io.ObjectInputValidation, MemoryTools.Internable, java.lang.Comparable<SimpleVariableDefinition>

Immutable definition of a simple local or global system variable. This defines the type, default value, scope, writability, etc of a single system variable.

Some variables may also be events, and gain some extra functionality such as a record of the values over time.

Names of variables are in the same scheme as Java properties and class names, ie structured hierarchical alphanumeric ASCII strings, with sections separated by "." dots, and with the more significant components on the left.

These variables may be limited in scope to a single JVM, or may be global, or may have local values that are automatically merged into a global version.

(We may in future allow these definitions to be provided centrally and distributed via GenProps, for example, possibly merged with or filtered by a built-in set, if we have the need and can avoid security issues for example.)

The Comparable ordering is on the name; behaviour is undefined if two different variable definitions with the same name are compared.

See Also:

Serialized Form

EVENT_ABS_MAX_DIFF_VALUES

public static final int EVENT_ABS_MAX_DIFF_VALUES

Absolute maximum different event values that can be held; strictly positive. Individual event variables may impose a smaller limit; this is here to impose a bearable upper limit on system resources.

This should probably not be lots smaller than the number of exhibits, for example to allow accurate retention of sparse votes.

Small enough that that rank (etc) can be stored as a short rather than int to reduce footprint.

See Also:

Constant Field Values

name

private final java.lang.String name

The variable name; never null or empty.

type

private final int type

The variable type; one of the TYPE_XXX values.

persistent

private final boolean persistent

True if the variable value is to persist through restarts.

readOnly

private final boolean readOnly

True if the variable is read-only; defaults to false.

event

private final boolean event

True if the variable is read-only; defaults to false.

evPeriodSubset

private final java.util.EnumSet<EventPeriod> evPeriodSubset

Event period/interval subset (immutable) to be collected, or null if not an event or all to be collected. If this is non-null then it is non-empty.

local

private final boolean local

True if the variable is local; defaults to true.

maxDiffEventCount

private final int maxDiffEventCount

Maximum number of different event values retained; defaults to 0.

MAX_NAME_LEN

public static final int MAX_NAME_LEN

Put a (high) upper bound on name length in character; strictly positive. This is much longer than we ever expect to use, and is mainly to reduce the possibility of accidents, for example during deserialisation.

Limiting this also makes it more likely that we can use an event name as part of a filename on a range of systems, eg *nix and Windows.

We will apply this to (String) event values too.

See Also:

Constant Field Values

TYPE_NONE

public static final int TYPE_NONE

Variable type: "none"; can only be null.

See Also:

Constant Field Values

TYPE_IID

public static final int TYPE_IID

Variable type: InstanceID; can only be of type InstanceID.

See Also:

Constant Field Values

TYPE_STRING

public static final int TYPE_STRING

Variable type: String; can only be of type java.lang.String.

See Also:

Constant Field Values

TYPE_NUMBER

public static final int TYPE_NUMBER

Variable type: Number; can only be of type java.lang.Number. In practice, for security reasons, only java.lang.* implementation types are allowed.

See Also:

Constant Field Values

TYPE__MIN

public static final int TYPE__MIN

Minimum legal TYPE_XXX value.

See Also:

Constant Field Values

TYPE__MAX

public static final int TYPE__MAX

Maxiumum legal TYPE_XXX value.

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

SimpleVariableDefinition

public SimpleVariableDefinition(java.lang.String name,
                                int type,
                                boolean local,
                                boolean persistent,
                                boolean readOnly,
                                boolean event,
                                int maxDiffEventCount,
                                java.util.EnumSet<EventPeriod> evPeriodSubset)
                         throws java.lang.IllegalArgumentException

Construct a single variable definition.

Parameters:

name - the variable name; never null or empty

type - the variable type; one of the TYPE_XXX values

persistent - if true then the value persists through a system/JVM restart if possible; usually false

readOnly - if true then the variable can never be explicitly set; it might be synthesised by specialised getter methods, for example

event - true if this is an event rather than just a simple value

maxDiffEventCount - maximum number of different event values recorded; never negative, must be zero for non-event variables

evPeriodSubset - for an event non-empty set of periods/intervals for which events are records (null means all periods/intervals); must be null if not an event

Throws:

java.lang.IllegalArgumentException - if the arguments are invalid

SimpleVariableDefinition

public SimpleVariableDefinition(java.lang.String name,
                                int type)
                         throws java.lang.IllegalArgumentException

Simplified constructor setting many of the typical defaults. Essentially a local, read-write, non-persistent value.

Parameters:

name - the variable name; never null or empty

type - the variable type; one of the TYPE_XXX values

Throws:

java.lang.IllegalArgumentException - if the arguments are invalid

getName

public java.lang.String getName()

Get the variable name; never null or empty.

getType

public int getType()

Get the variable type; one of the TYPE_XXX values.

isPersistent

public boolean isPersistent()

Get the veriable persistence; defaults to false.

isReadOnly

public boolean isReadOnly()

Get the variable writablity; true if read-only.

isEvent

public boolean isEvent()

True if this reprents an event rather than a simple value.

getEvPeriodSubset

public java.util.Set<EventPeriod> getEvPeriodSubset()

Get unmodifiable view of the event period/interval subset to be collected, or null if not an event or all event periods to be collected. Returns a read-only view to protect our internal state.

isLocal

public boolean isLocal()

Get the variable scope; true if local. Local values never get propagated out of their local system (often JVM), and don't get merged into a map, and are thus cheaper and simpler to manage than globalmap values.

Returns:

true if this is a local variable

getMaxDiffEventCount

public int getMaxDiffEventCount()

Get maximum number of different event values retained; non-negative, zero if not an event

checkType

public boolean checkType(java.lang.Object value)

Checks the type of the value passed is valid for this definition. Note that null is always a valid value for any var type.

Returns:

true if value is of valid type for this definition, false otherwise

toString

public java.lang.String toString()

Human-readable summary of variable definition.

Overrides:

toString in class java.lang.Object

compareTo

public int compareTo(SimpleVariableDefinition o)

Comparable ordering is on name alone in default String order.

Specified by:

compareTo in interface java.lang.Comparable<SimpleVariableDefinition>

equals

public boolean equals(java.lang.Object o)

Equality is based on the name and all the other parameters; ie equal definitions are identical. This definition of equals() allows use of MemoryTools.intern().

This tests fields in an order likely to give the best performance.

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

The hash is built on a subset of the fields. This implementation just uses the hash of the name.

Overrides:

hashCode in class java.lang.Object

readResolve

protected java.lang.Object readResolve()
                                throws java.io.ObjectStreamException

Deserialise: use constructor for validation, defensive copying, etc. We also use this to eliminate duplicate copies and thus conserve memory. We attempt to effectively intern() the entire definition and also the name.

Returns:

identical, de-duped, defensively-copied, non-null instance

Throws:

java.io.ObjectStreamException

validateObject

public void validateObject()
                    throws java.io.InvalidObjectException

Specified by:

validateObject in interface java.io.ObjectInputValidation

Throws:

java.io.InvalidObjectException