Java Web Services: Up and Running, 2nd Edition

A SOAP-Based Web Service

JAX-WS, like JAX-RS, uses annotations, and machine-generated JAX-WS code is awash with these. The first example is stingy in its use of annotations in order to underscore exactly what is required for a SOAP-based service. Later examples introduce additional annotations.:

The RandService class (see Example 4-1) defines a SOAP-based service with two operations, each an annotated Java method:

• Operation next1 takes no arguments and returns one randomly generated integer.
• Operation nextN takes one argument, the number of randomly generated integers desired, and returns a list (in this implementation, an array) of integers.

Example 4-1. A SOAP-based service with two operations

package rand;

import javax.jws.WebService;
import javax.jws.WebMethod;
import java.util.Random;

@WebService                                                       
public class RandService {
    private static final int maxRands = 16;

    @WebMethod // optional but helpful annotation                 
    public int next1() { return new Random().nextInt(); }
    @WebMethod // optional but helpful annotation                 
    public int[ ] nextN(final int n) {
        final int k = (n > maxRands) ? maxRands : Math.abs(n);
        int[ ] rands = new int[k];
        Random r = new Random();
        for (int i = 0; i < k; i++) rands[i] = r.nextInt();
        return rands;
    }
}

The @WebService annotation (line 1) marks the RandService POJO class as a web service, and the @WebMethod annotation (lines 2 and 3) specifies which of the encapsulated methods is a service operation. In this example, the RandService class has only two methods and each of these is annotated as @WebMethod. The @WebMethod annotation is optional but recommended. In a class annotated as a @WebService, a public instance method is thereby a service operation even if the method is not annotated. This SOAP service code is compiled in the usual way, assuming JDK 1.6 or greater.

Recall that core Java 6 or greater includes the Endpoint class for publishing web services, SOAP-based (@WebService) and REST-style (@WebServiceProvider) alike. The class RandPublisher (see Example 4-2) is the Endpoint publisher for the RandService.

Example 4-2. An Endpoint published for the RandService SOAP-based web service

package rand;

import javax.xml.ws.Endpoint;
public class RandPublisher {
    public static void main(String[ ] args) {
        final String url = "http://localhost:8888/rs";                    
        System.out.println("Publishing RandService at endpoint " + url);
        Endpoint.publish(url, new RandService());                         
    }
}

The publish method used here (line 2) takes two arguments: a URL that specifies the service endpoint (line 1) and an instance of the service implementation class, in this case the RandService class (line 2). In the URL, the port number 8888 and the URI /rs are arbitrary, although a port number greater than 1023 is recommended because modern operating systems typically reserve port numbers below 1024 for particular applications (e.g., port 80 is typically reserved for HTTP requests to a web server). The RandPublisher as coded here runs indefinitely, but there are various way to control an Endpoint publisher’s life span.

The web service publisher can be executed in the usual way:

% java rand.RandPublisher

The output should be similar to this:

Publishing RandService at endpoint http://localhost:8888/rs

com.sun.xml.internal.ws.model.RuntimeModeler getRequestWrapperClass
INFO: Dynamically creating request wrapper Class rand.jaxws.Next1
com.sun.xml.internal.ws.model.RuntimeModeler getResponseWrapperClass
Dynamically creating response wrapper bean Class rand.jaxws.Next1Response
com.sun.xml.internal.ws.model.RuntimeModeler getRequestWrapperClass
INFO: Dynamically creating request wrapper Class rand.jaxws.NextN
com.sun.xml.internal.ws.model.RuntimeModeler getResponseWrapperClass
INFO: Dynamically creating response wrapper bean Class rand.jaxws.NextNResponse

The first line of output is from the RandPublisher but the others are from the Java run-time. The dynamically created wrapper classes such as Next1 and Next1Response are JAX-B artifacts that represent the incoming SOAP request (Next1) and the outgoing SOAP response (Next1Response).

Once the service is published, a utility such as curl can be used to confirm that the service is indeed up and running:

% curl http://localhost:8888/rs?xsd=1

This curl request contains the query string entry xsd=1 that asks for the XML Schema associated with this service; the schema, like the JAX-B artifacts, is generated dynamically (see Example 4-3).

Example 4-3. The XML Schema generated dynamically for the RandService

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:tns="http://rand/" xmlns:xs="http://www.w3.org/2001/XMLSchema"
           version="1.0" targetNamespace="http://rand/">
  <xs:element name="next1" type="tns:next1"></xs:element>
  <xs:element name="next1Response" type="tns:next1Response"></xs:element>
  <xs:element name="nextN" type="tns:nextN"></xs:element>
  <xs:element name="nextNResponse" type="tns:nextNResponse"></xs:element>
  <xs:complexType name="next1"><xs:sequence></xs:sequence></xs:complexType>
  <xs:complexType name="next1Response">
    <xs:sequence>
      <xs:element name="return" type="xs:int"></xs:element>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="nextN">
    <xs:sequence>
      <xs:element name="arg0" type="xs:int"></xs:element>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="nextNResponse">
    <xs:sequence>
      <xs:element name="return" type="xs:int" minOccurs="0" maxOccurs="unbounded">
      </xs:element>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

The schema will be studied carefully later. For now, the point of interest is that the schema provides a data type for each SOAP message that travels, in either direction, between the service and the client. Each message is of an XML Schema complexType as opposed to an simple type such as xsd:date, xsd:string, or xsd:integer.

In the RandService there are two SOAP messages (for instance, the messages Next1 and Next1Response) per web service operation (in this case, the next1 operation) because each operation implements the familiar request/response pattern: a client issues a request, delivered to the service as a Next1 SOAP message, and gets a response, in this case a Next1Response message, in return. Accordingly, the schema contains four typed SOAP messages because the RandService has two operations in the request/response pattern, which means two messages per operation. The number of complexType occurrences in the XML Schema may exceed the total number of messages needed to implement the service’s operations because special error messages, SOAP faults, also may be defined in the XML Schema. SOAP faults are covered in the next chapter.

The XML Schema types such as Next1 and Next1Response are the XML counterparts to the JAX-B artifacts, noted earlier, with the same names. The schema types and the JAX-B types together allow the SOAP libraries to transform Java objects into XML documents (in particular, SOAP Envelope instances) and SOAP Envelope instances into Java objects. The Endpoint publisher’s underlying SOAP libraries handle the generation of the JAX-B artifacts and the generation of the XML Schema.

Publishing a SOAP-Based Service with a Standalone Web Server

Publishing a @WebService with Tomcat or Jetty is almost the same as publishing a @WebServiceProvider (see A RESTful Service as a @WebServiceProvider) with these web servers. Here, for quick review, are the details.

Two configuration files are needed: the usual file web.xml and the additional file sun-jaxws.xml. Here is the web.xml, which would work for any implementation annotated as @WebService or @WebServiceProvider:

<?xml version="1.0" encoding="UTF-8"?>
<web-app>
  <listener>
    <listener-class>
      com.sun.xml.ws.transport.http.servlet.WSServletContextListener
    </listener-class>
  </listener>
  <servlet>
    <servlet-name>jaxws</servlet-name>
    <servlet-class>
      com.sun.xml.ws.transport.http.servlet.WSServlet
    </servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>jaxws</servlet-name>
    <url-pattern>/*</url-pattern>
  </servlet-mapping>
</web-app>

The Metro classes WSServletContextListener and WSServlet are in the JAR file currently named webservices-rt.jar, which can be downloaded with the rest of Metro JARs. A second Metro library file webservices-api.jar is also required. The JAR files in question should be in the src directory so that the Ant script can package them in the deployed WAR file. In any case, the WSServletContextListener parses the sun-jaxws.xml file. The WSServlet acts as the interceptor: the servlet receives incoming requests and dispatches these to the RandService.

The second configuration file, sun-jaxws.xml, is:

<?xml version="1.0" encoding="UTF-8"?>
<endpoints version="2.0"
           xmlns="http://java.sun.com/xml/ns/jax-ws/ri/runtime">
  <endpoint implementation="rand.RandService" 
            name="RandService"
            url-pattern="/*"/>
</endpoints>

This file completes the routing by notifying the WSServletContextListener that the WSServlet should dispatch requests to a RandService instance (line 1).

With the two configuration files and the Metro library JARs in the src directory, the RandService can be deployed to Tomcat in the usual way:

% ant -Dwar.name=rand deploy

Once the @WebService has been deployed, a curl call or a browser can be used to verify that the service is up and running:

% curl http://localhost:8080/myWarFileName?xsd=1

If successful, this command returns the XML Schema associated with the service.

Even this first and rather simple example underscores a major appeal of SOAP-based services: underlying SOAP libraries handle the conversions between native language types (in this case, Java types) and XML Schema types. Figure 4-1 depicts the architecture.

Figure 4-1. The architecture of a typical SOAP-based service