email article printer friendly

Process SOAP Headers in JAX-RPC Handlers
Use general-purpose handlers to process SOAP headers in specific ways for specific applications by learning how to code and configure them
by Kevin Jones

Posted January 14, 2004

Java API for XML-based Remote Procedure Calls (JAX-RPC) can be used to map Web services operations onto Java method calls. I discussed this concept in a previous article ("Write and Configure JAX-RPC Handlers," January 7, 2004) that included how to write and configure JAX-RPC-based handlers, which have a number of uses. I also covered general-purpose handlers that can be used with any Web service. As well as being used for generic tasks, handlers can be used to process SOAP headers in a specific way for a specific application. Here, let's look at how to code and configure those handlers.

The SOAP specification defines a model for passing out-of-band or context information along with the SOAP request or response, and this information is passed in the form of a SOAP header. This context data can be used for many tasks such as security, session management, cache management, and so on in much the same way that HTTP headers are used. A SOAP header is added to the SOAP message as part of the SOAP header block (see Listing 1).

Notice that the header block can contain more than one header. Notice also that the headers in addition to containing their own data can also be annotated with attributes from the SOAP namespace (http://schemas.xmlsoap.org/soap/envelope/). There are two attributes that can be added to a header: mustUnderstand and actor (called role in the SOAP 1.2 specification). We'll discuss both of these attributes and how JAX-RPC manages headers with these attributes.

First, let's look at the session header. This header carries some session ID that will be processed in the server. Notice that the header does not contain a mustUnderstand or an actor attribute. Lack of an actor attribute is a signal to the Web service that this header is destined for the ultimate destination of this message.

The credentials header does have an actor attribute, which means that something somewhere is responsible for processing this header. The value of the attribute is a URI that defines what that something is, that is, some piece of code will receive this SOAP message, look at the headers, see and recognize the actor URI, and process this header.

The session header has a predefined actor URI of http://schemas.xmlsoap.org/soap/actor/next that indicates it is the responsibility of whatever the next thing to receive this message is to process the header (we'll discuss what things could process a message shortly).

Then we have the mustUnderstand attribute. This attribute signals that whatever actor is processing this message must understand and process the message and that if it doesn't, it must return a SOAP fault indicating a failure.

In the previous case only one header is marked as mustUnderstand: the credentials header. This is for the actor identified by urn:some:actor. That part of the Web service that acts as this actor must process this header and must understand it.

What Does the Processing?
In a JAX-RPC application it is typically the job of a handler to process SOAP headers. Handlers are part of a handler chain, and the handler chain can be associated with an actor. If the handler chain is configured without specifying the value of the actor, then the handler chain is implicitly acting in the role of the next actor. Otherwise, the chain acts in the role of the configured actors (see Listing 2).

This chain is defined to be explicitly in the http://kevinj.develop.com role and in the http://schemas.xmlsoap.org/soap/actor/next role, that is, you don't have to list the next role explicitly. Note that if you don't list any roles the next role is assumed. Also note that there is no way to state explicitly that a handler acts as the ultimate receiver of a message, which of course it doesn't. The ultimate receiver is the Java end point; however, you sometimes want a handler to handle headers with no actor, that is, to pretend to be the ultimate receiver. Although there is no way to state that in the configuration, it is perfectly okay for a handler to process headers for the ultimate recipient. And one other thing: the roles entry in the configuration file is not used unless mustUnderstand headers are involved, then it is vital.