Axis2

Axis2, which implements but also extends JAX-WS, is an alternative to the Metro implementation. The current version is 1.6.x. Axis2 can be downloaded in various formats, including as a self-contained WAR file, axis2.war, which can be copied to TOMCAT_HOME/webapps. An Axis2 service does not require annotations if the proper configuration file is used. This section introduces Axis2 using a deliberately simple service so that the focus is on the deployment steps.

The HiService class (see Example 5-15) is a POJO class, free of annotations, that implements the SOAP-based HiService in Axis2. Any public instance method in the class is thereby a service operation; in this case, there is a single operation: echo.

Example 5-15. The HiService in Axis2

package hello;

public class HiService {            // service
  public String echo(String name) { // service operation
    String msg =
      (name == null || name.length() < 1) ? "Hello, world!" : "Hello, " + name + "!";
    return msg;
  }
}

The configuration file services.xml (see Example 5-16) specifies that an instance of the Axis2 class RPCMessageReceiver will act as the interceptor for requests against the operation named echo. The configuration document services.xml must be deployed in the JAR file’s META-INF directory.

Example 5-16. The services.xml configuration file for the Axis2 HiService

<service>
  <parameter name = "ServiceClass" locked = "false">hello.HiService</parameter>
  <operation name = "echo">
    <messageReceiver class = "org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
  </operation>
</service>

Here are the steps for deploying this Axis2 service:

1. The downloaded Axis2 implementation file, axis2.war, should be copied to webapps directory under TOMCAT_HOME. Tomcat unwars this WAR file, creating the directory webapps/axis2, which in turn has a subdirectory named WEB-INF/services. An Axis2 service is deployed as a JAR file copied to the services subdirectory.

2. The compiled service class, in this case hello.HiService, together with the configuration file META-INF/services.xml, should be put in a JAR file with an .aar extension, for example, hi.aar. Here is a snapshot of the contents of hi.aar:

   hello/HiService.java
   hello/HiService.class
   META-INF/services.xml

   The source code, HiService.java, is included in the JAR file for convenience.

3. The deployable JAR file, hi.aar, is then copied to webapps/axis2/WEB-INF/services.

Once the Axis2 service is deployed, wsimport can be used to generate client-side artifacts. The command is the usual one:

% wsimport -p clientAxis2 -keep http://localhost:8080/axis2/services/hi?wsdl

The wsimport utility outputs a warning that the portType in the WSDL is not standard and that, accordingly, there may be problems with the generated JAX-WS artifacts. This issue is addressed next.

The AxisClient class (see Example 5-17) is code for a sample client against the Axis2 HiService. The client is built on the familiar wsimport-generated classes in the package/directory clientAxis2. These wsimport-generated classes are close but not identical to the classes that would be generated from a Metro service. In any case, the Axis2 versions do not set the service endpoint according to JAX-WS standards, which explains lines 2 and 3 in the code: these two lines change the endpoint address to the correct one, in this case to the endpoint given in line 1. Lines 2 and 3 represent transport-level code. With this small change using the JAX-WS transport-level API, the service operation can be invoked in the usual way (lines 4 and 5).

Example 5-17. The AxisClient against the HiService

import clientAxis2.HiPortType;
import clientAxis2.Hi;
import javax.xml.ws.BindingProvider;

public class AxisClient {
    public static void main(String[ ] args) {
        final String endpoint = "http://localhost:8080/axis2/services/hi";     

        HiPortType port = new Hi().getHiHttpEndpoint();
        // Override the endpoint in the wsimport-derived classes.
        BindingProvider bp = (BindingProvider) port;                           
        bp.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,  
                                   endpoint);
        System.out.println(port.echo(null));                                   
        System.out.println(port.echo("Fred"));                                 
    }
}

The output is

Hello, world!
Hello, Fred!

Axis2 is a popular alternative to the Metro implementation of JAX-WS. Axis2 and Metro are close enough that the transition from one to the other should be mostly trouble-free.