41.4. Implementing a Protocol Handler

Overview

Protocol handlers are specific to the protocol in use. Apache CXF provides the SOAP protocol handler as specified by JAX-WS. A SOAP protocol handler implements the javax.xml.ws.handler.soap.SOAPHandler interface.
The SOAPHandler interface, shown in Example 41.8, “SOAPHandler Synopsis”, uses a SOAP specific message context that provides access to the message as a SOAPMessage object. It also allows you to access the SOAP headers.

Example 41.8. SOAPHandler Synopsis

public interface SOAPHandler extends Handler
{
  boolean handleMessage(SOAPMessageContext context);
  boolean handleFault(SOAPMessageContext context);
  void close(SOAPMessageContext context);
  Set<QName> getHeaders()
}
In addition to using a SOAP specific message context, SOAP protocol handlers require that you implement an additional method called getHeaders(). This additional method returns the QNames of the header blocks the handler can process.

Procedure

To implement a logical hander do the following:
  1. Implement any initialization logic required by the handler.
  2. Implement the message handling logic.
  3. Implement the fault handling logic.
  4. Implement the getHeaders() method.
  5. Implement the logic for closing the handler when it is finished.
  6. Implement any logic for cleaning up the handler's resources before it is destroyed.

Implementing the getHeaders() method

The getHeaders(), shown in Example 41.9, “The SOAPHander.getHeaders() Method”, method informs the Apache CXF runtime what SOAP headers the handler is responsible for processing. It returns the QNames of the outer element of each SOAP header the handler understands.

Example 41.9. The SOAPHander.getHeaders() Method

Set<QName> getHeaders();
For many cases simply returning null is sufficient. However, if the application uses the mustUnderstand attribute of any of the SOAP headers, then it is important to specify the headers understood by the application's SOAP handlers. The runtime checks the set of SOAP headers that all of the registered handlers understand against the list of headers with the mustUnderstand attribute set to true. If any of the flagged headers are not in the list of understood headers, the runtime rejects the message and throws a SOAP must understand exception.