email article printer friendly get the code

Handle Your JAX
Though frequently misunderstood, the handlers classes of JAX-RPC can be plugged dynamically into Web services
by Sameer Tyagi

Posted August 25, 2003

JAX-RPC was released in June 2002 as JSR 101 and was well received by the community. It is now a part of the proposed Java 2 Platform, Enterprise Edition (J2EE) 1.4. The current Java Web Services Developer Pack (Java WSDP 1.2) distribution contains JAX-RPC version 1.1 EA of the reference implementation. Recall that JAX-RPC is a Java API for exposing procedure calls, using XML, to business applications that occur primarily, though not exclusively, on the periphery of organizations.

Here we will look at a very useful and often misunderstood feature of JAX-RPC called handlers. JAX-RPC has a pluggable architecture, in that it allows special classes called handlers—or SOAP handlers, as they are sometimes called—to be plugged dynamically into the Web service. This ability allows additional functionality and system-level services to be layered on top of the Web service.

Note that JAX-RPC is being further enhanced as JSR 224. This JSR will develop the next version of the API (JAX-RPC 2.0), which will add new features like direct support for JAXB 2.0-based data binding, SOAP 1.2, WSDL 1.2, and support for asynchronous RPC and other transport protocols.

A SOAP message handler is a Java class that provides a filtering mechanism for pre-processing and post-processing of the SOAP message by intercepting the SOAP message and acting on the SOAP request and SOAP response. A handler can be used on the client side, the server side, or both. Handlers can be used to add features to a service call and are a good means to layer additional functionality over the core message on the client side, the server side, or both together. They are useful because they provide the ability to introduce security services, business processing, error handling, and managing the selection of content creation strategies in both service consumers and service implementations—without changing the client/server code.

Take a look at how handlers plug into the JAX-RPC architecture (see Figure 1). On the client side any of the handlers can be configured to be invoked in a specific order once the SOAP request has been constructed by marshalling the Java to XML. The same handlers also intercept the request before the response returned by the service is unmarshaled into Java.

On the server side the handlers act in much the same way. They intercept the SOAP request before it is unmarshaled to Java and before the service is invoked. The same handlers also intercept the outgoing SOAP response once the SOAP message has been constructed.

Servlet-Like Life Cycles
Developers write the pluggable handlers by implementing a special interface in the JAX-RPC API, which allows the JAX-RPC runtime to invoke the special methods contained in the interface. In short, all handler implementations must implement the javax.xml.rpc.handler.Handler interface you see here:

public interface Handler{
  public abstract void init(
    HandlerInfo handlerinfo);
  public abstract boolean 
    handleRequest(MessageContext 
    messagecontext);
  public abstract boolean 
    handleResponse(MessageContext 
    messagecontext);
  public abstract boolean 
    handleFault(MessageContext 
    messagecontext);
  public abstract void destroy();
  public abstract QName[] 
    getHeaders();
}