org.embl.ebi.SoaplabShare
Interface AnalysisWS

public interface AnalysisWS

An interface to a Web Service accessing and controlling an analysis (an analysis is a remote program, mostly a command-line program).

Last changes (in backwards order)

• Some methods changed their names (because WSDL 1.2 demands not to use method overwriting):
  • run(String,String) -> runNotifiable(java.lang.String, java.lang.String)
  • run(Map) -> createAndRun(java.util.Map)
  • run(Map,String) -> createAndRunNotifiable(java.util.Map, java.lang.String)
  • waitFor(Map) -> runAndWaitFor(java.util.Map)
  • getResults(String,String[]) -> getSomeResults(java.lang.String, java.lang.String[])
• Method getResultSpec() changed its signature, it returns now Map[] - the same data type as other methods returning metadata. Sorry for the previous wrong design...
• New property names added.

Version:

$Id: AnalysisWS.java,v 1.1.1.1 2005/06/15 09:00:19 marsenger Exp $

Author:

Martin Senger

See Also:

AnalysisFactoryWS

Field Summary

static java.lang.String	ANALYSIS_DESCRIPTION A property name for an analysis description.
static java.lang.String	ANALYSIS_HELP_URL A property name for an analysis URL with a detailed help.
static java.lang.String	ANALYSIS_INSTALLATION A property name for an analysis installation.
static java.lang.String	ANALYSIS_NAME A property name for an analysis name.
static java.lang.String	ANALYSIS_SUPPLIER A property name for an analysis supplier.
static java.lang.String	ANALYSIS_TYPE A property name for an analysis type.
static java.lang.String	ANALYSIS_VERSION A property name for an analysis version.
static java.lang.String	DATA_HELP A property name of a data attribute.
static java.lang.String	DATA_PROMPT A property name of a data attribute.
static java.lang.String	DATA_SEMANTIC_TYPE A property name of a data attribute.
static java.lang.String	DATA_SEMANTIC_TYPE_2 A property name of a data attribute.
static java.lang.String	DATA_SYNTAX_TYPE A property name of a data attribute.
static java.lang.String	FAULT_NOT_FOUND A fault string.
static java.lang.String	FAULT_NOT_IMPLEMENTED A fault string.
static java.lang.String	FAULT_NOT_RUNNABLE A fault string.
static java.lang.String	FAULT_NOT_RUNNING A fault string.
static java.lang.String	FAULT_NOT_TERMINATED A fault string.
static java.lang.String	FAULT_NOT_VALID_INPUTS A fault string.
static java.lang.String	FAULT_NOTIFY_UNACCEPTED A fault string.
static java.lang.String	FAULT_UNKNOWN_NAME A fault string.
static java.lang.String	INPUT_ALLOWED_VALUES A property name of a data input.
static java.lang.String	INPUT_DEFAULT_VALUE A property name of a data input.
static java.lang.String	INPUT_MANDATORY A property name of a data input.
static java.lang.String	INPUT_NAME A property name of a data input.
static java.lang.String	INPUT_TYPE A property name of a data input.
static java.lang.String	JOB_COMPLETED A job status: Job has completed execution.
static java.lang.String	JOB_CREATED A job status: Job has been created but not yet executed.
static java.lang.String	JOB_RUNNING A job status: Job is running.
static java.lang.String	JOB_TERMINATED_BY_ERROR A job status: Job was terminated due to an error.
static java.lang.String	JOB_TERMINATED_BY_REQUEST A job status: Job was terminated by user request.
static java.lang.String	RESULT_NAME A property name of a data output (a result).
static java.lang.String	RESULT_TYPE A property name of a data output (a result).

Method Summary

java.lang.String	createAndRun(java.util.Map inputs) A convenient combination of methods createJob(java.util.Map) and run.
java.lang.String	createAndRunNotifiable(java.util.Map inputs, java.lang.String notificationDescriptor) The same as createAndRun(java.util.Map) with addition of the channel notification negotiation.
java.lang.String	createJob(java.util.Map 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.
java.util.Map	getAnalysisType() Return attributes describing this analysis.
java.util.Map	getCharacteristics(java.lang.String jobID) A convenient method combining together methods getCreated(java.lang.String), getStarted(java.lang.String), getEnded(java.lang.String) and getElapsed(java.lang.String).
long	getCreated(java.lang.String jobID) Return a creation time of the given job.
long	getElapsed(java.lang.String jobID) Return the elapsed time of the execution of the given job (in milliseconds).
long	getEnded(java.lang.String jobID) Return time when the given job ended.
java.util.Map[]	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.
java.util.Map	getResults(java.lang.String jobID) Return all (available) results from the given job.
java.util.Map[]	getResultSpec() Return information about all possible results.
java.util.Map	getSomeResults(java.lang.String jobID, java.lang.String[] resultNames) Return named (and available) results from the given job.
long	getStarted(java.lang.String jobID) Return time when the given job started.
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.
java.util.Map	runAndWaitFor(java.util.Map 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.

Field Detail

FAULT_NOT_FOUND

static final java.lang.String FAULT_NOT_FOUND

A fault string.

See Also:

Defining exceptions, Constant Field Values

FAULT_NOT_RUNNABLE

static final java.lang.String FAULT_NOT_RUNNABLE

A fault string.

See Also:

Defining exceptions, Constant Field Values

FAULT_NOT_RUNNING

static final java.lang.String FAULT_NOT_RUNNING

A fault string.

See Also:

Defining exceptions, Constant Field Values

FAULT_NOT_VALID_INPUTS

static final java.lang.String FAULT_NOT_VALID_INPUTS

A fault string.

See Also:

Defining exceptions, Constant Field Values

FAULT_NOT_TERMINATED

static final java.lang.String FAULT_NOT_TERMINATED

A fault string.

See Also:

Defining exceptions, Constant Field Values

FAULT_UNKNOWN_NAME

static final java.lang.String FAULT_UNKNOWN_NAME

A fault string.

See Also:

Defining exceptions, Constant Field Values

FAULT_NOTIFY_UNACCEPTED

static final java.lang.String FAULT_NOTIFY_UNACCEPTED

A fault string.

See Also:

Defining exceptions, Constant Field Values

FAULT_NOT_IMPLEMENTED

static final java.lang.String FAULT_NOT_IMPLEMENTED

A fault string.

See Also:

Defining exceptions, Constant Field Values

ANALYSIS_TYPE

static final java.lang.String ANALYSIS_TYPE

A property name for an analysis type.

See Also:

Constant Field Values

ANALYSIS_NAME

static final java.lang.String ANALYSIS_NAME

A property name for an analysis name.

See Also:

Constant Field Values

ANALYSIS_SUPPLIER

static final java.lang.String ANALYSIS_SUPPLIER

A property name for an analysis supplier.

See Also:

Constant Field Values

ANALYSIS_VERSION

static final java.lang.String ANALYSIS_VERSION

A property name for an analysis version.

See Also:

Constant Field Values

ANALYSIS_INSTALLATION

static final java.lang.String ANALYSIS_INSTALLATION

A property name for an analysis installation.

See Also:

Constant Field Values

ANALYSIS_DESCRIPTION

static final java.lang.String ANALYSIS_DESCRIPTION

A property name for an analysis description.

See Also:

Constant Field Values

ANALYSIS_HELP_URL

static final java.lang.String ANALYSIS_HELP_URL

A property name for an analysis URL with a detailed help.

See Also:

Constant Field Values

INPUT_TYPE

static final java.lang.String INPUT_TYPE

A property name of a data input.

See Also:

Constant Field Values

INPUT_NAME

static final java.lang.String INPUT_NAME

A property name of a data input.

See Also:

Constant Field Values

INPUT_ALLOWED_VALUES

static final java.lang.String INPUT_ALLOWED_VALUES

A property name of a data input.

See Also:

Constant Field Values

INPUT_DEFAULT_VALUE

static final java.lang.String INPUT_DEFAULT_VALUE

A property name of a data input.

See Also:

Constant Field Values

INPUT_MANDATORY

static final java.lang.String INPUT_MANDATORY

A property name of a data input.

See Also:

Constant Field Values

DATA_HELP

static final java.lang.String DATA_HELP

A property name of a data attribute.

See Also:

Constant Field Values

DATA_PROMPT

static final java.lang.String DATA_PROMPT

A property name of a data attribute.

See Also:

Constant Field Values

DATA_SEMANTIC_TYPE

static final java.lang.String DATA_SEMANTIC_TYPE

A property name of a data attribute.

See Also:

Constant Field Values

DATA_SEMANTIC_TYPE_2

static final java.lang.String DATA_SEMANTIC_TYPE_2

A property name of a data attribute.

See Also:

Constant Field Values

DATA_SYNTAX_TYPE

static final java.lang.String DATA_SYNTAX_TYPE

A property name of a data attribute.

See Also:

Constant Field Values

RESULT_TYPE

static final java.lang.String RESULT_TYPE

A property name of a data output (a result).

See Also:

Constant Field Values

RESULT_NAME

static final java.lang.String RESULT_NAME

A property name of a data output (a result).

See Also:

Constant Field Values

JOB_CREATED

static final java.lang.String JOB_CREATED

A job status: Job has been created but not yet executed.

See Also:

Constant Field Values

JOB_RUNNING

static final java.lang.String JOB_RUNNING

A job status: Job is running.

See Also:

Constant Field Values

JOB_COMPLETED

static final java.lang.String JOB_COMPLETED

A job status: Job has completed execution.

See Also:

Constant Field Values

JOB_TERMINATED_BY_REQUEST

static final java.lang.String JOB_TERMINATED_BY_REQUEST

A job status: Job was terminated by user request.

See Also:

Constant Field Values

JOB_TERMINATED_BY_ERROR

static final java.lang.String JOB_TERMINATED_BY_ERROR

A job status: Job was terminated due to an error.

See Also:

Constant Field Values

Method Detail

describe

java.lang.String describe()
                          throws SoaplabException

Return an XML string containing metadata describing this analysis service. The ubiquitous question is what format such XML string should have. One solution is to use the DTD used in the AppLab project (concretely in metadata/AppLabAnalysis.dtd).

Throws:

SoaplabException - if communication with the service fails

getInputSpec

java.util.Map[] getInputSpec()
                             throws SoaplabException

Return information about all possible data inputs. Each element of the returned Map describes 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(java.util.Map) or runAndWaitFor(java.util.Map)).
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.)

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

java.util.Map[] 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[][]).

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

java.util.Map getAnalysisType()
                              throws SoaplabException

Return attributes describing this analysis. 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(java.util.Map 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 FAULT_UNKNOWN_NAME if there is an unrecognized input name

fault string 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(java.util.Map). 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 FAULT_NOT_FOUND if the given job ID does not exist

fault string FAULT_NOT_RUNNABLE if the same job was alredy executed, or if the data given previously by createJob(java.util.Map) 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 FAULT_NOTIFY_UNACCEPTED if the server does not agree on using the proposed notification channel

createAndRun

java.lang.String createAndRun(java.util.Map inputs)
                              throws SoaplabException

A convenient combination of methods createJob(java.util.Map) 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 FAULT_UNKNOWN_NAME if there is an unrecognized input name

fault string 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(java.util.Map inputs,
                                        java.lang.String notificationDescriptor)
                                        throws SoaplabException

The same as createAndRun(java.util.Map) with addition of the channel notification negotiation. See details here.

Throws:

SoaplabException - as in createAndRun(java.util.Map) plus (see defining exceptions) using:

fault string 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 FAULT_NOT_FOUND if the given job ID does not exist

fault string FAULT_NOT_IMPLEMENTED if the implementation refuses this request

runAndWaitFor

java.util.Map runAndWaitFor(java.util.Map 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 FAULT_UNKNOWN_NAME if there is an unrecognized input name

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

fault string 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 FAULT_NOT_FOUND if the given job ID does not exist

fault string 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 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 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 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 FAULT_NOT_FOUND if the given job ID does not exist

getCreated

long getCreated(java.lang.String jobID)
                throws SoaplabException

Return a creation time of the given job. Expressed in seconds, counting from the beginning of the UNIX epoch (1.1.1970).

Throws:

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

fault string FAULT_NOT_FOUND if the given job ID does not exist

getStarted

long getStarted(java.lang.String jobID)
                throws SoaplabException

Return time when the given job started. Expressed in seconds, counting from the beginning of the UNIX epoch (1.1.1970). Return -1 if the job has not yet started.

Throws:

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

fault string FAULT_NOT_FOUND if the given job ID does not exist

getEnded

long getEnded(java.lang.String jobID)
              throws SoaplabException

Return time when the given job ended. Expressed in seconds, counting from the beginning of the UNIX epoch (1.1.1970). Return -1 if the job has not yet ended.

Throws:

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

fault string FAULT_NOT_FOUND if the given job ID does not exist

getElapsed

long getElapsed(java.lang.String jobID)
                throws SoaplabException

Return the elapsed time of the execution of the given job (in milliseconds). Return 0 if the job has not yet started.

Throws:

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

fault string FAULT_NOT_FOUND if the given job ID does not exist

getCharacteristics

java.util.Map getCharacteristics(java.lang.String jobID)
                                 throws SoaplabException

A convenient method combining together methods getCreated(java.lang.String), getStarted(java.lang.String), getEnded(java.lang.String) and getElapsed(java.lang.String). It returns a Map with keys equals to the individual method names (without prefix 'get', and in lowercase).

Throws:

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

fault string FAULT_NOT_FOUND if the given job ID does not exist

getResults

java.util.Map 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 FAULT_NOT_FOUND if the given job ID does not exist

getSomeResults

java.util.Map 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 FAULT_NOT_FOUND if the given job ID does not exist

fault string 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 FAULT_NOT_FOUND if the given job ID does not exist