EMBL-EBI Web Services

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Apache Axis ======

===== Introduction =====

Apache Axis ((Apache Axis - http://ws.apache.org/axis/)) is an implementation of the SOAP ((SOAP - http://www.w3.org/TR/soap/)) submission to W3C ((W3C - http://www.w3.org/)) and follows-on from the Apache SOAP project. Apache Axis is an implementation of the JAX-RPC standard ((JAX-RPC - http://jcp.org/en/jsr/detail?id=101)).

An important feature of Apache Axis is support for both RPC/encoded and Document/literal style SOAP services and the inclusion of a WSDL to Java code generator supporting both styles.

**Please note**: Apache Axis2 ((Apache Axis2/Java - http://axis.apache.org/axis2/java/core/)) is not the version of Apache Axis described here.
===== Installation =====

Apache Axis 1.x is available for download from: http://ws.apache.org/axis/

==== Apache Ivy ====

If using Apache Ivy ((Apache Ivy - http://ant.apache.org/ivy/)) the following dependency declarations can be used:
<code xml>
<!-- Apache Axis 1.x -->
<dependency org="commons-logging" name="commons-logging" rev="1.1.1" />
<dependency org="wsdl4j" name="wsdl4j" rev="1.6.2" />
<dependency org="commons-discovery" name="commons-discovery" rev="0.2" />
<dependency org="org.apache.axis" name="axis" rev="1.4" />
<dependency org="org.apache.axis" name="axis-jaxrpc" rev="1.4" />
</code>

==== Apache Maven ====

If using Apache Maven ((Apache Maven - http://maven.apache.org/)) the following dependency declarations can be used:
<code xml>
<dependency>
  <groupId>commons-logging</groupId>
  <artifactId>commons-logging</artifactId>
  <version>1.1.1</version>
  <scope>compile</scope>
</dependency>
<dependency>
  <groupId>axis</groupId>
  <artifactId>axis</artifactId>
  <version>1.4</version>
  <scope>compile</scope>
</dependency>
<dependency>
  <groupId>org.apache.axis</groupId>
  <artifactId>axis-jaxrpc</artifactId>
  <version>1.4</version>
  <scope>compile</scope>
</dependency>
<dependency>
  <groupId>org.apache.axis</groupId>
  <artifactId>axis-saaj</artifactId>
  <version>1.4</version>
  <scope>compile</scope>
</dependency>
<dependency>
  <groupId>axis</groupId>
  <artifactId>axis-wsdl4j</artifactId>
  <version>1.5.1</version>
  <scope>compile</scope>
</dependency>
<dependency>
  <groupId>commons-discovery</groupId>
  <artifactId>commons-discovery</artifactId>
  <version>0.4</version>
  <scope>compile</scope>
</dependency>
</code>

==== EMBL-EBI Sample Client Dependencies ====

For the Apache Axis 1.x based sample clients we provide an archive containing all the required dependencies: ''[[http://www.ebi.ac.uk/Tools/webservices/downloads/java/lib-1.4.zip|lib-1.4.zip]]''.

This includes the development tools and can be used via the ''-Djava.ext.dirs'' option when running a client, for example if the ''lib-1.4.zip'' archive was unpacked in the current directory (creating a ''lib'' sub-directory) and the sample WSDbfetch client jar is in the current directory the client could be run using:
<code csh>java -Djava.ext.dirs=lib -jar WSDbfetch_Axis1.jar</code>

===== Creating Stubs Using WSDL2Java ======

The Axis WSDL2Java tool generates client classes representing the service interface from a WSDL interface definition. By default the generated ''.java'' files will be placed into a ''package'' based on the namespace used in the WSDL. To specify a specific ''package'' for the generated classes use the ''-p'' option.

For details of the WSDL documents available for [[:about:webservices|EBI Web Services]] see the service page for the service of interest.

**Note**: the stubs generated by Axis WSDL2Java are version specific. If you want to use a different version of Axis with the sample clients, you will have to regenerate and recompile the stubs.

==== Command-line ====

Generate stubs from a WSDL, in this case for [[:services:dbfetch|WSDbfetch]]:
<code csh>java org.apache.axis.wsdl.WSDL2Java http://www.ebi.ac.uk/ws/services/WSDbfetch?wsdl</code>
<BR>
In this case the stubs are generated in the ''uk.ac.ebi.www'' package.

To force the stubs into the ''uk.ac.ebi.webservices.wsdbfetch'' package:

<code csh>java org.apache.axis.wsdl.WSDL2Java -p uk.ac.ebi.webservices.wsdbfetch 
  http://www.ebi.ac.uk/ws/services/WSDbfetch?wsdl</code>
<BR>

==== Apache ant: generic task ====

To build stubs using the Apache ant ((Apache ant - http://ant.apache.org/)) build tool, without having to install additional tasks, a generic target can be defined which generates code stubs from a WSDL document:
<code xml>
<!-- Generate Axis 1.x stubs from a WSDL -->
<target name="genAxis1Stubs" description="Axis 1.x: generate stubs from a WSDL using WSDL2Java class">
	<echo message="${stubPkg}" />
	<echo message="${wsdlUrl}" />
	<java classname="org.apache.axis.wsdl.WSDL2Java" classpathref="classpath" fork="yes" dir="${src.dir}">
		<arg value="-p" />
		<arg value="${stubPkg}" />
		<arg value="${wsdlUrl}" />
	</java>
</target>
</code>

This assumes that the org.apache.axis.wsdl.WSDL2Java class in available in the classpath.

The ''genAxis1Stubs'' target can then be called with parameters in a service specific target to generate the stubs, for example for [[:services:dbfetch|WSDbfetch]]:
<code xml>
<!-- Generate Axis 1.x stubs for WSDbfetch -->
<target name="axis1-stubs-wsdbfetch" description="Axis 1.x: generate stubs for WSDbfetch">
	<antcall target="genAxis1Stubs">
		<param name="stubPkg" value="uk.ac.ebi.webservices.axis1.stubs.wsdbfetch" />
		<param name="wsdlUrl" value="http://www.ebi.ac.uk/ws/services/WSDbfetch?wsdl" />
	</antcall>
</target>
</code>

The target can then be referenced when invoking ant to generate the stubs:
<code csh>ant axis1-stubs-wsdbfetch</code>

An Apache ant ''build.xml'' file using this method to generate stubs for Apache Axis 1.x is included in the exercise project: [[http://www.ebi.ac.uk/Tools/webservices/downloads/java_exercises.zip|java_exercises.zip]]. By using this mechanism the project has a minimal set of dependencies, which are handled by an Apache Ivy configuration (the Ivy plug-in for ant is dynamically downloaded and added to the installation during the build process).

=== Exercise 1: Generate the service stubs. ===

Examine the Apache ant build file (''build.xml'') includes in the exercise project. You will see a number of ant tasks, these can be grouped into:
  * Setting up the environment
  * Cleaning the build directories
  * Obtaining and unpacking the dependencies archive
  * Generation of Axis stubs from a WSDL
  * Compiling of source code

To run the tasks described in the ant build file in Eclipse right-click on the ''build.xml'' file, select "Run As" -> "Ant Build..." and select the required targets.

To build the Apache Axis examples we need to run two targets:
  - ''axis1-stubs'': to generate the code stubs
  - ''axis1-compile'': to compile the generate stubs and the client code.

To run these in Eclipse:
  - Right-click on the ''build.xml'' file to bring up the menu
  - Select "Run As" -> "Ant Build..." to get the dialog describing the available targets
  - Select the ''axis1-stubs'' target to generate the stubs.
  - Use the "Order..." button to put ''axsi1-stubs'' before ''compile''
  - Click the "Run" button to invoke the ant build.
  - To ensure Eclipse recognises the generated code refresh the project:
    - Right click on the project (e.g. EBIWS_Java_Exercises)
    - Select "Refresh"

To run these targets from the command-line:
<code csh>
ant axis1-stubs
ant axis1-compile
</code>

==== Apache ant: Axis-wsdl2java task ====

Apache ant allows the addition of specific tasks via a plug-in mechanism. The Axis-wsdl2java task (http://ws.apache.org/axis/java/ant/axis-wsdl2java.html) supports the generation of Axis stubs from a WSDL document and, if installed, can be used as an alternative to the generic task above.

==== Apache maven ====

A Maven plug-in is also available to generate Axis code stubs from a WSDL document, see http://maven-plugins.sourceforge.net/maven-axis-plugin/index.html for details.

===== Using the Stubs =====

The stubs generated by Axis WSDL2Java are direct mappings of the interface and data types described in the WSDL into their Java equivalents. You may find looking at the generated code, [[:services:dbfetch|WSDbfetch service documentation]] and http://www.ebi.ac.uk/ws/services/WSDbfetch?wsdl useful in the following section.

Import the generated classes into the program (assuming the ''uk.ac.ebi.webservices.wsdbfetch'' package):
<code java>import uk.ac.ebi.webservices.wsdbfetch.*;</code>

To create a service proxy, with which you can interact with the service:
<code java>WSDBFetchServerService service =  new WSDBFetchServerServiceLocator();
WSDBFetchServer srvProxy = service.getWSDbfetch();</code>

The methods of the service proxy (''srvProxy'') map to those defined in the WSDL, so to call the ''fetchData'' method of the WSDbfetch service we can use:
<code java>String result = srvProxy.fetchData("UNIPROT:ADH1A_HUMAN", "default", "raw");</code>

The ''fetchData'' method returns a string containing the requested database entry, which can be output with:
<code java>System.out.println(result);</code>

Then compile in the usual way:
  - Using an IDE, such as Eclipse:
    * If "Build Automatically" is enabled the class is compiled when the source file is saved
    * Otherwise "Project", "Build All" can be used to compile all source files in the project.
  - Using Apache ant and the supplied ''build.xml'' file: <code csh>ant axis1-compile</code>
  - Using the Java commands from the command-line: <code csh>javac uk/ac/ebi/webservices/wsdbfetch/*.java
javac Dbfetch.java</code>

And then run the program, to check it works:
  - Using an IDE, such as Eclipse: right-click on the source file (e.g. ''Dbfetch.java''), select "Run As" and "Java Application".
  - From the command-line:
    * If the Apache Axis libraries have been added to the ''CLASSPATH'': <code csh>java Dbfetch</code>
    * If using a library directory called ''lib'' (as used in the supplied Eclipse project or the library archive): <code csh>java -Djava.ext.dirs=lib Dbfetch</code>

=== Exercise 2: WSDbfetch (SOAP) ===

The WSDbfetch web service (http://www.ebi.ac.uk/Tools/webservices/services/dbfetch) provides the same basic functionality as [[http://www.ebi.ac.uk/cgi-bin/dbfetch|dbfetch]], but through a collection of SOAP interfaces.

Using the example WSDbfetch client ([[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Java_Exercise/src/examples/soap/axis1/Dbfetch.java|examples/soap/axis1/Dbfetch.java]]) as a guide, use the service to fetch the [[http://www.ebi.ac.uk/uniprot/|UniProtKB]] entries with the accessions: P13569, P26361 and P35071, in fasta sequence format.

Sample solution: [[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Java_Exercise/src/solutions/soap/axis1/Q4Dbfetch.java|solutions/soap/axis1/Q4Dbfetch.java]]

=== Exercise 3: WSDbfetch meta-data ===

The [[:services:dbfetch|WSDbfetch]] service includes a number of meta-data methods which provide information about the service such as the names of the databases available, and the formats and styles which can be used with each database (see http://www.ebi.ac.uk/Tools/webservices/services/dbfetch).

Starting from the example client ([[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Java_Exercise/src/examples/soap/axis1/Dbfetch.java|examples/soap/axis1/Dbfetch.java]]), use the ''getDbFormats()'' method of the [[:services:dbfetch|WSDbfetch]] service determine what the available data formats are for the [[http://www.ebi.ac.uk/uniprot/|UniProtKB]] database.

Sample solution: [[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Java_Exercise/src/solutions/soap/axis1/Q5Dbfetch.java|solutions/soap/axis1/Q5Dbfetch.java]]

==== Complex Data Structures ====

The methods in the [[:services:dbfetch|WSDbfetch service]] all use simple string parameters. Many of the other EBI services use more complex input structures. For example [[:services:sss:NCBI BLAST (SOAP)]] requires a structure containing the various parameters and the input sequence to be passed to the ''[[:services:sss:NCBI BLAST (SOAP)#run(email, title, params)]]'' method:
<code java>
// Populate input parameters structure
InputParameters params = new InputParameters();
params.setProgram("blastp");
String[] databaseList = { "uniprotkb_swissprot" };
params.setDatabase(databaseList);
params.setStype("protein");
params.setSequence(">Seq1 Example search sequence\n"
	+ "MKFLILLFNILCLFPVLAADNHGVGPQGASGVDPITFDINSNQTGPAFLTAVEMAGV");
String email = "email@example.org"; // Your e-mail address
// Get the NCBI BLAST (SOAP) service proxy
JDispatcherService_Service service = new JDispatcherService_ServiceLocator();
JDispatcherService_PortType ncbiblast = service.getJDispatcherServiceHttpPort();
// Submit the job
String jobid = ncbiblast.run(email, "", params);
System.out.println("Job Id: " + jobid);
</code>

The ''[[:services:sss:NCBI BLAST (SOAP)#run(email, title, params)]]'' method returns a job identifier which can be used with the ''[[:services:sss:NCBI BLAST (SOAP)#getStatus(jobId)]]'' method to get the status of the job (e.g. ''RUNNING'', ''FINISHED'' or ''ERROR''), the ''[[:services:sss:NCBI BLAST (SOAP)#getResultTypes(jobId)]]'' method to get details of the available results for a finished job and the ''[[:services:sss:NCBI BLAST (SOAP)#getResult(jobId, type)]]'' method to get the results of the job.

<code java>
// Poll until job has finished
String status = "RUNNING";
while (status.equals("RUNNING")) {
	Thread.sleep(3000); // Wait 3 seconds
	status = ncbiblast.getStatus(jobid); // check job status
	System.out.println(status);
}
// If the job completed successfully...
if (status.equals("FINISHED")) {
	// Get the text result
	byte[] resultbytes = ncbiblast.getResult(jobid, "out", null);
	String result = new String(resultbytes);
	// Output the result
	System.out.println(result);
}
</code>

=== Exercise 4: NCBI BLAST (SOAP) ===

So far all the services we have looked at have been able to return the result in a relatively short period of time. This is not the case when running analytical tools, which in extreme cases may take days to return a result. So for these tools asynchronous methods have to be used, where the submission returns a job identifier which can be then used to check on the status of the job, and once it completes retrieve the results. The [[:services:sss:NCBI BLAST (SOAP)]] service, uses the NCBI BLAST suite to perform a sequence similarity search requires this approach. Examine the example client ([[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Java_Exercise/src/examples/soap/axis1/NcbiBlastSoap.java|examples/soap/axis1/NcbiBlastSoap.java]]) and note the "run", "getStatus" and "getResult" work flow.

Using the example client as a guide, perform an NCBI BLAST search with UniProtKB CFTR_MOUSE (''uniprot:CFTR_MOUSE'') against UniProtKB/SwissProt (''uniprotkb_swissprot'').

Sample solution: [[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Java_Exercise/src/solutions/soap/axis1/Q8NcbiBlastSoap.java|solutions/soap/axis1/Q8NcbiBlastSoap.java]]

=== Exercise 5: NCBI BLAST (SOAP) meta-data ===

The [[:services:sss:NCBI BLAST (SOAP)]] service can return the result in a number of formats, modify your client to use the ''[[:services:sss:NCBI BLAST (SOAP)#getResultTypes(jobId)]]'' method to discover the other available result types.

Sample solution: [[http://www.ebi.ac.uk/Tools/webservices/workshop/EBIWS_Java_Exercise/src/solutions/soap/axis1/Q9NcbiBlastSoap.java|solutions/soap/axis1/Q9NcbiBlastSoap.java]]

===== Proxies =====

In some environments it is necessary to configure an HTTP proxy before a client can connect to external services. Apache Axis supports the normal Java mechanisms for the configuration of proxies:
  - Java system properties:
    * Provided to the JVM: <code csh>java -Dhttp.proxyHost=proxy.example.org -Dhttp.proxyPort=8080 ExampleClientClass</code>
    * Set in client code: <code java>
System.setProperty("http.proxyHost", "proxy.example.org");
System.setProperty("http.proxyPort", "8080");
</code>
  - Using the java.net.Proxy and java.net.ProxySelector classes.

For details and examples see:
  * Networking Properties: http://download.oracle.com/javase/6/docs/technotes/guides/net/properties.html
  * Java Networking and Proxies: http://download.oracle.com/javase/6/docs/technotes/guides/net/proxies.html
  * Apache Axis network configuration: http://ws.apache.org/axis/java/client-side-axis.html#NetworkConfiguration

===== User-Agent =====

HTTP clients usually provide information about what they are, allowing services to handle specific clients differently if necessary, and giving service providers some information about how their services are being used. By default Apache Axis sets the HTTP User-Agent header (see [[http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43|RFC2616 section 14.43]]) to something like ''Axis/1.4'', where the version number (1.4) is the version of Apache Axis.

The user-agent string is set in the ''/org/apache/axis/i18n/resource.properties'' file in the Apache Axis JAR.

**Note**: while the HTTP specification does not define a limit on the size of HTTP headers, web server implementations often do limit the maximum size of an HTTP header to 8KB or 16KB. If the server limit for an HTTP header is exceeded a "400 Bad Request" will be returned by the server.

===== Service End-point and Namespace =====

In cases where access is required to alternative instance of the web service, the end-point address for the service will need to be modified. In Apache Axis these can be overridden when getting the service proxy object by specifying the required end-point address, for example:
<code java>
String srvEndpoint = "http://wwwdev.ebi.ac.uk/ws/services/WSDbfetchDoclit";
WSDBFetchDoclitServerService service = new WSDBFetchDoclitServerServiceLocator();
WSDBFetchServer srvProxy = service.getWSDbfetchDoclit();
</code>

===== HTTP Compression =====

In order to save bandwidth HTTP provides mechanisms to compress the messages exchanged between the client and the server. 

In Apache Axis support for HTTP compression requires that Commons HttpClient ((Commons HttpClient 3.x - http://hc.apache.org/httpclient-3.x/)) is used to provide the HTTP transport. This is enabled by ensuring that Commons HttpClient is available on the CLASSPATH and providing a ''client-config.wsdd'' which tells Apache Axis to use Commons HttpClient at the transport:

<code xml>
<deployment name="commonsHTTPConfig" xmlns="http://xml.apache.org/axis/wsdd/" xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
  <!-- Use CommonsHTTPSender instead of the default HTTPSender (requires Commons HttpClient) -->
  <transport name="http" pivot="java:org.apache.axis.transport.http.CommonsHTTPSender" />  
  <transport name="local" pivot = "java:org.apache.axis.transport.local.LocalSender" /> 
  <transport name="java" pivot="java:org.apache.axis.transport.java.JavaSender" /> 
</deployment>
</code>

When the Commons HttpClient based transport is used, the Apache Axis HTTP compression options become available. The simplest way to enable HTTP compression in Apache Axis is to subclass the service locator and override the ''createCall()'' method to enable compression on the call. For example:

<code java>
/** Wrapper for WSDBFetchDoclitServerServiceLocator to enable HTTP 
 * compression.
 * 
 * Compression requires Commons HttpClient and a client-config.wsdd which 
 * specifies that Commons HttpClient should be used as the HTTP transport.
 * See http://wiki.apache.org/ws/FrontPage/Axis/GzipCompression.
 */
private class WSDBFetchDoclitServerServiceLocatorExtended extends WSDBFetchDoclitServerServiceLocator {
  private static final long serialVersionUID = 1L;

  public Call createCall() throws ServiceException {
    Call call = super.createCall();
    // Enable response compression.
    call.setProperty(HTTPConstants.MC_ACCEPT_GZIP, Boolean.TRUE);
    // Enable request compression (requires service support)
    call.setProperty(HTTPConstants.MC_GZIP_REQUEST, Boolean.TRUE);
    return call;
  }
}
</code>

For HTTP response compression the client requests that the response be compressed, but if the server does not support compression the client will correctly handle the uncompressed result received. So this can be safely enabled for all requests. 

However HTTP request compression **requires** that the service support HTTP request compression in order to work at all. Typically if HTTP request compression is not supported by the service the HTTP status returned by the service when sent a compressed request will be a "415 Unsupported Media Type", although XML parsing errors are also a commonly seen problem when the service does not support request compression. As a consequence HTTP request compression should only be enabled if it is known that the service supports it.

Once the required compression options are enabled the subclass is then used to obtain the service proxy in the normal way, for example:
<code java>
WSDBFetchDoclitServerService service = new WSDBFetchDoclitServerServiceLocatorExtended();
WSDBFetchServer srvProxy = service.getWSDbfetchDoclit();
</code>

===== Sample Clients =====

Most SOAP Web Services at [[http://www.ebi.ac.uk/|EMBL-EBI]] have sample clients which provide command-line access to the service and example code. For Java some of the clients are based on Apache Axis 1.x.

==== Document/literal SOAP ====

^ Service ^ Sample client ^
| [[:services:EB-eye]] | Executable jar: ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/java/jar/EBeye_Axis1.jar|EBeye_Axis1.jar]]'';\\ Source code: ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/java/src/uk/ac/ebi/webservices/axis1/EBeyeClient.java|EBeyeClient.java]]'' |
| [[:services:pfa:iprscan_soap|InterProScan (SOAP)]] | Executable jar: ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/java/jar/IPRScan_Axis1.jar|IPRScan_Axis1.jar]]'';\\ Source: ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/java/src/uk/ac/ebi/webservices/AbstractWsToolClient.java|AbstractWsToolClient.java]]'', ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/java/src/uk/ac/ebi/webservices/axis1/IPRScanClient.java|IPRScanClient.java]]'' |
| [[:services:sss:NCBI BLAST (SOAP)]] | Executable jar: ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/java/jar/NCBIBlast_Axis1.jar|NCBIBlast_Axis1.jar]]'';\\ Source: ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/java/src/uk/ac/ebi/webservices/AbstractWsToolClient.java|AbstractWsToolClient.java]]'', ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/java/src/uk/ac/ebi/webservices/axis1/NCBIBlastClient.java|NCBIBlastClient.java]]'' |
| [[:services:dbfetch|WSDbfetch (SOAP)]] | Executable jar: ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/java/jar/WSDbfetch_Axis1.jar|WSDbfetch_Axis1.jar]]'';\\ Source: ''[[http://www.ebi.ac.uk/Tools/webservices/download_clients/java/src/uk/ac/ebi/webservices/axis1/WSDbfetchClient.java|WSDbfetchClient.java]]'' |

==== RPC/encoded SOAP ====

^ Service ^ Sample client ^
| [[:services:dbfetch|WSDbfetch]] | Executable jar: ''[[http://www.ebi.ac.uk/Tools/webservices/downloads/java/bin/WSDbfetch.jar|WSDbfetch.jar]]'';\\ Source: ''[[http://www.ebi.ac.uk/Tools/webservices/downloads/java/src/uk/ac/ebi/webservices/WSDbfetchClient.java|WSDbfetchClient.java]]'' |

\\
^ Up | [[..:..:Java]] ^ Contents | [[..:..:..:00_Contents|Contents]] |
EMBL-EBI Web Services

EMBL-EBI

Services

Research

Training

Industry

About us
