org.hd.d.pg2k.svrCore.datasource
Interface SimpleExhibitPipelineIF

All Superinterfaces:

BasicVarMgrInterface, SimpleVariablePipelineIF

All Known Subinterfaces:

ExhibitPipelineReducedExceptionIF

All Known Implementing Classes:

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

public interface SimpleExhibitPipelineIF
extends SimpleVariablePipelineIF

Simple interface implemented by several stages in the Web exhibit-handling pipeline. In particular, the on-disc exhibit-data cache and backend datasource adaptors implement this.

The pipeline stages that implement this may well implement other interfaces in parallel to provide richer and more efficient cacheing, etc.

As this is in effect handling a stream of I/O on its way to a browser, IOException seems the natural way to signal errors.

We may make implementers of this interface Serializable so as to allow them to be persisted in servlet context for robustness and distribution, but making copies through this mechanism will upset the ability to fully track usage and efficiently share caches, etc.

Note that this extends the variable-handling pipeline interface, ie data pipelines also handle system variables.

Note that transient errors (eg caused by temporary resource shortage/congestion) and indicated by InterruptedIOException being thrown, and may indicate that a retry soon may be successful.

MAX_USER_READ_SIZE

static final int MAX_USER_READ_SIZE

Maximum exhibit user-driven I/O data transfer request in bytes; strictly positive. This is the limit for filesystem access, tunnel connections, etc, to avoid causing bottlenecks and out-of-memory conditions.

Some operations that request transfers larger than this (and where the caller has control of the size of the request), eg reading raw data from an exhibit, may be rejected with an IOException.

Note that this does not limit the return of large data items (eg AllExhibitProperties) whose size is not controlled by the caller.

This helps prevent denial-of-service by a faulty/malicious client.

A power of two for efficiency in various places.

A size of many times BULK_DATA_TRANSFER_SIZE to a few mBytes is probably reasonable.

See Also:

Constant Field Values

getStaticAttr

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.

Throws:

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

getRawFile

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 call may return less than the the buffer capacity, though will block until it has read at least one byte unless at EOF or for a zero-byte request; this will be clear from the state of the buffer.

Parameters:

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

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

Throws:

java.lang.IllegalArgumentException - for invalid arguments such as a null or syntactically-invalid name, a negative position or excessive number of requested bytes, 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

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.

Throws:

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

getAllExhibitProperties

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

Gets set of all exhibit properties if its hash is not that specified; never null for -1 argument. 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.

Throws:

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

getGenProps

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

Gets the general properties as a GenProps object if its timestamp is not that specified; never null for -1 argument. 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.

Throws:

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

getGenSecProps

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

Deprecated. Use getProperties() for new code.

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.

Throws:

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

getThumbnails

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.

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

getProperties

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.

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

Stratum getStratum()
                   throws java.io.IOException

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

Throws:

java.io.IOException

poll

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

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

Throws:

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

destroy

void destroy()

Shut down the data pipeline. Free resources having saved any persistent state and shut down any upstream components.