org.hd.d.pg2k.svrCore.datasource
Class SimpleExhibitPipelineFilter

java.lang.Object
  org.hd.d.pg2k.svrCore.datasource.SimpleExhibitPipelineFilter

All Implemented Interfaces:

SimpleExhibitPipelineIF, BasicVarMgrInterface, SimpleVariablePipelineIF

Direct Known Subclasses:

SimpleCacheTest.DataConcurrencyAccessMonitor, SimpleCacheTest.RawDataAccessMonitor, SystemVariablesTest.EventValueRequestMonitor, SystemVariablesTest.TestVarCacheStage

public class SimpleExhibitPipelineFilter
extends java.lang.Object
implements SimpleExhibitPipelineIF

Simple extendable base class which acts as a pipeline filter. Analogous to a FilterInputStream, a SimpleExhibitPipelineFilter wraps another data source/stage, which it uses as its basic source of data, possibly transforming the data along the way or providing additional functionality.

The class SimpleExhibitPipelineFilter itself simply implements all methods of SimpleExhibitPipelineIF with versions that pass all requests to the wrapped source. Subclasses of SimpleExhibitPipelineFilter may further override some of these methods and may also provide additional methods and fields.

A bare SimpleExhibitPipelineFilter is like a null/identity stage which leaves the semantics of a data pipeline intact.

One possible use of this is to build a "Mock Object" for testing purposes.

source

protected final SimpleExhibitPipelineIF source

The upstream source; never null.

SimpleExhibitPipelineFilter

public SimpleExhibitPipelineFilter(SimpleExhibitPipelineIF source)

Construct a new instance of this filter.

Parameters:

source - the upstream data source; never null

getStaticAttr

public ExhibitStaticAttr getStaticAttr(Name.ExhibitFull name)
                                throws java.io.IOException

Get the static attributes for a given exhibit. Returns null if the named exhibit does not exist.

Specified by:

getStaticAttr in interface SimpleExhibitPipelineIF

Throws:

java.io.IOException - if the operation cannot be completed due to I/O restrictions or failure

getRawFile

public void getRawFile(java.nio.ByteBuffer buf,
                       Name.ExhibitFull exhibitName,
                       int position,
                       boolean dontCache)
                throws java.io.IOException

Read a chunk of the raw exhibit binary into the given buffer. The start index and the index after the last required byte is supplied. The start value must be non-negative and the afterEnd value no smaller than start and no larger than the exhibit data length.

This always reads all the bytes requested or throws an IOException.

Specified by:

getRawFile in interface SimpleExhibitPipelineIF

Parameters:

dontCache - if true, this is a hint not to attempt to cache this or displace anything from extant caches for this data as it maqy for example be precaching or random activity; by default callers should leave this false to allow cacheing

buf - the buffer into which to read the data; must be non-null, in put()able state, and with remaining capacity of at least the requested number of bytes

exhibitName - the full name of the exhibit to read from; never null and must be syntactically valid

position - position/index of first byte in exhibitFile to read; non-negative

Throws:

java.lang.IllegalArgumentException - for invalid arguments such as a null or invalid name, a negative offset or start, a negative (or in some cases, non-positive) len

java.io.IOException - for requests that cannot be fulfilled because of I/O restrictions or problems, such as link failure or an upper bound on the length of a request

getAllExhibitImmutableData

public AllExhibitImmutableData getAllExhibitImmutableData(long oldStamp)
                                                   throws java.io.IOException

Gets set of all static exhibit data if its timestamp is not that specified. If the time specified is negative the object will be returned unconditionally.

If no exhibits are currently installed a default set with a zero timestamp is returned.

If the caller's copy appears to be up-to-date (eg the oldStamp matches that that would have been returned) null is returned.

Specified by:

getAllExhibitImmutableData in interface SimpleExhibitPipelineIF

Throws:

java.io.IOException - if the operation cannot be completed due to I/O restrictions or failure

getAllExhibitProperties

public AllExhibitProperties getAllExhibitProperties(long oldHash)
                                             throws java.io.IOException

Gets set of all exhibit properties if its hash is not that specified. If the hash specified is negative the object will be returned unconditionally.

If no exhibits are currently installed a default set with a zero timestamp is returned.

If the caller's copy appears to be up-to-date (eg the oldHash matches that that would have been returned) null is returned.

Specified by:

getAllExhibitProperties in interface SimpleExhibitPipelineIF

Throws:

java.io.IOException - if the operation cannot be completed due to I/O restrictions or failure

getGenProps

public GenProps getGenProps(long oldStamp)
                     throws java.io.IOException

Gets the general properties as a GenProps object if its timestamp is not that specified. If the time specified is negative the object will be returned unconditionally.

If no props are currently installed/available a default set with a zero timestamp is returned.

If the caller's copy appears to be up-to-date (eg the oldStamp matches that that would have been returned) null is returned.

Specified by:

getGenProps in interface SimpleExhibitPipelineIF

Throws:

java.io.IOException - if the operation cannot be completed due to I/O restrictions or failure

getGenSecProps

public java.util.Properties getGenSecProps(long oldStamp)
                                    throws java.io.IOException

Gets the generic security properties as a Properties object if its timestamp is not that specified. If the time specified is negative the object will be returned unconditionally.

If no props are currently installed/available a default set with a zero timestamp is returned.

If the caller's copy appears to be up-to-date (eg the oldStamp matches that that would have been returned) null is returned.

Specified by:

getGenSecProps in interface SimpleExhibitPipelineIF

Throws:

java.io.IOException - if the operation cannot be completed due to I/O restrictions or failure

getThumbnails

public ExhibitThumbnails getThumbnails(Name.ExhibitFull name,
                                       boolean create)
                                throws java.io.IOException

Gets the thumbnails for an exhibit. A data source is at liberty to refuse to compute thumbnails in which case it may return null, else it returns a non-null value which may include the `could-not-compute' value to indicate that a thumbnail/sample cannot be made for this exhibit and no attempt need be made in future.

Specified by:

getThumbnails in interface SimpleExhibitPipelineIF

Parameters:

create - if true, and no thumbnail yet exists, try to create one if possible, else if create is false only return an existing one and return null if none is to hand

Throws:

java.io.IOException - if the operation cannot be completed due to I/O restrictions or failure

poll

public void poll(GenProps gp)
          throws java.io.IOException

Poll periodically (of the order of seconds) to do bg work. The current generic system properties are passed in...

Specified by:

poll in interface SimpleExhibitPipelineIF

Throws:

java.io.IOException - in case of difficulty, but even if a sub-ordinate call throws IOException the poll() call should make some effort to do as much of its work as reasonably possible

syncVariables

public void syncVariables(boolean force)
                   throws java.io.IOException

Synchronise variables with upstream values. Pushes updated values upstream to the source, calls sync on the source if called with the "force" argument true, and then retrieves changed values from upstream.

When called with force==true, this acts like a full "memory barrier", flushing all write-cached items downstream immediately and afterwards getting the value of all upstream values with getVariables(-1), but may be expensive in terms of CPU or bandwidth, so use sparingly.

When called with force=false, this incrementally flushes outstanding writes and will then fetch all, or only new, values from upstream, so is potentally much less resource-intensive. In particular, this does not propagate the sync() upstream.

In any case, it is rarely the right thing for a casual user to vall this as it may be very expensive.

Specified by:

syncVariables in interface SimpleVariablePipelineIF

Parameters:

force - if true, this will force a full write flush, a full sync upstream, then full read with getVariables(-1), to get the effect of a full "barrier"; otherwise, in general, a more incremental and non-propagating mode is used which still does a write flush but may chose to do a partial read of "new" upstream values

Throws:

java.io.IOException - if one is received from upstream

getVariables

public 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.

Specified by:

getVariables in interface BasicVarMgrInterface

Throws:

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

getVariable

public 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.

Specified by:

getVariable in interface BasicVarMgrInterface

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

setVariables

public 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.

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)

Specified by:

setVariables in interface BasicVarMgrInterface

Returns:

the number of variable values set; never negative, never more than the number passed in

Throws:

java.io.IOException

setVariable

public 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.

Specified by:

setVariable in interface BasicVarMgrInterface

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

getEventValue

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

Get the current partial, or previous full, event set at the specified interval. 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.

Specified by:

getEventValue in interface BasicVarMgrInterface

Parameters:

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

intervalSelector - one of EVENT_INTERVAL_SELECTOR_xxx values

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

Returns:

requested event set; may be null if requested set not available

getEventValues

public 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.)

Specified by:

getEventValues in interface BasicVarMgrInterface

Parameters:

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

intervalSelector - one of EVENT_INTERVAL_SELECTOR_xxx values

intervalNumber - a time (as from System.currentTimeMillis()) which identifies 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 access 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, at least long enough to return all the available values, with [0] corresponding to bit 0 in the BitSet; may contain nulls or be zero-length but is never null

getProperties

public java.util.Properties getProperties(SimpleExhibitPipelineIF.PropsKey key,
                                          long versionID)
                                   throws java.io.IOException

Get requested Properties selected by key and versionID. Fetches a Properties set unconditionally (versionID == -1) else if the versionID presented is not current.

Specified by:

getProperties in interface SimpleExhibitPipelineIF

Parameters:

key - selector (with possible embedded sub-key) for desired properties set; never null

versionID - if -1 then map is always returned if available, else must be non-negative and null is returned if the versionID presented matches that of the current version (ie if the caller has presumably got the up-to-date version); may be a timestamp or a hash or other value, and by convention is zero only for an empty properties set

Returns:

null, or Properties map guaranteed to contain only String keys and values

Throws:

java.io.IOException

getStratum

public Stratum getStratum()
                   throws java.io.IOException

Description copied from interface: SimpleExhibitPipelineIF

Gets information about our stratum and upstream server; never null.

Specified by:

getStratum in interface SimpleExhibitPipelineIF

Throws:

java.io.IOException

destroy

public void destroy()

Shut down the data pipeline. Simply calls source.destroy().

Specified by:

destroy in interface SimpleExhibitPipelineIF