Previous Section Next Section

Building Handlers

Handlers are the key building blocks of Axis. As previously described, configuring Axis simply requires defining the types of handlers deployed and the order in which handlers are placed in the chains. A handler is nothing more than a piece of code that examines some (or all) of a SOAP message and then acts on it. Axis makes no assumptions about what each handler does; each one is free to do as little or as much work as needed. The specific details of how to write a handler are outside the scope of this book; however, we'll give a brief overview here. If you want to write a handler, you should consult the Axis documentation.

As each handler is invoked, it is passed a MessageContext object that contains all the information about the current state of the processing of the SOAP message. In particular, some of the key pieces of data in the MessageContext are as follows:

  • requestMessage— The SOAP message that is the incoming or requesting message. Typically this is the message that handlers before the pivot point use as input.

  • responseMessage— The SOAP message that is the outgoing or response message. Typically this is the message into which handlers after the pivot point will place their response message (if any).

  • targetService— The name of the service-specific chain that will be invoked by the Axis engine. If a handler's job is to determine which Web service is being called, it needs to set this field by calling the setTargetService() method, passing it the name of the service-specific chain.

  • bag— A Hashtable that can be used to store any metadata about the processing of the current message. Handlers can use this Hashtable to share information. For example, one handler can place in it information that another handler, later in the chain, can then retrieve and use in its own processing. This process requires some out-of-band knowledge between handlers so they know what key to use to store and retrieve the data.

The logic inside a handler is relatively straightforward. Each handler, whether it is on the request chain, on the response chain, or the pivot point handler, can access any of the data in the MessageContext. As a result, both the request and any possible response message that might exist are available and can be modified. Sometimes a handler can be placed on the request or the response side of a chain—in this case, requesting the request or response message explicitly could result in the wrong message being returned. For this reason, a getCurrentMessage() method on the MessageContext object will return either the request or response message, depending on whether the handler appears before or after the pivot point.

Once a message has been obtained, the handler is free to examine or process any part of the message. The handler can ask for the entire message, the body of the message, or any specific header. Because the SOAP specification has very specific rules for the processing of mustUnderstand headers, it is important than any handler that does process a header set the processed flag on that header by calling setProcessed(true) on that SOAPHeader object. Axis will use this information to determine whether to throw a mustUnderstand fault if all the mustUnderstand headers have not been processed.

    Previous Section Next Section