Intercepting SOAP messages: easy development based on Apache Axis

Intercepting SOAP messages: easy development based on Apache Axis – Focus: message-centric Web services vs RPC

Aravilli Srinivasa Rao

This article takes a look at SOAP Message handlers and how JAX-RPC supports SOAP Message handlers and its usage scenarios.

First, some of the terminology: a SOAP Interceptor takes raw SOAP message as input and, before processing the message, modifies the SOAP message or adds some additional information to it, and then returns the SOAP message as output.

A SOAP Message handler is a mechanism that intercepts the SOAP messages at the client level as well as at the server level. SOAP Intermediary intercepts the SOAP message between the client and server.

SOAP Header processors deal mainly with the header part of the SOAP payload. A SOAP Header typically contains authentication information, a transaction ID, a digital signature, or some routing information.

SOAP Message Handlers

A SOAP Message handler intercepts the SOAP messages between the client and the server and gets access to the SOAP message that represents either SOAP request or SOAP response. Message handlers are tied to the Web service endpoints and are used to provide additional processing mechanisms when invoking a service using RPC. A SOAP Message handler processes the SOAP Header blocks as part of the processing of an RPC request or response.

SOAP Message Handler Usage Scenarios

SOAP Message handlers are used for many scenarios. Some typical handlers are:

* To do encryption and decryption on the client and service side for exchanging messages securely

* To provide Access-Control to Web services

* To provide auditing, logging, metric collection, caching, and transformation of Web services

* To provide content-based routing

* To provide transaction management

JAX-RPC Message Handler

JAX-RPC defines the following interfaces/ class in order to support the SOAP Message 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.


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.


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.


The HandlerInfo class represents the configuration data for a handler.


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.


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 client-request handler: A request handler is invoked before an RPC request is communicated to the target service endpoint.

* A client-response handler: A response handler is invoked before an RPC response is returned to the service client from the target service endpoint.

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

* A server-request handler: On the service endpoint side, a request handler is invoked before an RPC request is dispatched to the target service endpoint.

* A server-response handler: A response handler is invoked before an RPC response is communicated back to the service client from the target service endpoint.

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 JAXRPC 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:

* Purchase order generation

* Sign the purchase order document and send it to service endpoint

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


Cunningham road






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.

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.

Listing 7

<soapenv:Envelope soapenv:actor="some-uri"


// namespace declaration >




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 elements, which can be used to provide the configuration details for the handler:

<handler name=" signature"


<parameter name="filename"


Handler chain is a collection of one or more handlers:

<handler name=" Handler1"


handler name=”Handler2 ” type=”Typ2″>

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

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:

* Request Flow:Describes inbound messages

* Response Flow: Describes the outward flow of a message

* Fault flow: Describes the fault processing flow to be executed for SOAP Fault

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

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

<handler name=" signature"


<parameter name="filename"


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.

Listing 8

<deployment xmlns=""


<service name="http://localhost:8080/POService"


<!–specify the class name and its methods to the purchase

order service

<parameter name="allowedMethods" value=" processPOMethod



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.


* Apache Axis:

* JAX-RPC: rpc


Aravilli Srinivasa Rao, a software analyst at Hewlett-Packard, is technical lead for the development of HP’s public UDDI Registry. He is currently involved in a feasibility study of the projects in the mobile space to implement web services. Aravilli holds a master’s degree in computer application.


Madan Mohan, a senior software engineer at Hewlett-Packard, has several years of experience in J2EE, Web services, and testing. He is currently involved in the development and testing of J2EE and Web services applications. Madan holds a bachelor’s degree in engineering.


COPYRIGHT 2003 Sys-Con Publications, Inc.

COPYRIGHT 2003 Gale Group