Creating Web Service Applications with JAX-WS - Java SOA - page 339

Intercepting the Request to Perform

Protocol-Specific Work

Problem

You want to decorate your service request by intercepting it immediately prior to invocation
so that you can modify certain protocol-specific parts of your request, such as SOAP headers.
You don't want to bake this code into your message construction, or you aren't using SAAJ.

Solution

Implement the javax.xml.ws.handler.soap.SOAPHandler<T extends SOAPMessageCon-
text> interface to use a ProtocolHandler . Write a class that implements the HandlerRe-
solver interface and puts your handler in a list. Add an instance of your resolver to your ser-
vice proxy before you get its port. The handler will be invoked at each request sent and each
response received by the runtime.

Discussion

There are two types of message handlers defined in JAX-WS: SOAPHandler s and Logic-
alHandler s. If you want to operate on the payload of your message itself or its message con-
text properties, use a logical handler (discussed in Intercepting the Request to Perform Work
on Your Payload ). If you want to operate on some part of the message that is specific to the
binding protocol in use, such as SOAP, then you can use a protocol handler. One such handler,
defined out of the box by JAX-WS, is the SOAPHandler , which allows you to operate on the
SOAP envelope, such as its headers, attachment, or fault. This recipe examines that class.
Handlers are similar to EJB 3 interceptors or servlet filters. On the client side, handlers are
used to modify or simply access SOAP messages immediately before they are sent across the
wire to the service.

NOTE

Message handlers can also be used on the server side, but that's covered in the next chapter.

With JAX-RPC, considerable configuration in webservices.xmlwas required to provide sup-
port for your handler within the runtime. Java EE 5 removes much of this burden by employ-
ing annotations.