41.5. Handling Messages in a SOAP Handler
Overview
handleMessage()
method.
handleMessage()
method receives a SOAPMessageContext
object that provides access to the message body as a SOAPMessage
object and the SOAP headers associated with the message. In addition, the context provides access to any properties stored in the message context.
handleMessage()
method returns either true
or false
depending on how message processing is to continue. It can also throw an exception.
Working with the message body
getMessage()
method. It returns the message as a live SOAPMessage
object. Any changes to the message in the handler are automatically reflected in the message stored in the context.
setMessage()
method. The setMessage()
method takes a SOAPMessage
object.
Getting the SOAP headers
SOAPMessage
object's getHeader()
method. This will return the SOAP header as a SOAPHeader
object that you will need to inspect to find the header elements you wish to process.
getHeaders()
method, shown in Example 41.10, “The SOAPMessageContext.getHeaders()
Method”, that will return an array containing JAXB objects for the specified SOAP headers.
Example 41.10. The SOAPMessageContext.getHeaders()
Method
Ojbect[] getHeaders(QName header,
JAXBContext context,
boolean allRoles);
allRoles
parameter to false
. That instructs the runtime to only return the SOAP headers that are applicable to the active SOAP roles.
JAXBContext
object see Chapter 37, Using A JAXBContext
Object.
Working with context properties
APPLICATION
scope and the Handler
scope.
Map
. To access the properties stored in the context, you use the get()
method and put()
method inherited from the Map
interface.
HANDLER
. If you want the application code to be able to access the property you need to use the context's setScope()
method to explicitly set the property's scope to APPLICATION.
Determining the direction of the message
MessageContext.MESSAGE_OUTBOUND_PROPERTY
key as shown in Example 41.11, “Getting the Message's Direction from the SOAP Message Context”.
Example 41.11. Getting the Message's Direction from the SOAP Message Context
Boolean outbound; outbound = (Boolean)smc.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);
Boolean
object. You can use the object's booleanValue()
method to determine the property's value. If the property is set to true
, the message is outbound. If the property is set to false
the message is inbound.
Determining the return value
handleMessage()
method completes its message processing has a direct impact on how message processing proceeds. It can complete by doing one of the following actions:
- return
true
—Returningtrue
signals to the Apache CXF runtime that message processing should continue normally. The next handler, if any, has itshandleMessage()
invoked. - return
false
—Returningfalse
signals to the Apache CXF runtime that normal message processing is to stop. How the runtime proceeds depends on the message exchange pattern in use for the current message.For request-response message exchanges the following happens:- The direction of message processing is reversed.For example, if a request is being processed by a service provider, the message will stop progressing toward the service's implementation object. It will instead be sent back towards the binding for return to the consumer that originated the request.
- Any message handlers that reside along the handler chain in the new processing direction have their
handleMessage()
method invoked in the order in which they reside in the chain. - When the message reaches the end of the handler chain it is dispatched.
For one-way message exchanges the following happens:- Message processing stops.
- All previously invoked message handlers have their
close()
method invoked. - The message is dispatched.
- throw a
ProtocolException
exception—Throwing aProtocolException
exception, or a subclass of this exception, signals the Apache CXF runtime that fault message processing is to start. How the runtime proceeds depends on the message exchange pattern in use for the current message.For request-response message exchanges the following happens:- If the handler has not already created a fault message, the runtime wraps the message in a fault message.
- The direction of message processing is reversed.For example, if a request is being processed by a service provider, the message will stop progressing toward the service's implementation object. It will be sent back towards the binding for return to the consumer that originated the request.
- Any message handlers that reside along the handler chain in the new processing direction have their
handleFault()
method invoked in the order in which they reside in the chain. - When the fault message reaches the end of the handler chain it is dispatched.
For one-way message exchanges the following happens:- If the handler has not already created a fault message, the runtime wraps the message in a fault message.
- Message processing stops.
- All previously invoked message handlers have their
close()
method invoked. - The fault message is dispatched.
- throw any other runtime exception—Throwing a runtime exception other than a
ProtocolException
exception signals the Apache CXF runtime that message processing is to stop. All previously invoked message handlers have theclose()
method invoked and the exception is dispatched. If the message is part of a request-response message exchange the exception is dispatched so that it is returned to the consumer that originated the request.
Example
handleMessage()
implementation that prints the SOAP message to the screen.
Example 41.12. Handling a Message in a SOAP Handler
public boolean handleMessage(SOAPMessageContext smc) { PrintStream out; Boolean outbound = (Boolean)smc.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY); 1 if (outbound.booleanValue()) 2 { out.println("\nOutbound message:"); } else { out.println("\nInbound message:"); } SOAPMessage message = smc.getMessage(); 3 message.writeTo(out); 4 out.println(); return true; }