com.zynaptic.stash

Interface StashService

public interface StashService

This interface provides access to a single persistent stash storage service. It provides the common stash management API as well as providing access to the type specific stash entry access objects.

Method Summary

Methods

Modifier and Type	Method and Description
int	getCacheTimeout() Accesses the current cache timeout period which is in use by the stash time series entries.
<T extends java.io.Serializable> StashObjectEntry<T>	getStashObjectEntry(java.lang.String stashId, java.lang.Class<T> dataClass) Accesses the public interface for manipulating an individual raw Java object in the persistent stash storage.
<T extends java.io.Serializable> StashObjectEntry<T>	getStashObjectEntry(java.lang.String stashId, java.lang.Class<T> dataClass, java.lang.ClassLoader classLoader) Accesses the public interface for manipulating an individual raw Java object in the persistent stash storage.
<T extends java.io.Serializable> StashTimeSeriesEntry<T>	getStashTimeSeriesEntry(java.lang.String stashId, java.lang.Class<T> dataClass) Accesses the public interface for for manipulating time series data in the persistent stash storage.
<T extends java.io.Serializable> StashTimeSeriesEntry<T>	getStashTimeSeriesEntry(java.lang.String stashId, java.lang.Class<T> dataClass, java.lang.ClassLoader classLoader) Accesses the public interface for for manipulating time series data in the persistent stash storage.
java.net.URI	getStashUri() Accesses the URI of the stash resource which is accessed via the stash service object.
boolean	hasStashId(java.lang.String stashId) Determines whether a given stash ID has been registered with the stash.
Deferred<java.lang.Boolean>	invalidateStashId(java.lang.String stashId) Invalidates a stash identifier which is no longer to be used for accessing its associated stash entry.
<T extends java.io.Serializable> Deferred<StashObjectEntry<T>>	registerStashObjectId(java.lang.String stashId, java.lang.String stashName, T defaultValue) Registers a stash identifier which will be used to access a specific persistent object.
<T extends java.io.Serializable> Deferred<StashTimeSeriesEntry<T>>	registerStashTimeSeriesId(java.lang.String stashId, java.lang.String stashName, T defaultValue, int dataBlockPeriod, int dataBlockSize) Registers a stash identifier which will be used to access a set of time series data, using a configurable data block size and period.
void	reportStashContents(java.io.PrintStream printStream) Reports the contents of the stash for informational purposes.
StashService	setCacheTimeout(int cacheTimeout) Specifies the approximate timeout period for which copies of the time series data blocks will be retained in local memory after use.

Method Detail

getStashUri

java.net.URI getStashUri()

Accesses the URI of the stash resource which is accessed via the stash service object.

Returns:

Returns the URI of the stash resource which is associated with the stash service object.

registerStashObjectId

<T extends java.io.Serializable> Deferred<StashObjectEntry<T>> registerStashObjectId(java.lang.String stashId,
                                                                                   java.lang.String stashName,
                                                                                   T defaultValue)

Registers a stash identifier which will be used to access a specific persistent object.

Type Parameters:

T - This is the generic type specifier which determines the class of objects which may be stored in the stash using the given stash identifier.

Parameters:

stashId - This is the stash identifier to be registered with the stash. It takes the form of a number of dot separated alphanumeric fields, similar to the canonical Java package naming convention.

stashName - This is a human readable string which is used to refer to the stash entry.

defaultValue - This is the default data value which is to be associated with the stash identifier. It is used to infer the type and structure of data objects which may subsequently be stored and must implement the Serializable interface.

Returns:

Returns a deferred event object which will have its callbacks executed on successful completion of the operation, passing a reference to the StashObjectEntry interface which was created. On failure an exception of type InvalidStashIdException will be passed back via the errback chain if the specified stash identifier is already in use or the specified stash identifier is malformed.

registerStashTimeSeriesId

<T extends java.io.Serializable> Deferred<StashTimeSeriesEntry<T>> registerStashTimeSeriesId(java.lang.String stashId,
                                                                                           java.lang.String stashName,
                                                                                           T defaultValue,
                                                                                           int dataBlockPeriod,
                                                                                           int dataBlockSize)

Registers a stash identifier which will be used to access a set of time series data, using a configurable data block size and period.

Type Parameters:

T - This is the generic type specifier which determines the class of objects which may be stored in the stash using the given stash identifier.

Parameters:

stashId - This is the stash identifier to be registered with the stash. It takes the form of a number of dot separated alphanumeric fields, similar to the canonical Java package naming convention.

stashName - This is a human readable string which is used to refer to the stash entry.

defaultValue - This is the default data value which is to be associated with the stash identifier. It is automatically inserted into the time series data with a timestamp value of 0. The default value is used to infer the type and structure of data objects which may be subsequently stored and must implement the Serializable interface.

dataBlockPeriod - This is the minimum data block period to be used for the given time series, expressed as an integer number of milliseconds. The default URI type data block period will be used if a value of zero is specified.

dataBlockSize - This is the minimum data block size to be used for the given time series, expressed as an integer number of entries. The default URI type data block size will be used if a value of zero is specified.

Returns:

Returns a deferred event object which will have its callbacks executed on successful completion of the operation, passing a reference to the StashTimeSeriesEntry interface which was created. On failure an exception of type InvalidStashIdException will be passed back via the errback chain if the specified stash identifier is already in use or the specified stash identifier is malformed.

hasStashId

boolean hasStashId(java.lang.String stashId)

Determines whether a given stash ID has been registered with the stash.

Parameters:

stashId - This is the stash identifier being tested for current stash registration.

Returns:

Returns a boolean flag which will be set to 'true' only if the specified stash ID has been registered with the stash and has not been invalidated.

invalidateStashId

Deferred<java.lang.Boolean> invalidateStashId(java.lang.String stashId)

Invalidates a stash identifier which is no longer to be used for accessing its associated stash entry. Once invalidated, the associated persistent resource will be deleted once it is not longer in use.

Parameters:

stashId - This is the stash identifier to be invalidated in the stash. It takes the form of a number of dot separated alphanumeric fields, similar to the canonical Java package naming convention.

Returns:

Returns a deferred event object which will have its callbacks executed on successful completion of the operation, passing a boolean parameter which will be set to 'true' if a matching entry was found and removed and 'false' if no matching entry could be found. On failure an exception of type InvalidStashIdException will be passed back via the errback chain if the specified stash identifier is malformed.

getStashObjectEntry

<T extends java.io.Serializable> StashObjectEntry<T> getStashObjectEntry(java.lang.String stashId,
                                                                       java.lang.Class<T> dataClass)
                                                                     throws InvalidStashIdException,
                                                                            java.lang.ClassNotFoundException

Accesses the public interface for manipulating an individual raw Java object in the persistent stash storage. This method uses implicit class loader selection for the specified object data type.

Type Parameters:

T - This is the generic type specifier which determines the class of objects which may be stored in the stash using the given stash identifier.

Parameters:

stashId - This is the stash identifier associated with the raw Java object. It takes the form of a number of dot separated alphanumeric fields, similar to the canonical Java package naming convention.

dataClass - This is the runtime type which is used to check that the object stored in the stash is consistent with the expected data type. It is also used to infer the class loader to be used when deserializing the stash object data.

Returns:

Returns a reference to the StashObjectEntry interface which is associated with the specified stash identifier, or a null reference if there is no corresponding stash entry.

Throws:

InvalidStashIdException - This exception will be thrown if the specified stash identifier does not refer to a raw Java object entry or the specified stash identifier is malformed.

java.lang.ClassNotFoundException - This exception will be thrown if there is a mismatch between the specified data class and the default data value held by the stash entry.

getStashObjectEntry

<T extends java.io.Serializable> StashObjectEntry<T> getStashObjectEntry(java.lang.String stashId,
                                                                       java.lang.Class<T> dataClass,
                                                                       java.lang.ClassLoader classLoader)
                                                                     throws InvalidStashIdException,
                                                                            java.lang.ClassNotFoundException

Accesses the public interface for manipulating an individual raw Java object in the persistent stash storage. This method uses explicit class loader selection.

Type Parameters:

T - This is the generic type specifier which determines the class of objects which may be stored in the stash using the given stash identifier.

Parameters:

stashId - This is the stash identifier associated with the raw Java object. It takes the form of a number of dot separated alphanumeric fields, similar to the canonical Java package naming convention.

dataClass - This is the runtime type which is used to check that the object stored in the stash is consistent with the expected data type.

classLoader - This is the class loader which will be used when deserializing the stash object data.

Returns:

Returns a reference to the StashObjectEntry interface which is associated with the specified stash identifier, or a null reference if there is no corresponding stash entry.

Throws:

InvalidStashIdException - This exception will be thrown if the specified stash identifier does not refer to a raw Java object entry or the specified stash identifier is malformed.

java.lang.ClassNotFoundException - This exception will be thrown if there is a mismatch between the specified data class and the default data value held by the stash entry.

getStashTimeSeriesEntry

<T extends java.io.Serializable> StashTimeSeriesEntry<T> getStashTimeSeriesEntry(java.lang.String stashId,
                                                                               java.lang.Class<T> dataClass)
                                                                             throws InvalidStashIdException,
                                                                                    java.lang.ClassNotFoundException

Accesses the public interface for for manipulating time series data in the persistent stash storage. This method uses implicit class loader selection.

Type Parameters:

T - This is the generic type specifier which determines the class of objects which may be stored in the stash using the given stash identifier.

Parameters:

stashId - This is the stash identifier associated with the time series data. It takes the form of a number of dot separated alphanumeric fields, similar to the canonical Java package naming convention.

dataClass - This is the runtime type which is used to check that the time series data stored in the stash is consistent with the expected data type. It is also used to infer the class loader to be used when deserializing the time series data.

Returns:

Returns a reference to the StashTimeSeriesEntry interface which is associated with the specified stash identifier, or a null reference if there is no corresponding stash entry.

Throws:

InvalidStashIdException - This exception will be thrown if the specified stash identifier does not refer to a time series entry or the specified stash identifier is malformed.

java.lang.ClassNotFoundException - This exception will be thrown if there is a mismatch between the specified data class and the default data value held by the stash entry.

getStashTimeSeriesEntry

<T extends java.io.Serializable> StashTimeSeriesEntry<T> getStashTimeSeriesEntry(java.lang.String stashId,
                                                                               java.lang.Class<T> dataClass,
                                                                               java.lang.ClassLoader classLoader)
                                                                             throws InvalidStashIdException,
                                                                                    java.lang.ClassNotFoundException

Accesses the public interface for for manipulating time series data in the persistent stash storage. This method uses explicit class loader selection.

Type Parameters:

T - This is the generic type specifier which determines the class of objects which may be stored in the stash using the given stash identifier.

Parameters:

stashId - This is the stash identifier associated with the time series data. It takes the form of a number of dot separated alphanumeric fields, similar to the canonical Java package naming convention.

dataClass - This is the runtime type which is used to check that the time series data stored in the stash is consistent with the expected data type.

classLoader - This is the class loader which will be used when deserializing the time series data.

Returns:

Returns a reference to the StashTimeSeriesEntry interface which is associated with the specified stash identifier, or a null reference if there is no corresponding stash entry.

Throws:

InvalidStashIdException - This exception will be thrown if the specified stash identifier does not refer to a time series entry or the specified stash identifier is malformed.

java.lang.ClassNotFoundException - This exception will be thrown if there is a mismatch between the specified data class and the default data value held by the stash entry.

reportStashContents

void reportStashContents(java.io.PrintStream printStream)
                         throws java.io.IOException

Reports the contents of the stash for informational purposes. This method generates a text report of the current state of the stash for debug and monitoring purposes.

Parameters:

printStream - This is the output print stream to which the stash contents report will be sent.

Throws:

java.io.IOException - This exception will be thrown on failure to write to the specified print stream.

setCacheTimeout

StashService setCacheTimeout(int cacheTimeout)

Specifies the approximate timeout period for which copies of the time series data blocks will be retained in local memory after use. Data blocks will automatically be discarded from local memory after they have been unused for the specified period. The default cache timeout period depends on the stash service URI type being used.

Parameters:

cacheTimeout - This is the timeout period after which unused data blocks will be discarded from local memory, expressed as an integer number of milliseconds. May be set to zero or a positive integer value;

Returns:

Returns a reference to the stash service object, enabling fluent parameter assignment to be used.

getCacheTimeout

int getCacheTimeout()

Accesses the current cache timeout period which is in use by the stash time series entries.

Returns:

Returns the current cache timeout period, expressed as an integer number of milliseconds.