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 :
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 chainin 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. |