Document/Literal Web Services on Apache Axis

Back to Web Services Resources and Tutorials

Setting Up Your Environment
Starting with a WSDL File
Generating a Simple Service
Packaging and Deploying the Service

You will need a servlet container (recommended, and used in this tutorial: Tomcat) and the Apache Axis distribution. Links are below. The versions may differ by the time you see this; results are not expected to vary, but the version numbers are provided here as a record of what versions were used during the production of this tutorial:

Once you've installed Tomcat and downloaded Axis, you'll need to install the Axis webapp on Tomcat. See Axis installation instructions, but in short, it involves dropping the webapp in the Tomcat webapps directory, bringing up the Axis webapp, and performing some housekeeping tasks to ensure that Axis will run correctly. This last task mostly involves obtaining various .jar files Axis needs; a diagnostic page called the "Axis Happiness Page" provides the necessary diagnostics.

Starting with a WSDL File

As was mentioned in the introduction to this tutorial, we will emphasize interoperability and the use of the WSDL file as the starting point. Create a directory to hold this project and create a subdirectory called wsdl. This tutorial uses a different WSDL file than the other service-side examples. This WSDL file specifies a simple contract to return a document containing the current date and time as separate character strings. Within the wsdl directory, create a file called datetime-1.0.wsdl. An example of this file can be found at datetime-1.0.wsdl.

The portType defines a single operation, "GetDateTime", the style is "document" and the use attribute is "literal". The WS-I Basic Profile 1.1 restricts style/use values to RPC/Literal and Document/Literal, while .NET tools (as of this writing) do not support RPC/Literal, so Document/Literal appears to be the best choice for interoperability.

Generating a Simple Service

The first step is to use Axis' WSDL2Java utility (a Java class) to generate the server-side tie (skeleton) from the WSDL file. This utility takes a number of options, but the ones important here are:

-o srcdir: this specifies the directory in which to place the generated source files. Axis generates package structures based on the namespaces you use in the WSDL file. In the example WSDL supplied here, the data types have a different namespace than the WSDL contract, so the model classes go in a different package than the service package.
-s wsldFileName: the name of the WSDL file.

You will need a number of .jar files on the runtime classpath, including a parser implementation which you can get from Ant (easy, if you're using Ant to build). An example build file is available at build.xml, but the .jar files need to generate the schema and tie classes follows:

axis.jar
commons-logging-1.0.4.jar
commons-discovery-0.2.jar
jaxrpc.jar
saaj.jar
wsdl4j-1.5.1.jar
xercesImpl.jar

Create a src directory at the top level of your tutorial, then create under it two directories named src and webapp. When you run the WSDL2Java utility, you will get the following:

Server-side classes (if you use the supplied WSDL file, these will be in the com/example/datetime_1_0/wsdl directory)
Schema classes (again, if you use the WSDL file from this tutorial, these will be in the com/example/datetime_1_0/schema directory)
Axis' deployment files, deploy.wsdd and undeploy.wsdd, in the same directory as the server-side classes

The deploy.wsdd file will be used to deploy the web service to the Axis webapp, as described below.

The WSDL2Java utility created a server implementation class named DateTimeSoapHttpBindingImpl.java. Edit this class to return the DateTime document specified in the WSDL file with code similar to the following:

package com.example.datetime_1_0.wsdl;

import java.util.Calendar;
import java.util.Date;
import java.text.DateFormat;

public class DateTimeSoapHttpBindingImpl implements com.example.datetime_1_0.wsdl.DateTimePortType
{
  public com.example.datetime_1_0.schema.DateTimeType getDateTime(com.example.datetime_1_0.schema.DateTimeRequestType body) 
    throws java.rmi.RemoteException
  {
    Calendar cal = Calendar.getInstance();
    Date date = cal.getTime();
    DateFormat dateInstance = DateFormat.getDateInstance(DateFormat.LONG);
    DateFormat timeInstance = DateFormat.getTimeInstance(DateFormat.LONG);
    return new com.example.datetime_1_0.schema.DateTimeType(dateInstance.format(date), timeInstance.format(date));
  }
}

At the top level of your tutorial directory, create a directory called

webapp/WEB-INF/classes

and then compile the entire source branch into this directory. Again, see the included Ant build file for an example of this operation.

Packaging and Deploying the Service

Axis uses a somewhat different deployment style that the .war-file approach we have used in the other tutorial examples. Since Axis is itself a webapp, you deploy your web service by adding its compiled .class files to the Axis WEB-INF/classes directory, or by dropping a .jar file of your classes into the Axis WEB-INF/lib directory. To maintain as clean a packaging system as possible, we'll use the latter approach here.

Create a .jar file of the Java class structure you created in the previous section; name the file datetime.jar. Copy this file to the Axis WEB-INF/lib directory. Next, run the Axis AdminClient to deploy the web service. The client is a Java class, specifically

org.apache.axis.client.AdminClient

You will also need to specify the URL of the AdminService and the full path to the deploy.wsdd file. An example, including the classpath you'll need to execute the client, can be found in the deploy-web-service target of the example Ant build file.

Once the AdminClient has finished, the web service should be available. You should see the web service appear on the Axis webapp's list of deployed webservices. For the example given here, the URL is at

http://127.0.0.1:8080/axis/services/DateTimePort?wsdl

since the deploy.wsdd file specified a service name of DateTimePort. This check only verifies that the web service has deployed, but not necessarily that it has deployed correctly. You can actually invoke the web service by passing the expected request document for the GetDateTime operation to a browser, using the following URL:

http://localhost:8080/axis/services/DateTimePort?method=GetDateTime><request/>

(the request document does not need to be populated because its content is ignored by the web service). You should in return see a document like the following:

<?xml version="1.0" encoding="UTF-8"?>
  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
                       xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Body>
      <DateTime xmlns="http://example.com/datetime-1.0/schema">
        <date xmlns="">July 10, 2006</date>
        <time xmlns="">1:30:52 PM MDT</time>
      </DateTime>
    </soapenv:Body>
  </soapenv:Envelope>

To test further, look at the client tutorials under Web Services Resources and Tutorials.