Use handlers in JAX-WS web services

Use handlers in JAX-WS web services

JAX-WS provides you with a standard way of developing interoperable and portable web services. Use JAX-WS handlers to customize web services requests or response handling.

You need an EAR file for the applications to configure. If we are running in a Thin Client for JAX-WS environment, then you are not required to begin with an EAR file. For some handler use, such as logging or tracing, only the server or client application needs to be configured. For other handler use, including sending information in SOAP headers, the client and server applications must be configured with symmetrical handlers.
The modules in the EAR file must contain the handler classes to configure. The handler classes implement the javax.xml.ws.handler.LogicalHandler<LogicalMessageContext> interface or the javax.xml.ws.handler.soap.SOAPHandler<SOAPMessageContext> interface.
Remember: If we intercept an inbound SOAPMessage and then manipulate it, such as adding an attachment part, use the setmessage part of the SOAPMessageContext to ensure that the attachment is part of the SOAPMessageContext. This ensures that the JAX-WS runtime can access this latest SOAPMessage so that it can properly process the attachment parts. The following example demonstrates this process.
 SOAPMessage m = context.getMessage(); 
 AttachmentPart ap1 = m.createAttachmentPart(); 
 ap1.setContent("abc", "text/plain");           
 m.addAttachmentPart(ap1);
 context.setMessage(m);                       
As in JAX-RPC, the JAX-WS programming model provides an application handler facility that enables us to manipulate a message on either an inbound or an outbound flow. We can add handlers into the JAX-WS runtime environment to perform additional processing of request and response messages. We can use handlers for a variety of purposes such as capturing and logging information and adding security or other information to a message. Because of the support for additional protocols beyond SOAP, JAX-WS provides two different classifications for handlers. One type of handler is a logical handler that is protocol independent and can obtain the message in the flow as an extensible markup language (XML) message. The logical handlers operate on message context properties and message payload. These handlers must implement the javax.xml.ws.handler.LogicalHandler interface. A logical handler receives a LogicalMessageContext object from which the handler can get the message information. Logical handlers can exist on both SOAP and XML/HTTP-based configurations.
The second type of handler is a protocol handler. The protocol handlers operate on message context properties and protocol-specific messages. Protocol handlers are limited to SOAP-based configurations and must implement the javax.xml.ws.handler.soap.SOAPHandler interface. Protocol handlers receive the message as a javax.xml.soap.SOAPMessage to read the message data.
The JAX-WS runtime makes no distinction between server-side and client-side handler classes. The runtime does not distinguish between inbound or outbound flow when a handleMessage(MessageContext) method or handleFault(MessageContext) method for a specific handler is invoked. We must configure the handlers for the server or client, and implement sufficient logic within these methods to detect the inbound or outbound direction of the current message.
To use handlers with web services client applications, add the @HandlerChain annotation to the service endpoint interface or the generated service class and provide the handler chain configuration file. The @HandlerChain annotation contains a file attribute that points to a handler chain configuration file that we create. For web services client applications, we can also configure the handler chain programmatically using the Binding API. To modify the handlerchain class programmatically, use either the default implementation or a custom implementation of the HandlerResolver method.
To use handlers with the server application, set the @HandlerChain annotation on either the service endpoint interface or the endpoint implementation class, and provide the associated handler chain configuration file. Handlers for the server are only configured by setting the @HandlerChain annotation on the service endpoint implementation or the implementation class. The handler classes must be included in the server application EAR file.
For both server and client implementations of handlers using the @HandlerChain annotation, specify the location of the handler configuration as either a relative path from the annotated file or as an absolute URL. For example:
@HandlerChain(file="../../common/handlers/myhandlers.xml")
or
@HandlerChain(file="http://foo.com/myhandlers.xml")
For more information on the schema of the handler configuration file, see the JSR 181 specification.
For more information regarding JAX-WS handlers, see chapter 9 of the JAX-WS specification.

Determine if to implement JAX-WS handlers on the service or the client.

Configure the client handlers by setting the @HandlerChain annotation on the service instance or service endpoint interface, or we can modify the handler chain programmatically to control how the handler chain is built in the runtime. If we choose to modify the handler chain programmatically, then you must determine if you will use the default handler resolver or use a custom implementation of a handler resolver that is registered on the service instance. A service instance uses a handler resolver when creating binding providers. When the binding providers are created, the handler resolver that is registered with a service is used to create a handler chain and the handler chain is subsequently used to configure the binding provider.

Use the default implementation of a handler resolver. The runtime now uses the @HandlerChain annotation and the default implementation of HandlerResolver class to build the handler chain. We can obtain the existing handler chain from the Binding, add or remove handlers, and then return the modified handler chain to the Binding object.

To use a custom implementation of a handler resolver, set the custom HandlerResolver class on the Service instance. The runtime uses the custom implementation of the HandlerResolver class to build the handler chain, and the default runtime implementation is not used. In this scenario, the @HandlerChain annotation is not read when retrieving the handler chain from the binding after the custom HandlerResolver instance is registered on the Service instance. We can obtain the existing handler chain from the Binding, add or remove handlers, and then return the modified handler chain to the Binding object.

Configure the server handlers by setting the @HandlerChain annotation on the service endpoint interface or implementation class. When the @HandlerChain annotation is configured on both the service endpoint interface and the implementation class, the implementation class takes priority.

Create the handler chain configuration XML file. Create a handler chain configuration XML file for the @HandlerChain to reference.

Add the handler chain configuration XML file in the class path for the service endpoint interface when configuring the server or client handlers using the @HandlerChain annotation. We must also include the handler classes contained in the configuration XML file in the class path.

Write the handler implementation.

Results

You have the enabled the JAX-WS web service or web services client to use handlers to perform additional processing of request and response message exchange.

Example

Example steps necessary to configure JAX-WS handlers on a service endpoint interface using the @HandlerChain annotation.
The @HandlerChain annotation has a file attribute that points to a handler chain configuration XML file that we create. The following file illustrates a typical handler configuration file. The protocol-bindings, port-name-pattern, and service-name-pattern elements are all filters used to restrict which services can apply the handlers.
<?xml version="1.0" encoding="UTF-8"?>

<jws:handler-chains xmlns:jws="http://java.sun.com/xml/ns/javaee">


 <jws:handler-chain name="MyHandlerChain">
  <jws:protocol-bindings>##SOAP11_HTTP ##ANOTHER_BINDING</jws:protocol-bindings>
  <jws:port-name-pattern 
              xmlns:ns1="http://handlersample.samples.ibm.com/">ns1:MySampl*</jws:port-name-pattern>
        <jws:service-name-pattern 
              xmlns:ns1="http://handlersample.samples.ibm.com/">ns1:*</jws:service-name-pattern>
  <jws:handler>
   <jws:handler-class>com.ibm.samples.handlersample.SampleLogicalHandler</jws:handler-class>
  </jws:handler>
  <jws:handler>
   <jws:handler-class>com.ibm.samples.handlersample.SampleProtocolHandler2</jws:handler-class>
  </jws:handler>
  <jws:handler>
   <jws:handler-class>com.ibm.samples.handlersample.SampleLogicalHandler</jws:handler-class>
  </jws:handler>
  <jws:handler>
   <jws:handler-class>com.ibm.samples.handlersample.SampleProtocolHandler2</jws:handler-class>
  </jws:handler>
 </jws:handler-chain>
 
</jws:handler-chains>

</jws:handler-chains>
Make sure that we add the handler.xml file and the handler classes contained in the handler.xml file in the class path.
The following example demonstrates a handler implementation:
package com.ibm.samples.handlersample;

import java.util.Set;

import javax.xml.namespace.QName;
import javax.xml.ws.handler.MessageContext;
import javax.xml.ws.handler.soap.SOAPMessageContext;

public class SampleProtocolHandler implements         javax.xml.ws.handler.soap.SOAPHandler<SOAPMessageContext> {

    public void close(MessageContext messagecontext) {
    }

    public Set<QName> getHeaders() {
        return null;
    }

    public boolean handleFault(SOAPMessageContext messagecontext) {
        return true;
    }

    public boolean handleMessage(SOAPMessageContext messagecontext) {
        Boolean outbound = (Boolean) messagecontext.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);
        if (outbound) {
            // Include the steps for the outbound flow.
        }
        return true;
    }

}
What to do next
Deploy the web services application.

Related concepts

JAX-WS
JAX-WS client programming model

Related tasks

Implement web services applications with JAX-WS
Implement static JAX-WS web services clients

JAX-WS annotations
Web services specifications and APIs

Related information:

JAX-WS API documentation
JAX-WS API User's Guide documentation