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.


Nested Class Summary
static class SimpleExhibitPipelineIF.PropsKey
          Class that holds key to Properties lookup/fetch.
 
Field Summary
static int MAX_USER_READ_SIZE
          Maximum exhibit user-driven I/O data transfer request in bytes; strictly positive.
 
Method Summary
 void destroy()
          Shut down the data pipeline.
 AllExhibitImmutableData getAllExhibitImmutableData(long oldStamp)
          Gets set of all static exhibit data if its timestamp is not that specified.
 AllExhibitProperties getAllExhibitProperties(long oldHash)
          Gets set of all exhibit properties if its hash is not that specified; never null for -1 argument.
 GenProps getGenProps(long oldStamp)
          Gets the general properties as a GenProps object if its timestamp is not that specified; never null for -1 argument.
 java.util.Properties getGenSecProps(long oldStamp)
          Deprecated. Use getProperties() for new code.
 java.util.Properties getProperties(SimpleExhibitPipelineIF.PropsKey key, long versionID)
          Get requested Properties selected by key and versionID.
 void getRawFile(java.nio.ByteBuffer buf, Name.ExhibitFull exhibitName, int position, boolean dontCache)
          Read a chunk of the raw exhibit binary into the given buffer.
 ExhibitStaticAttr getStaticAttr(Name.ExhibitFull name)
          Get the static attributes for a given exhibit.
 Stratum getStratum()
          Gets information about our stratum and upstream server; never null.
 ExhibitThumbnails getThumbnails(Name.ExhibitFull name, boolean create)
          Gets the thumbnails for an exhibit.
 void poll(GenProps gp)
          Poll periodically (of the order of seconds) to do background work.
 
Methods inherited from interface org.hd.d.pg2k.svrCore.vars.SimpleVariablePipelineIF
syncVariables
 
Methods inherited from interface org.hd.d.pg2k.svrCore.vars.BasicVarMgrInterface
getEventValue, getEventValues, getVariable, getVariables, setVariable, setVariables
 

Field Detail

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
Method Detail

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.


DHD Multimedia Gallery V1.60.69

Copyright (c) 1996-2012, Damon Hart-Davis. All rights reserved.