org.soaplab.share
Interface Analysis

public interface Analysis

An interface to a service (usually a web service, but nothing precludes to have, for example, a REST implementtaion of such service), accessing and controlling an analysis.

An analysis is usually a remote program, mostly a command-line tool, but it can also be fetching a web site, or starting a local Java class (providing, for example, some computation).

Version:

$Id: Analysis.java,v 1.7 2010/08/06 10:41:55 marsenger Exp $

Author:

Martin Senger

Method Summary

java.lang.String	createAndRun(SoaplabMap inputs) A convenient combination of methods createJob(org.soaplab.share.SoaplabMap) and run.
java.lang.String	createAndRunNotifiable(SoaplabMap inputs, java.lang.String notificationDescriptor) The same as createAndRun(org.soaplab.share.SoaplabMap) with addition of the channel notification negotiation.
java.lang.String	createJob(SoaplabMap inputs) Prepare a job with given input data but do not start it.
java.lang.String	describe() Return an XML string containing metadata describing this analysis service.
void	destroy(java.lang.String jobID) Release related resources, including results.
SoaplabMap	getAnalysisType() Return attributes describing this analysis.
SoaplabMap	getCharacteristics(java.lang.String jobID) Returning job's time characteristics.
SoaplabMap[]	getInputSpec() Return information about all possible data inputs.
java.lang.String	getLastEvent(java.lang.String jobID) Return the last event which happened to the given job.
java.lang.String	getNotificationDescriptor(java.lang.String jobID) Return an XML string describing location and available protocol (or even protocols) of a notification channel which will have messages regarding given job.
SoaplabMap	getResults(java.lang.String jobID) Return all (available) results from the given job.
SoaplabMap[]	getResultsInfo(java.lang.String jobId)
SoaplabMap[]	getResultSpec() Return information about all possible results.
SoaplabMap	getSomeResults(java.lang.String jobID, java.lang.String[] resultNames) Return named (and available) results from the given job.
java.lang.String	getStatus(java.lang.String jobID) Return a string describing the current job status.
void	run(java.lang.String jobID) Start an underlying analysis and return immediately, without waiting for its completion.
SoaplabMap	runAndWaitFor(SoaplabMap inputs) Block the client until the underlying running analysis is completed and return immediately all results.
void	runNotifiable(java.lang.String jobID, java.lang.String notificationDescriptor) The same as run(java.lang.String) with addition of the channel notification negotiation.
void	terminate(java.lang.String jobID) Terminate the running analysis, identified by its job ID.
void	waitFor(java.lang.String jobID) Block the client until the underlying running analysis is completed.

Method Detail

describe

java.lang.String describe()
                          throws SoaplabException

Return an XML string containing metadata describing this analysis service. Its format complies with the SoaplabAnalysis.dtd.

Throws:

SoaplabException - if communication with the service fails

getInputSpec

SoaplabMap[] getInputSpec()
                          throws SoaplabException

Return information about all possible data inputs. Each element of the returned array is a Map describing one data input (it does not contain, however, the input data themselves).

Each Map element should have at least keys name and type defining input data name and its Java type. An implementation can choose to provide more characteristics. Typically they are:

Key	Type	Note
name	String	A name of analysis data input. The input names are needed when a job is created and fed with the input data (see methods createJob(org.soaplab.share.SoaplabMap) or runAndWaitFor(org.soaplab.share.SoaplabMap)).
type	String	A type of this data input. Expressed as Java type (e.g. String, or byte[][]).
allowed_values	String[]	A list of possible (allowed, expected) values for this data input. (Note that the values are here always as Strings. This may be rectify later.)
mandatory	String	The true is this data input must be present when the analysis starts. Otherwise there is false here, or this key is missing at all.
default	String	A default value used when no data given for this data input. (The same note applies as for allowed_values above.)

Additionally, some keys may be terms from an ontology defining semantics of this input. For Soaplab implementation, typically such keys have format EDAM:NNN indicating the usage of the EDAM ontology.

This is just a convenient method retrieving the same data (but only part of it) as method describe() but without need to parse any XML stream.

Throws:

SoaplabException - if communication with the service fails

getResultSpec

SoaplabMap[] getResultSpec()
                           throws SoaplabException

Return information about all possible results. Each element of the returned Map describes one result (it does not contain, however, the result itself).

Each Map element should have at least keys name and type defining result name and its Java type. An implementation can choose to provide more characteristics. Typically they are:

Key	Type	Note
name	String	A name of analysis result. The result names are needed when asking a job to retrieve output data (see method getResults(java.lang.String)).
type	String	A type of this result. Expressed as Java type (e.g. String, or byte[][]).

Additionally, some keys may be terms from an ontology defining semantics of this result. For Soaplab implementation, typically such keys have format EDAM:NNN indicating the usage of the EDAM ontology.

This is just a convenient method retrieving the same data (but only part of it) as method describe() but without need to parse any XML stream.

The result names can be used to retrieve only some, named, results from a job representing an execution of this analysis (see method getResults(java.lang.String)).

Throws:

SoaplabException - if communication with the service fails

getAnalysisType

SoaplabMap getAnalysisType()
                           throws SoaplabException

Return attributes describing this analysis.

Some attribute keys may be terms from an ontology defining semantics of this analysis. For Soaplab implementation, typically such keys have format EDAM:NNN indicating the usage of the EDAM ontology.

This is just a convenient method retrieving the same data (but only part of it) as method describe() but without need to parse any XML stream.

Returns:

a hash table with the following keys (some may be missing, however): type, name, supplier, version, installation, description; the implementation can also add some keys

Throws:

SoaplabException - if communication with the service fails

createJob

java.lang.String createJob(SoaplabMap inputs)
                           throws SoaplabException

Prepare a job with given input data but do not start it. It returns a job identifier which can be used by other methods (such as run) to start and to control the job.

How to specify input data

Generally speaking, each data input is a name/value pair. The name identifies uniquely each data input. The available names can be retrieved using method getInputSpec(). The values are any objects - but an implementation may limit the types which are recognized.

Returns:

a job ID

Throws:

SoaplabException - if communication with the service fails, or more specifically (see defining exceptions) using:

fault string SoaplabConstants.FAULT_UNKNOWN_NAME if there is an unrecognized input name

fault string SoaplabConstants.FAULT_NOT_VALID_INPUTS if the input data are invalid (e.g. they do not follow some inter-data dependency conditions)

run

void run(java.lang.String jobID)
         throws SoaplabException

Start an underlying analysis and return immediately, without waiting for its completion. It uses data which were sent (and possibly validated) by method createJob(org.soaplab.share.SoaplabMap). With the same jobID it can be run only once. It raises a NotRunnableSoaplabException if there is an attempt to start it more than once.

Throws:

SoaplabException - if communication with the service fails, or more specifically (see defining exceptions) using:

fault string SoaplabConstants.FAULT_NOT_FOUND if the given job ID does not exist

fault string SoaplabConstants.FAULT_NOT_RUNNABLE if the same job was alredy executed, or if the data given previously by createJob(org.soaplab.share.SoaplabMap) do not exist or are not accessible anymore

runNotifiable

void runNotifiable(java.lang.String jobID,
                   java.lang.String notificationDescriptor)
                   throws SoaplabException

The same as run(java.lang.String) with addition of the channel notification negotiation. See details here.

Throws:

SoaplabException - as in run(java.lang.String) plus (see defining exceptions) using:

fault string SoaplabConstants.FAULT_NOTIFY_UNACCEPTED if the server does not agree on using the proposed notification channel

createAndRun

java.lang.String createAndRun(SoaplabMap inputs)
                              throws SoaplabException

A convenient combination of methods createJob(org.soaplab.share.SoaplabMap) and run. See how to specify input data.

Returns:

a job ID

Throws:

SoaplabException - if communication with the service fails, or more specifically (see defining exceptions) using:

fault string SoaplabConstants.FAULT_UNKNOWN_NAME if there is an unrecognized input name

fault string SoaplabConstants.FAULT_NOT_VALID_INPUTS if the input data are invalid (e.g. they do not follow some inter-data dependency conditions)

createAndRunNotifiable

java.lang.String createAndRunNotifiable(SoaplabMap inputs,
                                        java.lang.String notificationDescriptor)
                                        throws SoaplabException

The same as createAndRun(org.soaplab.share.SoaplabMap) with addition of the channel notification negotiation. See details here.

Throws:

SoaplabException - as in createAndRun(org.soaplab.share.SoaplabMap) plus (see defining exceptions) using:

fault string SoaplabConstants.FAULT_NOTIFY_UNACCEPTED if the server does not agree on using the proposed notification channel

waitFor

void waitFor(java.lang.String jobID)
             throws SoaplabException

Block the client until the underlying running analysis is completed. The running job is identified by the given job ID.

Note that this method keeps an open connection with the server until the job is finished which may be for quite a long time. Therefore, an implementation may refuse this request by throwing an exception. Also even if the implementation allows there may be some time-outs set by other components (e.g. a proxy server) which may make this request unreliable. See notification for an alternative.

Throws:

SoaplabException - if communication with the service fails, or more specifically (see defining exceptions) using:

fault string SoaplabConstants.FAULT_NOT_FOUND if the given job ID does not exist

fault string SoaplabConstants.FAULT_NOT_IMPLEMENTED if the implementation refuses this request

runAndWaitFor

SoaplabMap runAndWaitFor(SoaplabMap inputs)
                         throws SoaplabException

Block the client until the underlying running analysis is completed and return immediately all results. The running job is identified by the given job ID.

This is designed for a full state-less server implementation - however, see the note about dangers.

Note that by using this method there is no way how to get additional information usually passed by a notification channel (e.g. events happenning during the job life-cycle). A service implementation should consider to pass some of those as an additional result (e.g. termination status/code).

Returns:

all results (see getResults(java.lang.String))

Throws:

SoaplabException - if communication with the service fails, or more specifically (see defining exceptions) using:

fault string SoaplabConstants.FAULT_UNKNOWN_NAME if there is an unrecognized input name

fault string SoaplabConstants.FAULT_NOT_VALID_INPUTS if the input data are invalid (e.g. they do not follow some inter-data dependency conditions)

fault string SoaplabConstants.FAULT_NOT_IMPLEMENTED if the implementation refuses this request

terminate

void terminate(java.lang.String jobID)
               throws SoaplabException

Terminate the running analysis, identified by its job ID.

Throws:

SoaplabException - if communication with the service fails, or more specifically (see defining exceptions) using:

fault string SoaplabConstants.FAULT_NOT_FOUND if the given job ID does not exist

fault string SoaplabConstants.FAULT_NOT_RUNNING if the given job was not yet started (note that this exception is not raised when the job had been already finished - from any reasons)

fault string SoaplabConstants.FAULT_NOT_TERMINATED if the given analysis is not interruptible from some reason

getLastEvent

java.lang.String getLastEvent(java.lang.String jobID)
                              throws SoaplabException

Return the last event which happened to the given job. It returns an XML string describing the event (see events description).

Throws:

SoaplabException - if communication with the service fails or more specifically (see defining exceptions) using:

fault string SoaplabConstants.FAULT_NOT_FOUND if the given job ID does not exist

getNotificationDescriptor

java.lang.String getNotificationDescriptor(java.lang.String jobID)
                                           throws SoaplabException

Return an XML string describing location and available protocol (or even protocols) of a notification channel which will have messages regarding given job. More details in notification description.

Throws:

SoaplabException - if communication with the service fails or more specifically (see defining exceptions) using:

fault string SoaplabConstants.FAULT_NOT_FOUND if the given job ID does not exist

getStatus

java.lang.String getStatus(java.lang.String jobID)
                           throws SoaplabException

Return a string describing the current job status. At least the following values are recognized:

• CREATED - job has been created but not yet executed
• RUNNING - job is running
• COMPLETED - job has completed execution
• TERMINATED_BY_REQUEST - job was terminated by user request
• TERMINATED_BY_ERROR - job was terminated due to an error

Throws:

SoaplabException - if communication with the service fails or more specifically (see defining exceptions) using:

fault string SoaplabConstants.FAULT_NOT_FOUND if the given job ID does not exist

getCharacteristics

SoaplabMap getCharacteristics(java.lang.String jobID)
                              throws SoaplabException

Returning job's time characteristics. The recognized map's keys are: SoaplabConstants.TIME_CREATED, SoaplabConstants.TIME_STARTED, SoaplabConstants.TIME_ENDED, SoaplabConstants.TIME_ELAPSED. The values are in milliseconds from the beginning of the Epoch (1.1.1971) - even though they are passed as type String.

Throws:

SoaplabException - if communication with the service fails or more specifically (see defining exceptions) using:

fault string SoaplabConstants.FAULT_NOT_FOUND if the given job ID does not exist

getResultsInfo

SoaplabMap[] getResultsInfo(java.lang.String jobId)
                            throws SoaplabException

Throws:

SoaplabException

getResults

SoaplabMap getResults(java.lang.String jobID)
                      throws SoaplabException

Return all (available) results from the given job.

How to deal with results

Generally speaking, each result is a name/value pair. The name identifies uniquely each result. The available names can be retrieved using method getResultSpec(). The values are any objects - but an implementation may limit the types which are recognized.

Throws:

SoaplabException - if communication with the service fails or more specifically (see defining exceptions) using:

fault string SoaplabConstants.FAULT_NOT_FOUND if the given job ID does not exist

getSomeResults

SoaplabMap getSomeResults(java.lang.String jobID,
                          java.lang.String[] resultNames)
                          throws SoaplabException

Return named (and available) results from the given job. See how to deal with results.

Throws:

SoaplabException - if communication with the service fails or more specifically (see defining exceptions) using:

fault string SoaplabConstants.FAULT_NOT_FOUND if the given job ID does not exist

fault string SoaplabConstants.FAULT_UNKNOWN_NAME if there is an unrecognized result name

destroy

void destroy(java.lang.String jobID)
             throws SoaplabException

Release related resources, including results. A client uses this method to suggest that she will not need anymore any data from the given job. However, implementation can decide both to ignore this request, or to release them even earlier.

Throws:

SoaplabException - if communication with the service fails or more specifically (see defining exceptions) using:

fault string SoaplabConstants.FAULT_NOT_FOUND if the given job ID does not exist