org.soaplab.services.storage
Interface PersistentStorage

public interface PersistentStorage

An interface defining how to store results, and other characteristics of service invocations ("jobs"), in more persistent way. Typical implementations will use a file system or a local database.

Some implementations may be actually just "data consumers", or "sinks", that will never return any data back. This may be used for various user interfaces displaying or transforming analysis results. A storage that behaves like that returns true from the isSink method.

Version:

$Id: PersistentStorage.java,v 1.5 2007/10/17 15:55:16 marsenger Exp $

Author:

Martin Senger

Method Summary

java.lang.String	getDescription() Return a (human-readable) description of this persistent storage.
java.util.Properties	getJobProperties(java.lang.String jobId) Return known properties of the given job.
org.soaplab.services.JobState	getJobState(java.lang.String jobId) This is as close to re-creating a stored job as possible.
java.lang.Object	getResult(java.lang.String jobId, java.lang.String name) Find in this persistent storage the given result for the given job and return them back.
java.util.Map<java.lang.String,java.lang.Object>	getResults(java.lang.String jobId) Find in this persistent storage all results for the given job and return them back.
java.util.Map<java.lang.String,java.lang.String>[]	getResultsInfo(java.lang.String jobId) Return properties associated with all results from the given job.
boolean	isSink() Return 'true' if this storage allows only setting data (jobs, state, results, etc.) but never returns them back.
java.lang.String[]	listJobs() Return names (job Ids) of all jobs still available from this storage handler.
void	removeJob(java.lang.String jobId) Remove given job from this persistent storage.
void	removeJobs(java.util.Date fromDate, java.util.Date toDate) Remove jobs from this persistent storage that were last updated within given time interval.
void	removeJobs(java.lang.String jobIdPattern) Remove jobs from this persistent storage whose IDs contain the string specified by 'jobIdPattern'.
void	setJob(Job job) Store Job's state information to the persistent storage.
void	setJobProperties(java.lang.String jobId, java.util.Properties props) Store properties for the given job.
void	setResult(Job job, java.lang.String name, java.lang.Object result) Store result in the persistent storage.

Method Detail

getDescription

java.lang.String getDescription()

Return a (human-readable) description of this persistent storage. It is intended for admin purposes, not for the Soaplab end-users.

listJobs

java.lang.String[] listJobs()

Return names (job Ids) of all jobs still available from this storage handler.

Returns:

names in the same format as expected in other methods (of this interface) requiring job IDs. Return an empty array (not null) if there are no jobs stored.

getJobState

org.soaplab.services.JobState getJobState(java.lang.String jobId)
                                          throws SoaplabException

This is as close to re-creating a stored job as possible.

Parameters:

jobId - an identifier of a job whose state will be returned

Returns:

a re-created job status of the wanted job; everything as read from the persistent storage

Throws:

SoaplabException - if the permanent storage cannot be accessed, or if the given 'jobId' does not exist there

getJobProperties

java.util.Properties getJobProperties(java.lang.String jobId)
                                      throws SoaplabException

Return known properties of the given job.

Parameters:

jobId - identifies the job whose properties are asked for

Returns:

job properties, or an empty container but never null

Throws:

SoaplabException - if the permanent storage cannot be accessed, or if the given 'jobId' does not exist there

setJobProperties

void setJobProperties(java.lang.String jobId,
                      java.util.Properties props)
                      throws SoaplabException

Store properties for the given job.

Parameters:

jobId - identifies the job whose properties are being saved

Throws:

SoaplabException - if the permanent storage cannot be accessed, or if the given 'jobId' does not exist there

setJob

void setJob(Job job)
            throws SoaplabException

Store Job's state information to the persistent storage. It includes job's time properties, job state and the last event.

Parameters:

job - whose state is being saved

Throws:

SoaplabException - if the permanent storage cannot be accessed

removeJob

void removeJob(java.lang.String jobId)
               throws SoaplabException

Remove given job from this persistent storage.

Throws:

SoaplabException - if the storage cannot be accessed

removeJobs

void removeJobs(java.lang.String jobIdPattern)

Remove jobs from this persistent storage whose IDs contain the string specified by 'jobIdPattern'.

Parameters:

jobIdPattern - is a simple pattern, not a regular expression

removeJobs

void removeJobs(java.util.Date fromDate,
                java.util.Date toDate)

Remove jobs from this persistent storage that were last updated within given time interval.

Parameters:

fromDate - begins the interval of removal

toDate - finishes the interval of removal

getResults

java.util.Map<java.lang.String,java.lang.Object> getResults(java.lang.String jobId)
                                                            throws SoaplabException

Find in this persistent storage all results for the given job and return them back.

Parameters:

jobId - a job whose results to return

Returns:

a map whose keys are result names and values results themselves

Throws:

SoaplabException - if the permanent storage cannot be accessed, or if the given 'jobId' does not exist there

getResult

java.lang.Object getResult(java.lang.String jobId,
                           java.lang.String name)
                           throws SoaplabException

Find in this persistent storage the given result for the given job and return them back.

Parameters:

jobId - a job whose result to return

name - of a result to be returned

Returns:

the wanted result, or null if 'name' result does not exist

Throws:

SoaplabException - if the permanent storage cannot be accessed, or if the given 'jobId' does not exist there

getResultsInfo

java.util.Map<java.lang.String,java.lang.String>[] getResultsInfo(java.lang.String jobId)
                                                                  throws SoaplabException

Return properties associated with all results from the given job.

Parameters:

jobId - identifies a job whose results are being investigated

Returns:

a Map for each existing result (for the given job); the keys are the result properies names - such as the type and size of the result

Throws:

SoaplabException - if the storage cannot be accessed

setResult

void setResult(Job job,
               java.lang.String name,
               java.lang.Object result)
               throws SoaplabException

Store result in the persistent storage.

Parameters:

job - where the result belongs to

name - of the result (as defined in the service metadata)

result - to be stored (allowed types may depend on the storage handler, but reasonable effort should be made to store most of the common types)

Throws:

SoaplabException - if the storage cannot be accessed

isSink

boolean isSink()

Return 'true' if this storage allows only setting data (jobs, state, results, etc.) but never returns them back.

This may be used if the "storage" is a user interface for displaying job's data. For example, the HTML pages may be a "persistent storage", showing results and job state.