Use handlers in JAX-WS Web services

Java API for XML 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.

we need an EAR file for the applications to configure. If running in a Thin Client for JAX-WS environment, then we 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.

As in the JAX-RPC programming model, the JAX-WS model provides an application handler facility that enables you 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. 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. You 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 created. 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")

See on the schema of the handler configuration file, see the JSR 181 specification.

See regarding JAX-WS handlers, see chapter 9 of the JAX-WS specification.

 

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

2. Set 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 determine if we 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.

   1. 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.

   2. 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.

3. Set 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.

4. Create the handler chain configuration XML file. You must create a handler chain configuration XML file for the @HandlerChain to reference.

5. 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. You must also include the handler classes contained in the configuration XML file in the class path.

6. Write the handler implementation.

 

Results

we 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

The following example illustrates the 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 created.

The following file illustrates a typical handler configuration file. The protocol-bindings, port-name-pattern, and service-name-pattern elements are all filters that are 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">
<!-- 
  The '*" denotes a wildcard. -->

  <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 you 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;
    }

}

 

Next steps

Deploy the Web services application.

JAX-WS
JAX-WS client model

 

Related tasks

Implement Web services applications with JAX-WS
Implementing JAX-WS Web services clients

 

Related

JAX-WS annotations
Web services specifications and APIs

 

Related information

Java API for XML Web Services (JAX-WS) API documentation
Java API for XML Web Services (JAX-WS) API User's Guide documentation