What’s Next?

JAX-WS has two distinct but related APIs for SOAP-based web services. One API, with annotations such as @WebService and @WebMethod, focuses on what might be called the application level. On the service side, annotations are used to create web services and to specify their operations. Additional annotations such as @WebParam are available for fine-tuning and documenting different aspects of a service and its operations. On the client side, the application API enables clients to draw upon wsimport-generated classes to access a SOAP-based service and to invoke its operations. A central feature of the application level is the WSDL contract, which captures in XML the service and its operations, including essential details such as the invocation syntax for the service operations, the encoding/decoding scheme for data types, the transport used for messages, and the service endpoint. Frameworks such as JAX-WS and DotNet come with utilities that put the WSDL to practical use.

A major appeal of the application level in JAX-WS is that the SOAP itself—the XML—remains hidden on the service and the client sides. The underlying SOAP libraries serialize from Java into XML and deserialize from XML into Java, thereby allowing both service and service client to work in Java data structures and in familiar Java programming idioms. JAX-B and related utilities allow REST-style services in Java to work around the XML or JSON payloads typical of REST-style services, but JAX-WS, which uses JAX-B under the hood, takes the further step of automating the serialization/deserialization. JAX-WS is programmer-friendly on both the service and client side.

The examples in this chapter have remained, for the most part, at the JAX-WS application level but have touched on another level, the handler level. A second JAX-WS API, with the Handler interface and its two subinterfaces LogicalHandler and SOAPHandler, provides access to the underlying SOAP. A SOAPHandler gives the programmer access to the entire SOAP message, whereas the convenient LogicalHandler gives the programmer access to the payload of the SOAP body. A SOAPHandler often is called a message handler and a LogicalHandler is called simply a logical handler.

The handler API allows the programmer to inspect and, if needed, to manipulate the SOAP that the underlying libraries generate. The distinction between the JAX-WS application and handler APIs in web services corresponds roughly to the distinction between the servlet and filter API in Java-based websites. (One important difference is that JAX-WS handlers are available on both the client and the service side.) This chapter introduced but did not explore the handler API in the clients against Amazon’s E-Commerce service. In the REST-style clients of Chapter 3 against the E-Commerce service, the clients made GET requests, and critical pieces of information (e.g., the user’s accessId and an HMAC hash generated from the user’s secretKey) had to be sent in the query string. The very same pieces of information are required in a SOAP-based client, but such a client, even when invoking a read operation on the E-Commerce service, sends a POST request whose body is a SOAP envelope. The JAX-WS libraries generate the SOAP envelope, but a client-side handler, an instance of the mentioned but not listed AwsServiceHandler class, inserts the user’s accessId, the HMAC hash, and a strictly formatted timestamp into the SOAP envelope, in particular into the SOAP body. The next chapter takes a close look at the AwsServiceHandler class.

The next chapter goes down to the JAX-WS handler level by explaining, first, how the class AwsServiceHandler works in the E-Commerce service clients. This chapter then does a full example with a client-side and a service-side handler, an example that deliberately mimics the way that Amazon’s more complicated E-Commerce service works. JAX-WS also exposes to the programmer the transport level, which is almost always HTTP(S). On either the client side or the service side, JAW-WS code can inspect and, if appropriate, modify the HTTP messages that carry SOAP messages as their payloads. JAX-WS thus covers three distinct levels of SOAP-based web services: the application level, the handler level, and the transport level. Chapter 5 also looks at some miscellaneous but related topics: SOAP faults in the application and handler levels, binary payloads in SOAP services, and the Axis2 implementation of JAX-WS, which is an alternative to the Metro implementation.