The handler is an Interface from JAX-WS to intercept the request and response SOAP messages. Sometimes can be necessary to access SOAP message to additional process. The SOAP message Handler provides a mechanism for intercepting the SOAP message.

The two types of handler supported by JAX-WS are:

  1. SOAPHandler: can access the soap messages and headers (access the entire SOAP message)
  2. LogicHandler: can access just the payload of the messages.

If SOAP handlers are used in conjunction with policies (security, WS-ReliableMessaging, MTOM, and so on), for inbound messages, the policy interceptors are executed before the user-defined message handlers. For outbound messages, this order is reversed. [1]

Add SOAP Message Handlers

1. Design the handlers and handler chains

You should define the number of handlers you need and the sequence of the execution.

handler.xml

2. For each handler in the handler chain, create a Java class that implements the SOAP message handler interface.

  • The handleMessage method is called to intercept a SOAP message request before and after it is processed by the back-end component.
  • The MessageContext properties allow the handlers in a handler chain to determine if a message is inbound or outbound and to share processing state.
  • Each context object extends javax.xml.ws.handler.MessageContext, which enables you to access a set of runtime properties of a SOAP message handler from the client application or Web service.
    • You can use the MessageContext.MESSAGE_OUTBOUND_PROPERTY property to determine if the message is an inbound or outbound request because it holds a Boolean value. The property would be true when accessed by a client-side handler or false when accessed by a server-side handler.
  • The method handleFault is executed in case of exception.

After the method is processed you can invoke the next handler from the handler-chain returning true, or block processing returning false.

Soap Class

3. Update your JWS file, adding annotations to configure the SOAP message handlers.
  • Configure Handler Chains
    • You can use the @javax.jws.HandlerChain annotation to configure a handler chain for a Web service. Use the file attribute to specify an external file that contains the configuration of the handler chain. The configuration includes the list of handlers in the chain, the order in which they execute, the initialization parameters, and so on.
  • Create the Handler Chain Configuration File
  • Configure the Client-side SOAP Message Handlers
    • Set a handler chain directly on the javax.xml.ws.BindingProvider,
    • Implement a javax.xml.ws.handler.HandlerResolver on a Service instance
    • Create a customization file that includes an element that contains a handler chain description.
    • The schema for the element is the same for both handler chain files (on the server) and customization files.

Steps to execute

When the WS is invoked to be executed on server-side[2], the steps are:

  • Execute all the inbound methods for handlers in the handler chain. Any of them might change the SOAP message request.
  • As soon as the last handler executes, the back-end component that implements are executed.
  • After the back-end component has finished executing, the outbound methods are executed in the reverse order specified by the JWS annotation. Any of them might change the SOAP message response.
  • The final SOAP message response is returned to the client application as soon as the first handler in the handler chain executes.

Conclusion

If you are working on XML-Based Web Service, SOAP, and need to do some process before the service, it is a great solution for you. This and the Logger are powerful tools for your system.

References

  • https://stackoverflow.com/questions/1945618/tracing-xml-request-responses-with-jax-ws
  • https://docs.oracle.com/cd/E17904_01/web.1111/e13734/handlers.htm#WSADV160
  • https://examples.javacodegeeks.com/enterprise-java/jws/jax-ws-logging-with-handler-example/
  • http://java.boot.by/scdjws5-guide/ch09s05.html