SoapLab - WebService for invoking remote analyses

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

See:
Description

Packages

org.embl.ebi.analysis
org.embl.ebi.SoaplabServer.gowlab
org.embl.ebi.SoaplabShare

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

The main interface is AnalysisWS. A supplementary interface AnalysisFactoryWS should be replaced in the real and ready word by some discovery (naming, trading) service.

Additionally, for the Gowlab sub-project, there are plug-in interfaces RunPlugIn and DataAdaptPlugIn. Usage of both these interfaces are described more detailed in Gowlab plug-ins. There are also several basic implementations of RunPlugIn inteface:

• RunPlugInDefaultImpl fetches data from a remote web resource
• RunPlugInXSLTImpl fetches data and converts them by an XSLT stylesheet
• RunPlugInExternalImpl lets an exteranl program/script to fetch data

Usage scenarios

There are several scenarios how and what methods to use (see details by method descriptions). These scenarios differ mainly because of the "state-fullness" or "state-lessness" service implementation. Some implementations may provide only some of these scenarios.

• A state-full implementation

     jobID = createJob (inputs);    // create a job with input data
     run (jobID);                   // execute the job
     waitFor (jobID);               // wait for its completion
     results = getResults (jobID);  // retrieve resulting data
     

  Advantages: Input data validation can be done long before the job starts; full notification schema is available; full details, what is happening with the job, are available.

• A semi state-full implementation
  Often running a job is delegated to an underlying queueing system which can manage and keep some state information (like keeping results until someone takes them) - but the web service itself can be implemented in a state-less manner (in such case, the jobID is provided by the queueing system):

     jobID = createAndRun (inputs); // create a job and start it
     waitFor (jobID);               // wait for its completion
     results = getResults (jobID);  // retrieve resulting data
     

  Advantages: Less stressing on the service implementation; "server-push" notification and full details about running job are still available.

• A state-less implementation

     results = runAndWaitFor (inputs);  // create job, start it, wait for results
     

  Advantages: Easy service implementation (but not necessarily less resource consuming because it needs very threaded service implementation - individual threads may last long).

Notification negotiation and notification channels

A running job changes its state and the user may be interested in being notified about these changes. A prominent change in the job life-cycle is, of course, when the job terminates (either by an error or by the user request). The AnalysisWS interface provides two ways how to pass information about job changes to the clients: method AnalysisWS.getLastEvent(java.lang.String), or using a notification channel.

The method AnalysisWS.getLastEvent(java.lang.String) must be invoked by the client, and it informs about the latest job status or job status change.

The notification channel is more complex (and more powerful) way. However, the implementation may decide not to provide it at all. It uses another service to transport event messages (which may involve things like setting an expiration time, secure channels, or postponed and re-tried deliveries etc.). All you need to know about a notification channel is defined in a channel descriptor (an XML string whose DTD yet to be defined). There are the following ways how to get and use notification channels:

• Usually, it is the server (service-provider program) who knows about a suitable notification channel. The client must ask the server to get it - it is a per job request (which does not, however, preclude the server to use the same notification channel for more jobs and more clients):

     jobID = createJob (inputs);
     channelDescriptor = getNotificationDescriptor (jobID);
     // use the 'channelDescriptor' (if it is not empty):
     //    subscribe itself to it
     //    (which may include starting a separate thread waiting
     //    for server-push calls, or starting your own polling thread)
     run (jobID);
     ...
     

• However, a client may wish to negotiate to use its own notification channel (e.g. because it is guaranteed to be used only by this client, or because it uses a special quality of service, or because it prefers to use a different notification protocol - such as an email notification). The proposed notification descriptor can be passed in the runNotifiable (jobID, myDescriptor) or createAndRunNotifiable (inputs, myDescriptor):

     jobID = createJob (inputs);
     run (jobID, myChannelDescriptor);
     

  The server may refuse to use the suggested notification channel (e.g. if it does not understand the notification protocol defined in the channel descriptor).

Events describing running analyses

The chapter above described how to exchange messages. This chapter tells what is being exchanged - it is about the contents of the event messages.

The events are expressed as short XML strings. The DTD describing the events is simple and extendible in order to include provider-specific events. Here are some examples of various events:

AnalysisEvent_test.xml (see it as text) (a general event)

AnalysisEventHeartbeat_test.xml (see it as text)

AnalysisEventPercent_test.xml (see it as text)

AnalysisEventStateChanged_test.xml (see it as text)

AnalysisEventStep_test.xml (see it as text)

AnalysisEventTime_test.xml (see it as text)

AnalysisEventHeartbeat_test.xml (see it as text) (an example of an extended event)

Defining exceptions

Any Web Service call can raise an exception (fault). They can be defined by the fault code, fault string, fault actor and fault details. This interface will use the following rules to deliver details about any exception:

• The fault code used will be one of the standard fault codes: "Server" or "Client" (every method specifies which one to use and when).
• The fault strings are specified by the methods, and they carry the most significant information about what has happened. This interface contains a set of pre-defined constant fault strings.
• A rule about fault actor and fault details will come here when I understand it better :-)

Last modified: Thu Apr 8 10:19:41 2004