43.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 43.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 43.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:
- Implement any initialization logic required by the handler.
- Implement the message handling logic.
- Implement the fault handling logic.
- Implement the
getHeaders()method. - Implement the logic for closing the handler when it is finished.
- Implement any logic for cleaning up the handler's resources before it is destroyed.
Implementing the getHeaders() method
The
getHeaders(), shown in Example 43.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 43.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.
