Soaplab distribution has only basic clients that help mostly service providers to check their installation. The end users are keen to use sophisticated clients (an ultimate example is Taverna). This document shows how to start writing your own Java clients.

Note that there is also a possibility to write just your own Java plug-in. This is related to the Gowlab-based services and details are in the Gowlab Guide.

The easiest way for developing is to use Soaplab CVS. Put your source code anywhere below src/Clients or src/main, and use Ant to build it:

   ./build-dev.sh

   . run/source.me.sh
   source run/source.me.csh

It would be nice to have a paragraph here how to integrate the Soaplab's Ant with an IDE, such as Eclipse. Please let me know if you have done it.

For convenience and readability, the APIs showing available methods are formatted by the javadoc tool, even though the Web Services are programming-language independent.

There are three types of services (see also the Architecture Guide):

• Factory (List) service is defined by the Java interface org.embl.ebi.SoaplabShare.AnalysisFactoryWS. And there is nothing special about its methods.

• Analysis service is defined by the Java interface org.embl.ebi.SoaplabShare.AnalysisWS. This is the main interface.

• The derived analysis services also implements the org.embl.ebi.SoaplabShare.AnalysisWS interface but their main power is in having additional methods (which are specific for each Soaplab service):

  String createEmptyJob()

  This method is the same for all derived analysis services. It must be used before adding any input data to a created job. It returns a job's ID that can be used by the set_... methods later to populate the job with the input data.

  void set_<name> (String jobId, <type> value)

  Each derived service has set methods for every possible input data. The method names differ according to the input data names - a developer needs to check the service description (either its WSDL, or by calling its method getInputSpec) to find what methods are available. The checking is done on the service this derived service was derived from.

  Some services may have quite a number of such methods. And some of them may be mutually exclusive. For example, the EMBOSS sequence analysis programs often require an input sequence. The sequence can be specified directly, as a string, or as a so-called universal sequence address (an EMBOSS-specific term). The relevant methods in these cases are:

     void set_sequence_direct_data (String jobId, String value)
     void set_sequence_usa (String jobId, String value)
         

  <type> get_<name> (String jobId)

  Each result (output data) of any derived service is obtainable using a specific get... method. All Soaplab's services always have at least two results, report and detailed_status, accessible by methods:

     String get_report (String jobId)
     String get_detailed_status (String jobId)
         

  The report shows human readable details about the execution, and the detailed_status returns a number (although coded as a String) defining the exit condition. It can be used by programs to make decision how to proceed (successful execution returns zero or 200 - for Gowlab services).

Coding examples

A src/Clients/FactoryClient.java is a good example how to implement the org.embl.ebi.SoaplabShare.AnalysisFactoryWS interface.

Or, here is code for a client getting all available service names from the EBI's services:

import embl.ebi.soap.axis.*;
import java.net.*;

public class SimplestList {

    public static void main (String [] args) {
	try {
	    // where to go
	    String endpoint =
               "http://www.ebi.ac.uk/soaplab/services/AnalysisFactory";
	    if (args.length > 0)
		endpoint = args[0];

	    // make the call
	    String[] names =
		(String[])new AxisCall (new URL (endpoint))
		.doCall ("getAvailableAnalyses", new Object[] {});

	    // print results
	    if (names != null)
		for (int i = 0; i < names.length; i++)
		    System.out.println (names[i]);
	    System.out.println();

	} catch (Exception e) {
	    System.err.println (e.toString());
	}
    }
}

• HelloWorldClient shows how to call the simplest method, without any data inputs.

• SeqretClient shows how to set sequence data into a reformatting service (using a derived service).

• CpgplotClient shows how to deal with a binary (graphical) result (it even shows a picture if you are using JDK 1.3 or later).

  	Where to go next?

  Guide to ready-to-use Soaplab clients

  Martin Senger
  

  Last modified: Sun Oct 7 15:10:03 2007