JAX-RPC Message Handler
JAX-RPC defines the following interfaces/class in order to support the SOAP Message handler.

Handler
A handler interface provides methods for handleRequest, handleResponse, and handleFault. handleRequest and handleResponse perform the actual processing work for a handler. The method handleRequest processes the request SOAP message, while the method handleResponse processes the response SOAP message. The method handleFault performs SOAP fault processing.

SOAP Message Handler
A SOAP Message handler class is required to implement the javax.xml.rpc.handler.Handler interface.

GenericHandler
The javax.xml.rpc.handler.GenericHan dler class is an abstract class that implements the handler interface. Handler developers should typically subclass the GenericHandler class unless the handler implementation class needs another class as its superclass.

In the case of Apache Axis, handler developers should subclass the BasicHandler, which is a subclass of Handler.

HandlerChain
This class represents an ordered list of handlers. An implementation class for the HandlerChain interface abstracts the policy and mechanism for the invocation of the registered handlers. The default invocation policy is to invoke handlers in the order of registration with the HandlerChain instance. Additional policies may be applied to process the SOAP Headers.

HandlerInfo
The HandlerInfo class represents the configuration data for a handler.

MessageContext
The interface MessageContext abstracts the message context that is processed by a handler in the handleRequest, handleResponse, or handleFault. It has a method to set the properties, which are shared across the handlers in the handler chain.

SOAPMessageContext
The interface SOAPMessageContext provides access to the SOAP message for either RPC request or response. It has methods to set and get the SOAP message.

Handler Configuration
A JAX-RPC handler may be configured and used on the service client as follows:

A JAX-RPC handler may configured and used on a service endpoint as follows:

Let's take a look at how to develop a SOAP Message handler and how to configure the handler at the service endpoint as a request handler using the Apache Axis JAX-RPC implementation.

Using SOAP Message Handlers in Web Services
First, let's assume you're working on an application where you need to send secure SOAP messages to the Web service. In our example, we're developing a purchase order processing system where customers submit purchase order requests and the system processes the purchase orders. Each customer is assigned a private/public key pair that is installed in the client machine in a keystore, which is a database for keys and certificates. The customer signs each purchase order document using the private key and passes the public key and certificate details along with the document. Customers submit the signed purchase order document using a Web service to the supplier.

On the supplier site, each XML Signature is verified and if the identity of the submitter is accepted the purchase order is accepted for further processing. A SOAP Message handler is used in order to verify the XML Signature on the supplier side.

Let's consider how to develop the client application to digitally sign and send the purchase order document and how to develop the server-side application to verify the signature and process the document. We'll use Apache Axis.

Develop Client Application
Develop a Client application with the following:

Generate the purchase order (see Listing 1; the Java code for this article, contained in Listings 1-5, can be found online at www.sys-con.com/webservices/sourcec.cfm) as shown below. Assume that the Shipping and Billing addresses are the same.

<purchaseOrder orderDate="2003-01-20">
<shipTo country="IN">
<name>ARAVILLI   </name>
<street>Cunningham road   </street>
<city>Bangalore </city>
<zip>560052 </zip>
</shipTo>
<Items>
<item partNum="872-AA">
<productName>Inkjet-Printer   </productName>
<quantity>5   </quantity>
<USPrice>148.95   </USPrice>
</item>
</Items>
</purchaseOrder>

Sign the purchase order document (see Listing 2) using the private key and pass the certificate information. It signs only the purchase order element tag instead of signing the entire SOAP Body. The signature element looks like Listing 6.

Now create a SOAP message with the purchase order element in the body of the SOAP message and signature in the SOAP Header block. Add the service name and method as part of the SOAP Body in the message (see Listing 3 for Java code and Listing 5 for the entire SOAP message). The generated SOAP message looks like Listing 7.

To generate this SOAP message, we used a message-style Web service instead of RPC.

Develop the Server Application
Develop the server application:

public class Service
{
public String processPOMethod ()
{
// Actual processing done here
}
}

Develop the Message Handler
Develop a class that extends from BasicHandler of Apache Axis and override the invoke method. Apache Axis defined BasicHandler as an abstract class that extends from Handler, so the handler developer should subclass his pr her handler from BasicHandler class. The Invoke method receives MessageContext, which contains the incoming SOAPMessage. From the SOAP message extract the Signature element using XPath APIs and verify it against the SOAP Body. If the verification succeeds, the handler passes the message (removes the signature) on to the Web service (purchase OrderService) server itself. If the verification fails then the handler raises an exception, which causes a SOAP fault to be returned (see Listing 4 for Java code).

Deploy the Service and Configure the Handler
Configure the Handler
Configure the handler using the Handler element in the Apache Axis Web service deployment descriptor. This element has two attributes: the name for the handler and the type of handler. Handler type refers to the Java class that implements the handler. The Handler element contains several child <parameter> elements, which can be used to provide the configuration details for the handler:

<handler name=" signature" type="DecryptionHandler">
<parameter name="filename" value="MyService.log"/>
</handler>

Handler chain is a collection of one or more handlers:

<chain name = "my_own_chain" >
<handler name=" Handler1" type="Type1">
<parameter name="param1" value="Value1"/>
</handler>
handler name="Handler2 " type="Typ2">
<parameter name="param2" value="value2"/>
</handler>
</chain>

In order to reuse the handlers, define them separately and reference them in the chains.

<handler name=" Handler1" type="Type1">
<parameter name="param1" value="Value1"/>
</handler>
<handler name="Handler2 " type="Typ2">
<parameter name="param2" value="value2"/>
</handler>
<chain name = "my_own_chain" >
<handler type =" Handler1" >
<handler type =" Handler2" >
</chain>

Axis supports the Flow element to bind a particular handler or chain of handlers to a request or response. A Flow defines the sequential invocation of handlers and handler chains. The supported flows in Axis are:

Our example, related to Request Handler, uses the Request Flow element to bind the handler.

<requestFlow>
<handler type="signature"/>
</requestFlow>

We have defined handler element separately and referenced it in the requestFlow. It may also be defined in the request Flow element itself:

<requestFlow>
<handler name=" signature" type="DecryptionHandler">
<parameter name="filename" value="MyService.log"/>
</handler>
</requestFlow>

Configure and Deploy the Service
Configure and deploy the service using the Axis WSDD file as shown in Listing 8. Once deployed, the service invokes/tests the service and handler using the client application.

Conclusion
As you can see, it's not difficult to develop the SOAP Message handlers using Apache Axis; the handlers can be used in various ways. Axis used handlers extensively in the design of the Axis Engine. Refer to the Axis Architecture document for more information about the handlers usage.

References