org.hd.d.pg2k.svrCore.vars
Interface BasicVarMgrInterface

All Known Subinterfaces:

SimpleExhibitPipelineIF, SimpleVariablePipelineIF

All Known Implementing Classes:

AHStandaloneMain.FakeTunnel, BasicVarMgr, DataSourceBean, ExhibitDataFileSource, ExhibitDataHTTPTunnelSource, ExhibitDataSimpleCache, ExhibitDataTunnelSource, PipelineVarMgr, SimpleCacheTest.DataConcurrencyAccessMonitor, SimpleCacheTest.DummyDataSource, SimpleCacheTest.RawDataAccessMonitor, SimpleExhibitPipelineFilter, SystemVariablesTest.BasicVarMgrEndpoint, SystemVariablesTest.EventValueRequestMonitor, SystemVariablesTest.LocalTunnelSource, SystemVariablesTest.TestVarCacheStage

public interface BasicVarMgrInterface

Basic variable manager interface. The variable manager may or may not be part of a pipeline.

setVariable

void setVariable(SimpleVariableValue newValue)
                 throws java.io.IOException,
                        java.lang.UnsupportedOperationException

Set variable to the given value (the variable name and definition are implicit). The value set should be immediately readable with getVariable() as the "main" value of the variable even for global variables.

This is also used to send events, the last event value being the variable's value.

Throws:

java.io.IOException - in case of I/O difficulty

java.lang.UnsupportedOperationException - if a variable is set that we could never handle, eg a non-System-ID local variable at the client end of a tunnel

setVariables

int setVariables(SimpleVariableValue[] newValues)
                 throws java.io.IOException

Update a number of variables at once for efficiency; returns the number of variables set. Is passed a set of SimpleVariableValues and behaves as if it operates on all of them by calling setVariable() for each item in the set.

Furthermore it behaves as if the set operations are done in order, from low index to high index, unless variables are coalesced (multiple sets of the same simple variable can keep just the last value). Set operations of different variables may be re-ordered with respect to one another in order that redundancy may reduced for transmission and storage, so this implicitly allows, for example, events to be re-ordered with respect to non-event variables.

An implementation may "fail fast" on the first error/exception, or may attempt to continue and do as much as possible.

An implementation may throw an IllegalArgumentException on attempt to: set a variable with value of wrong type or incompatible definition, set a non-existent or read-only variable (or these may be ignored)

Returns:

the number of variable values set (the length of the array); never negative, never more than the number passed in

Throws:

java.io.IOException

getVariable

SimpleVariableValue getVariable(SimpleVariableDefinition var)
                                throws java.io.IOException,
                                       java.lang.UnsupportedOperationException

Get a single variable value; returns null if no such value or wrong type. Implementations should, where possible, trim from the globalMap of returned values any apparently-stale data, so as to return only reasonably-live data to the caller.

Only the last event value for a given event variable is returned by this method.

Parameters:

var - definition of variable to fetch; never null

Throws:

java.io.IOException - in case of I/O difficulty

java.lang.UnsupportedOperationException - if a variable is requested that we could never supply, eg a non-System-ID local variable at the client end of a tunnel

getVariables

SimpleVariableValue[] getVariables(long changedSince)
                                   throws java.io.IOException

Get set of variable values altered on or after specified time, or get all values with -1; never null. This may be slow if there are many live variables.

Only the last event value of each event variable is returned by this method.

Throws:

java.io.IOException - in case of I/O difficulty

getEventValue

EventVariableValue getEventValue(SimpleVariableDefinition def,
                                 EventPeriod intervalSelector,
                                 boolean current)

Get the current partial, or previous full, event set at the specified interval; never null. This is a simplified interface to return either the current event set that is being collected, or the previous completed set.

The current set is the most timely, but may not contain enough data to be meaningful if the new interval has just started.

The previous set is complete and thus most likely to have enough samples to be useful, but is not completely current.

If the requested event set is not available, an empty non-authoritative synthetic one is created and returned. Thus, with this interface, it is not possible to distinguish between there being no events in the given interval or simply no data at all, but this is relatively simple and safe to use.

Parameters:

def - event definition (must be for an event); never null

intervalSelector - never null

current - if true the current event set is returned, else the previous complete set is returned

Returns:

requested event set; never null

Throws:

java.lang.IllegalArgumentException - if the request argument are invalid

getEventValues

EventVariableValue[] getEventValues(SimpleVariableDefinition def,
                                    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.

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

An implementation that is not an end-point may go upstream to fetch missing values and cache them to satisfy future requests. However, if unable to fetch authoritative data (quickly) then we will return null or non-authoritative data as appropriate for each slot; this does not throw IOException.

Parameters:

def - event definition (must be for an event); never null

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, zero is used to select the "all" bucket

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; null is treated as the common case equivalent to just bit 0 set

Returns:

as many of the requested values as available, with as many of them authoritative as possible, with [0] corresponding to bit 0 in the BitSet; may contain nulls or be zero-length (or over-sized) but never null