Handling Fault Messages

Overview

Handlers use the handleFault() method for processing fault messages when a ProtocolException exception is thrown during message processing.

The handleFault() method receives either a LogicalMessageContext object or SOAPMessageContext object depending on the type of handler. The received context gives the handler's implementation access to the message payload.

The handleFault() method returns either true or false, depending on how fault message processing is to proceed. It can also throw an exception.

Getting the message payload

The context object received by the handleFault() method is similar to the one received by the handleMessage() method. You use the context's getMessage() method to access the message payload in the same way. The only difference is the payload contained in the context.

For more information on working with a LogicalMessageContext see Handling Messages in a Logical Handler.

For more information on working with a SOAPMessageContext see Handling Messages in a SOAP Handler.

Determining the return value

How the handleFault() method completes its message processing has a direct impact on how message processing proceeds. It completes by performing one of the following actions:

Return true: Returning true signals that fault processing should continue normally. The handleFault() method of the next handler in the chain will be invoked.
Return false: Returning false signals that fault processing stops. The close() method of the handlers that were invoked in processing the current message are invoked and the fault message is dispatched.
Throw an exception: Throwing an exception stops fault message processing. The close() method of the handlers that were invoked in processing the current message are invoked and the exception is dispatched.

Example

Example 21.13 shows an implementation of handleFault() that prints the message body to the screen.

Example 21.13. Handling a Fault in a Message Handler

public final boolean handleFault(LogicalMessageContext messageContext)
{
  System.out.println("handleFault() called with message:");

  LogicalMessage msg=messageContext.getMessage();
  System.out.println(msg.getPayload());

  return true;
}