# Dispatch

Web service client applications may choose to work at the XML message level by using the `Dispatch<T>` APIs. The `javax.xml.ws.Dispatch<T>` interface provides support for the dynamic invocation of service endpoint operations.

Four Message Exchange Protocols(MEP) are supported: request-response, one way, asynchronous polling, and callback. Each of these invocation MEPs are required with JAXB data bound `java.lang.Object`, `javax.xml.transform.Source`, `javax.xml.soap.SOAPMessage` and `javax.activation.DataSource` object requests.

The `javax.xml.ws.Service` acts as a factory for the creation of `Dispatch<T>` instances. In addition, a `Dispatch<T>` instance is created in either `Service.Mode.PAYLOAD` or `Service.Mode.MESSAGE` modes. A `javax.xml.soap.SOAPMessage` request can only be used with a `Dispatch<T>` instance of `Service.Mode.MESSAGE` and using the SOAP Binding. A `javax.activation.DataSource` request can only be used with a `Dispatch<T>` instance of `Service.Mode.MESSAGE` and using the XML/HTTP Binding.

Note that the `Dispatch<T>` instance simply acts as a conduit for the request. No validation of the message is required to be performed by the implementation, though some may catch errors during request processing. It is up to the client program to supply well-formed XML requests.

## Programming Model

### Create a dynamic `Service`.

The `javax.xml.ws.Service` acts as a factory for the creation of a dynamic `Service`. When created for use with `Dispatch<T>` APIs the `Service` created can be either a `Service` that has knowledge of the binding information of a known `Service` or no knowledge of any specific `Service`.

That is, when the `Service` is created with a WSDL file the port(s) binding ID, QName, and endpoint address are known to the `Service`.

The methods to create a dynamic `Service` are shown here:

    Service service = Service.create(QName serviceQName);
    Service service = Service.create(URL wsdlLocation, QName serviceQName);

A `Dispatch<T>` instance must be bound to a specific port and endpoint before use. The service has an `addPort(QName portName, URI bindingID, String endpointAddress)` method that the client program can invoke for `Dispatch<T>` objects. Ports created using this method can only be used with `Dispatch<T>` instances.

If the `Service` has been created with WSDL binding information the the port need not be added as the `Dispatch<T>` instance will be created specific for the binding information provided in the supplied WSDL file.

Developers who have used web service applications in the past are familiar with the port `QName` and endpoint address parameters of this method. &jax-ws.product.name; supports three `Binding` URI's, that of the SOAP 1.1, the SOAP 1.2 and XML/HTTP Binding. For more information on SOAP 1.2 support please refer to the SOAP 1.2 documents. For the XML/HTTP binding please see chapter 11 of the JAX-WS 2.0 PFD Specification.

The addition of the SOAP 1.1 port using the `Service` API is shown here:

    service.addPort(QName portName, String SOAPBinding.SOAP11HTTP_BINDING,
            String endpointAddress);

SOAP 1.2 support has been implemented for `Dispatch`. This requires only one change in the programming model. The addition of the SOAP 1.2 port using the `Service` API is shown here:

    service.addPort(QName portName, String SOAPBinding.SOAP12HTTP_BINDING,
            String endpointAddress);

XML/HTTP binding support has been implemented for `Dispatch`. The creation of the XML/HTTP port using the `Service` API is shown here:

    service.addPort(QName portName, String HTTPBinding.HTTP_BINDING,
            String endpointAddress);

### Create a `Dispatch<T>` instance.

The `Dispatch<T>` object can be created using either of these two `Service` methods:

    Dispatch dispatch = service.createDispatch(QName portName,
            Class clazz, Service.Mode mode);
    Dispatch dispatch = service.createDispatch(QName portName,
            JAXBContext jaxbcontext, Service.Mode mode);

For a `javax.xml.transform.Source` and JAXB data binding `java.lang.Object` `Dispatch<T>` can be created in both `Service.Mode.PAYLOAD` and `Service.Mode.MESSAGE` modes. A `javax.xml.soap.SOAPMessage` can only be created in `Service.Mode.MESSAGE` mode. The first form of the `createDispatch` method is used to create a `javax.xml.transform.Source` or `javax.xml.soap.SOAPMessage` specific to the `Dispatch<T>` instance.

A JAXB object-specific instance can only be created using the second method listed above.

It is important to note that once the `Dispatch<T>` instance is created it is static. That is, its `Service.Mode` or request type can not be changed. The instance can be reused given the caveat that if it is a JAXB-specific `Dispatch<T>` it must be reused with objects known to the same `JAXBContext`.

### Set the context `Map<String, Object>` for the request.

The `Dispatch<T>` interface extends the `javax.xml.ws.BindingProvider` interface. The `BindingProvider` interface defines accessor methods for the request and response context maps. Standard `BindingProvider` properties are defined by the JAX-WS 2.0 specification and the client program may set and get these properties. The application may also define application-specific properties, but the specification discourages this for portability reasons.

### Prepare the message request.

This is the client developer's responsibility. For examples of how to prepare specific request types refer to the `Dispatch<T>` sample applications.

### Invoke the web service request.

Four types of invocation MEPs are supported using the methods below. In methods that produce a response, the type of `Object` returned will be of the same type as the request. For example, a `SOAPMessage` request will return a `SOAPMessage` response.

    Object response = dispatch.invoke(T);
    dispatch.invokeOneway(T);
    Response<T> response = dispatch.invokeAsync(T);
    Future<?> response = dispatch.invokeAsync(T, AsyncHandler);

## Dispatch and Asynchronous Invocations

Asynchronous invocations require special consideration. The first form of the `invokeAsync` method is a polling method. The response, `Response<T>`,returns to the user immediately and may be polled for completion. In the meantime, the client program can do other work.

The `javax.xml.ws.Response<T>` implements the `java.util.concurrent.Future<T>` interface that is included in J2SE 5.0. The `Response<T>` object returns the actual response via its `get` method, which blocks if the response is not ready to be returned.

The `Future<T>` interface also has a `cancel` method that will attempt to cancel the request invocation if the request is being invoked.

Faults returned from the service or exceptions thrown during the invocation are returned when the `Response<T>` `get` method is called. Because the execution doesn't occur in the main thread, the exception or fault returned is wrapped in an `java.util.concurrent.ExecutionException`. To obtain the actual cause use the `getCause` method of `ExecutionException`.

For more information on the `java.util.concurrent.Future<?>` interface see the J2SE 5.0 documentation.

    public interface Response<T> extends java.util.concurrent.Future<T> {

        Map<String, Object> getContext();

    }

The second form of the `invokeAsync` method has a second parameter of type `javax.xml.ws.AsyncHandler`. The purpose of the `AsyncHandler` is to get and handle the the response or any fault thrown in an application-specific way. The `AsyncHandler` has a method `handleResponse(Response<T>)` that takes a `javax.xml.ws.Response<T>` parameter. This method gets the response or any faults and processes them according to behavior defined in the application. Note that it is the responsibility of the client program to implement the asynchronous handler.

    class ResponseHandler implements javax.xml.ws.AsyncHandler {

        public handleResponse(Response<T>);

    }

This form of the asynchronous invocation method returns a `Future<?>` object with wildcard type. As in the asynchronous poll invocation, the `Future<T>` object can be polled to see if the response is ready. However, calling the `get` method will not return the response of the invocation, but an object of indeterminate type.

Examples of synchronous and asynchronous invocations are shown in the `Dispatch<T>` samples. For convenience an example of `Response<T>` usage is display here:

    Response<Source> response = dispatch.invokeAsync(Source);
    while (!response.isDone()) {
        //go off and do some work
    }

    try {
        //get the actual result
        Source result = (javax.xml.transform.Source) response.get();
        //do something with the result
    } catch (ExecutionException ex) {
        //get the actual cause
        Throwable cause = ex.getCause();
    } catch (InterupptedException ie) {
        //note interruptions
        System.out.println("Operation invocation interrupted");
    }