Glen Mazza's Weblog

Also see this blog entry for information on CXF interceptors and alternative simpler methods of modifying SOAP requests and responses.

This tutorial shows various usages of JAX-WS handlers and how they can be attached to CXF-based SOAP web services and clients. We'll be attaching the handlers to the DoubleIt web service and client. The finished tutorial source code can be cloned or downloaded from GitHub.

The design and behavior of JAX-WS handlers are primarily defined in Chapter 9 of the JAX-WS Specification, with additional relevant material in Sections 4.2.1, 5.3, and 10. Some main features of handlers:

• Handlers fall into two categories:
  • SOAP Handlers (or, more precisely, protocol handlers, as JAX-WS supports other non-SOAP protocols such as XML over HTTP), which provide the ability to modify the entire SOAP envelope using the DOM-like SAAJ.
  • LogicalHandlers with provide access to the SOAP body's content (the payload) only. For logical handlers, JAXB or one of the Source options is used to modify the message instead of the protocol-specific SAAJ.
• Handlers are linked in predefined chains except will be reordered such that logical handlers always come before SOAP handlers.
• Handler chains are defined and attached separately to the client and/or service provider. Each handler chain is activated in both directions, inbound and outbound, however developers can use the OUTBOUND Boolean property of the MessageContext to determine whether or not to activate logic within those handlers.
• As specified in Section 9.3.2 of the JAX-WS spec, for outbound messages "processing starts with the first handler in the chain and proceeds in the same order as the handler chain. For inbound messages the order of processing is reversed: processing starts with the last handler in the chain and proceeds in the reverse order of the handler chain." So assuming a handler chain of "H1->H2->H3", attaching such a chain to a web service provider would result in "H3->H2->H1->web service->H1->H2-H3" ordering.
• Handlers carry a MessageContext, a threadsafe mechanism holding request/response data between the handlers of a chain, and between the client or service endpoints and the handlers.
• Handler functionality does not cross the client - service boundary. With SOAP the only data passed between the client and service remains the SOAP message and (if using HTTP) any associated HTTP headers.
• Handlers are commonly attached to the SOAP client via a Java API, and to the web service via an XML configuration file. CXF offers additional options.

The Metro-based JAX-WS handler samples (in its WSDL-first and Java-first versions) provide a good example of using Handlers to log incoming and outgoing SOAP messages, from both the client and web service provider. This code can be used as-is with CXF. We'll expand on these examples by modifying the SOAP message, processing the SOAP request without the web service being activated, and using the MessageContext to pass property values between (client or service) endpoint and handlers. The following list of handler capabilities shows some of the functionality covered:

Steps:

1. Download and deploy the DoubleIt web service on Tomcat. This is just a check to make sure the DoubleIt web service and client is working properly on your machine before adding the handlers. Best not to proceed unless the SOAP calls from that tutorial can be made successfully.

2. Create the HandlerUtils.java class to output the MessageContext properties. Although this class would ideally be kept in just one place, to avoid architectural complexity for this tutorial we can add this class to both the client and service packages. Note this class is not exhaustive in the MessageContext properties it reports on--it does not output the HTTP header values and Servlet properties, for example.

3. Create the client-side handlers. For tutorial convenience, I'm nesting both handlers within a single class. Place the following ClientHandlers.java class in the Client submodule's client package:

4. Update the SOAP client to use the handlers. Replace the WSClient.java file from Step #9 of the DoubleIt tutorial with the below class.

5. Create the service-side handlers. I could not nest the service-side handlers into a single class as I could above for the client handlers, CXF, when reading the service-side handler chain configuration file, complains about not being able to instantiate the handlers unless they are declared standalone. At any rate, add the following classes to the service package:

6. Update the web service provider to use the handlers. Replace the DoubleItPortTypeImpl.java file from Step #6 of the DoubleIt tutorial with the below class. The handler configuration file (handlers.xml) is declared and the WebServiceContext is injected so the web service can read any APPLICATION-scoped properities created by the web service's handlers.

7. Attach the JAX-WS handlers to the web service provider. We'll now need to create the handlers.xml file declared in the previous step. This configuration file's XSD is defined in the JSR 181 Specification (Version 2.0, Appendix B).

   For the required location of the handler chain configuration file, CXF follows the JSR 181 standard (see Sect. 4.6.1) in that relative paths are evaluated from the location of the compiled class, and absolute paths (e.g., "/handlers.xml") with respect to the base of the classpath. In the sample I used an absolute path for @HandlerChain and placed the config file in a new service/src/main/resources directory. Per Maven's Standard Directory Layout rules, files in the resources directory are automatically placed by Maven in the classpath root (i.e., WEB-INF/classes) when it creates the web service WAR file.

8. Redeploy the web service and test that the client and service provider handlers are working. After redeploying the service, run the SOAP client again to follow the output of the four SOAP calls made. The client side handler output you should see on the console window as before. As for the web service provider, if you're using Linux, the handler output should be viewable from $CATALINA_HOME/logs/catalina.{date}.out; if Windows, the console window that is hosting Tomcat. You may wish to comment out some of the printMessageContext calls made above to reduce the output. Also note because of the MAX_VALUE limitation of 200 enforced by the client-side logical handler, the web service query doubling 300 will top out at 400.

Notes:

• You may find design and/or performance benefits using CXF-specific interceptors instead of JAX-WS defined handlers. For example, within CXF, SOAP handlers can carry a performance penalty, as SAAJ loads the entire message as a DOM object into memory, as CXF's Dan Kulp noted.

• RedHat has a chapter on writing handlers in its Developing Applications Using JAX-WS guide.

• See the Additional Resources section of my CXF interceptor article for simpler CXF-specific ways of modifying SOAP requests and responses.