Apache Axis ¹⁾ is an implementation of the SOAP ²⁾ submission to W3C ³⁾ and follows-on from the Apache SOAP project. Apache Axis is an implementation of the JAX-RPC standard ⁴⁾.

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 ⁵⁾ is not the version of Apache Axis described here.

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

If using Apache Ivy ⁶⁾ the following dependency declarations can be used:

<!-- 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" />

If using Apache Maven ⁷⁾ the following dependency declarations can be used:

<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>

For the Apache Axis 1.x based sample clients we provide an archive containing all the required dependencies: 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:

java -Djava.ext.dirs=lib -jar WSDbfetch_Axis1.jar

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 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.

Generate stubs from a WSDL, in this case for WSDbfetch:

java org.apache.axis.wsdl.WSDL2Java http://www.ebi.ac.uk/ws/services/WSDbfetch?wsdl

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:

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

To build stubs using the Apache ant ⁸⁾ build tool, without having to install additional tasks, a generic target can be defined which generates code stubs from a WSDL document:

<!-- 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>

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 WSDbfetch:

<!-- 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>

The target can then be referenced when invoking ant to generate the stubs:

ant axis1-stubs-wsdbfetch

An Apache ant build.xml file using this method to generate stubs for Apache Axis 1.x is included in the exercise project: 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).

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:

1. axis1-stubs: to generate the code stubs
2. axis1-compile: to compile the generate stubs and the client code.

To run these in Eclipse:

1. Right-click on the build.xml file to bring up the menu
2. Select “Run As” → “Ant Build…” to get the dialog describing the available targets
3. Select the axis1-stubs target to generate the stubs.
4. Use the “Order…” button to put axsi1-stubs before compile
5. Click the “Run” button to invoke the ant build.
6. To ensure Eclipse recognises the generated code refresh the project:
   1. Right click on the project (e.g. EBIWS_Java_Exercises)
   2. Select “Refresh”

To run these targets from the command-line:

ant axis1-stubs
ant axis1-compile

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.

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.

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, 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):

import uk.ac.ebi.webservices.wsdbfetch.*;

To create a service proxy, with which you can interact with the service:

WSDBFetchServerService service =  new WSDBFetchServerServiceLocator();
WSDBFetchServer srvProxy = service.getWSDbfetch();

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:

String result = srvProxy.fetchData("UNIPROT:ADH1A_HUMAN", "default", "raw");

The fetchData method returns a string containing the requested database entry, which can be output with:

System.out.println(result);

Then compile in the usual way:

1. 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.
2. Using Apache ant and the supplied build.xml file:

   ant axis1-compile

3. Using the Java commands from the command-line:

   javac uk/ac/ebi/webservices/wsdbfetch/*.java
   javac Dbfetch.java

And then run the program, to check it works:

1. Using an IDE, such as Eclipse: right-click on the source file (e.g. Dbfetch.java), select “Run As” and “Java Application”.
2. From the command-line:
   • If the Apache Axis libraries have been added to the CLASSPATH:

     java Dbfetch

   • If using a library directory called lib (as used in the supplied Eclipse project or the library archive):

     java -Djava.ext.dirs=lib Dbfetch

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

Using the example WSDbfetch client (examples/soap/axis1/Dbfetch.java) as a guide, use the service to fetch the UniProtKB entries with the accessions: P13569, P26361 and P35071, in fasta sequence format.

Sample solution: solutions/soap/axis1/Q4Dbfetch.java

The 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 (examples/soap/axis1/Dbfetch.java), use the getDbFormats() method of the WSDbfetch service determine what the available data formats are for the UniProtKB database.

Sample solution: solutions/soap/axis1/Q5Dbfetch.java

The methods in the WSDbfetch service all use simple string parameters. Many of the other EBI services use more complex input structures. For example NCBI BLAST (SOAP) requires a structure containing the various parameters and the input sequence to be passed to the run(email, title, params) method:

// 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);

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

// 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);
}

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 NCBI BLAST (SOAP) service, uses the NCBI BLAST suite to perform a sequence similarity search requires this approach. Examine the example client (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: solutions/soap/axis1/Q8NcbiBlastSoap.java

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

Sample solution: solutions/soap/axis1/Q9NcbiBlastSoap.java

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:

1. Java system properties:
   • Provided to the JVM:

     java -Dhttp.proxyHost=proxy.example.org -Dhttp.proxyPort=8080 ExampleClientClass

   • Set in client code:

     System.setProperty("http.proxyHost", "proxy.example.org");
     System.setProperty("http.proxyPort", "8080");

2. 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

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 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.

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:

String srvEndpoint = "http://wwwdev.ebi.ac.uk/ws/services/WSDbfetchDoclit";
WSDBFetchDoclitServerService service = new WSDBFetchDoclitServerServiceLocator();
WSDBFetchServer srvProxy = service.getWSDbfetchDoclit();

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 ⁹⁾ 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:

<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>

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:

/** 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;
  }
}

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:

WSDBFetchDoclitServerService service = new WSDBFetchDoclitServerServiceLocatorExtended();
WSDBFetchServer srvProxy = service.getWSDbfetchDoclit();

Most SOAP Web Services at 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.