Sunday, May 29, 2016

JAX-WS client and server SOAP handler


I've found this interesting series of articles form Mkyong where he briefly explains how to write and configure SOAP handlers for client and server JAX-WS Webservices.

Then I've added some features: dependency management via Maven for client and server projects; a helper class to configure client's SOAP handler so it's possible to rebuild endpoint using wsimport any time is needed; and for last, I configured client's Maven POM file to run wsimport during generate-sources phase.

You can find these client and server in my GitHub repository. Clone them using the command:

git clone


The service runs over a Jetty web container. You can run it with the command (in the hello-server folder):

$ mvn clean jetty:run

You can check the service running, putting this URL in your browser:


And to check the WSDL, put this URL:


This service is very simple. It just send the string "Hello, <name>" over the network, given that the client has sent the expected IP address.
The service class is annotated with @HandlerChain(file="handler-chain.xml") which points to a handler class declaration. This xml file can be found in the src/main/resources folder.

What is cool about this handler is that with it you can intercept the inbound or outbound messages and enrich, validate or decorate them.


The client also has a handler attached to it, intercepting inbound and outbound messages.

In Mkyong's example, the handler is injected via annotation. But the annotation is put over the Webservice class and I wanted it generated automatically at every build. So I took a different approach:

To configure a handler, I implemented HandlerResolver as seen in this article. Then I just added the HandlerResolver to the Webservice class, as seen below.

As seen in client's Maven POM file, all client's Webservice classes are generated  during generate-sources phase.


Using handlers in JAX-WS Webservices is a great and clean way to handle inbound and outbound SOAP messages.