# Java TM API for XML Web Services
(JAX-WS)
Handler

Specification Version: 2.2
Implementation Version: 2.2.5

- Overview
- Provider
- AsyncProvider
- Dispatch
- Asynchronous Client
- Handler
- MTOM and Swaref
- SOAP 1.2
- WSDL Customization
- Annotations
- WS-Addressing
- Stateful Webservice
- Catalog
- Interoperability

## Handler Types

JAX-WS 2.0 defines a `Handler` interface, with subinterfaces `LogicalHandler` and `SOAPHandler`. The `Handler` interface contains `handleMessage(C context)` and `handleFault(C context)` methods, where `C` extends `MessageContext`. A property in the `MessageContext` object is used to determine if the message is inbound or outbound. `SOAPHandler` objects have access to the full soap message including headers. Logical handlers are independent of protocol and have access to the payload of the message.

The new handler types can now be written without casting the message context object that is passed to them. For instance:

    public class MyLogicalHandler implements LogicalHandler<LogicalMessageContext> {
        public boolean handleMessage(LogicalMessageContext messageContext) {
            LogicalMessage msg = messageContext.getMessage();
            return true;
        }
        // other methods
    }

    public class MySOAPHandler implements SOAPHandler<SOAPMessageContext> {

        public boolean handleMessage(SOAPMessageContext messageContext) {
            SOAPMessage msg = messageContext.getMessage();
            return true;
        }
        // other methods
    }

A `close(C context)` method has been added that is called on the handlers at the conclusion of a message exchange pattern. This allows handlers to clean up any resources that were used for the processing of a request-only or request/response exchange.

The `init()` and `destroy()` methods of the handler lifecycle no longer exist. Instead, a method may be annotated with the `@PostConstruct` annotation to be called after the handler is created or the `@PreDestroy` annotation to be called before the handler is destroyed. Note that the annotated methods must return `void` and take no arguments:

    import javax.annotation.PostConstruct;
    import javax.annotation.PreDestroy;

    public class MyLogicalHandler implements LogicalHandler<LogicalMessageContext> {
        @PostConstruct
        public void methodA() { }

        @PreDestroy
        public void methodB() {}

        // other methods
    }

## MessageContext

In the examples above, the `LogicalMessage` object allows a handler to get and set the message payload either as a JAXB object or as a `javax.xml.transform.Source`. The `SOAPMessage` object allows access to headers and the SOAP body of the message.

Both context objects extend `MessageContext`, which holds properties that the handlers can use to communicate with each other. A standard property `MessageContext.MESSAGE_OUTBOUND_PROPERTY` holds a `Boolean` that is used to determine the direction of a message. For example, during a request, the property would be `Boolean.TRUE` when seen by a client handler and `Boolean.FALSE` when seen by a server handler.

The message context object can also hold properties set by the client or provider. For instance, port proxy and dispatch objects both extend `BindingProvider`. A message context object can be obtained from both to represent the request or response context. Properties set in the request context can be read by the handlers, and the handlers may set properties on the message context objects passed to them. If these properties are set with the scope `MessageContext.Scope.APPLICATION` then they will be available in the response context to the client. On the server end, a context object is passed into the `invoke` method of a `Provider`.

## Handler Chain Configuration

### Handler Files

Starting from a WSDL file, handler chain configuration is through WSDL customizations as defined by JSR 109. A `<handler-chains>` element is added to the customization file. The following is a simple handler chain with one handler (customization may be on server or client side):

    <-- excerpt from customization file -->
    <bindings xmlns="http://java.sun.com/xml/ns/jaxws">
      <handler-chains xmlns="http://java.sun.com/xml/ns/javaee">
        <handler-chain>
          <handler>
            <handler-class>fromwsdl.handler_simple.common.TestHandler</handler-class>
          </handler>
        </handler-chain>
      </handler-chains>
    </bindings>

Multiple `handler-chain` elements may exist within the `handler-chains` element. These may optionally use a service name, port name, or protocol pattern in their description to apply some chains to certain ports and protocols and not to others. For instance (note the wildcard character used in the service name):

      <-- excerpt -->
      <handler-chains xmlns="http://java.sun.com/xml/ns/javaee">
        <handler-chain>
          <service-name-pattern xmlns:ns1="urn:namespace">ns1:My*Service</service-name-pattern>
          <handler>...</handler>
        </handler-chain>

        <handler-chain>
          <port-name-pattern xmlns:ns1="urn:namespace">ns1:HelloPort</port-name-pattern>
          <handler>...</handler>
        </handler-chain>

        <handler-chain>
          <protocol-bindings>##SOAP11_HTTP</protocol-bindings>
          <handler>...</handler>
        </handler-chain>
      </handler-chains>

Handlers will appear in the final handler chain in the order that they are included in the customization file. However, logical handlers will be sorted out and called before protocol handlers during execution.

Starting from a Java class, annotations are used to describe the handler chain as defined by JSR 181. The following example uses the `@HandlerChain` annotation to refer to a file describing the chain.

    import javax.jws.HandlerChain;
    import javax.jws.WebService;

    @WebService
    @HandlerChain( file="handlers.xml")
    public class MyServiceImpl {
        // implementation of class
    }

An example `handlers.xml` file is shown below. The schema is the same that is used for the customization.

    <?xml version="1.0" encoding="UTF-8"?>
    <jws:handler-chains xmlns:jws="http://java.sun.com/xml/ns/javaee">
      <jws:handler-chain>
        <jws:handler>
          <jws:handler-class>fromjava.handler_simple.common.TestHandler</jws:handler-class>
        </jws:handler>
      </jws:handler-chain>
    </jws:handler-chains>

When packaging the service, the handlers.xml file must be in the classpath within the WAR file, either directly under `WEB-INF/classes` or further down in the same package as the service class file.

On the server side, the handlers may be configured in the sun-jaxws.xml deployment descriptor as well. A handler chain specified here will override handlers in WSDL customizations or annotated classes. The schema for the handler section is the same as in the previous examples:

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

### Programmatic Case

Handler chains may be configured on the client side at runtime by setting a chain directly on a `BindingProvider` (e.g., a `Dispatch` object or a port proxy) or by using a `HandlerResolver`. This example shows how to add a handler chain to a port proxy:

        // given proxy interface HelloPortType
        HelloPortType myProxy = // create proxy

        Binding binding = ((BindingProvider)myProxy).getBinding();

        // can create new list or use existing one
        List<Handler> handlerList = binding.getHandlerChain();

        handlerList.add(new MyHandler());
        binding.setHandlerChain(handlerList);

To configure the handlers that are added to newly created `Binding` objects, add a handler resolver to the service with `setHandlerResolver()`. The new resolver will be used whenever a `BindingProvider` is created from the service. An example resolver is as follows:

    /*
     * Add handlers to the returned list based on the information
     * in info.getBindingID(), getPortName(), and/or getServiceName().
     */
    public class MyResolver implements HandlerResolver {
        public List<Handler> getHandlerChain(PortInfo info) {
            List<Handler> handlers = new ArrayList<Handler>();
            // add handlers to list based on PortInfo information
            return handlers;
        }
    }

A resolver that modifies the initially configured handler chains could be written by calling `service.getHandlerResolver()` and passing the original resolver to a new one:

        // original HandlerResolver passed in constructor or setter method
        public List<Handler> getHandlerChain(PortInfo info) {
            List<Handler> handlers = originalResolver.getHandlerChain(info);
            // alter list based on PortInfo information
            return handlers;
        }

## Handler Samples

The `fromjavahandler` and `fromwsdlhandler` samples set a `SOAPHandler` on the client and server. This handler simply outputs the contents of the SOAP message and can be used to see the requests and responses being passed back and forth. See the sample documentation for information on running the samples.