# Asynchronous Client

This document describes how a client application can invoke a remote web service asynchronously. It can do so either by generating a static stub or using the Dispatch API.

## Asynchronous Invocation Using Static Stub

Client application should apply `jaxws:enableAsyncMapping` binding declaration to the WSDL file to generate asynchronous method in the service endpoint interface. Please refer to for details on how this can be applied to the WSDL file.

Lets look at the following WSDL excerpt:

    <definitions
            name="AddNumbers"
            targetNamespace="http://duke.example.org"
            xmlns:tns="http://duke.example.org"
            xmlns="http://schemas.xmlsoap.org/wsdl/"
            xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">

        ...

        <portType name="AddNumbersImpl">
            <operation name="addNumbers">
                <input message="tns:addNumbers"/>
                <output message="tns:addNumbersResponse"/>
            </operation>
        </portType>
        <binding name="AddNumbersImplBinding" type="tns:AddNumbersImpl">
            <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
                    style="document"/>
            <operation name="addNumbers">
                <soap:operation soapAction=""/>
                <input>
                    <soap:body use="literal"/>
                </input>
                <output>
                    <soap:body use="literal"/>
                </output>
            </operation>
        </binding>

        ...

    </definitions>

In order to generate a service endpoint interface with asynchronous methods the following binding declaration file will be passed to `wsimport`:

    <bindings
            xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
            wsdlLocaption="http://localhost:8080/jaxws-async/addnumbers?WSDL"
            xmlns="http://java.sun.com/xml/ns/jaxws">
        <bindings node="wsdl:definitions">
            <package name="async.client"/>
            <enableAsyncMapping>true</enableAsyncMapping>
        </bindings>
    </bindings>

It produces the following service endpoint interface (annotations are removed from the synchronous method for better readability):

    //synchronous method
    public int addNumbers(int number1, int number2) throws java.rmi.RemoteException;

    //async polling Method
    public Response<AddNumbersResponse> addNumbers(int number1, int number2);

    //async callback Method
    public Future<?> addNumbers(int number1, int number2, AsyncHandler<AddNumbersResponse>);

### Async Polling

    //async polling Method
    public Response<AddNumbersResponse> addNumbers(int number1, int number2);

Typically a client application will invoke the async polling operation on the stub and check for a response on the returned `Response` object. The response is available when `Response.isDone` returns true.

    javax.xml.ws.Response<AddNumbersResponse> resp = port
            .addNumbersAsync(10, 20);
    while (!resp.isDone()) {
        //do something
    }
    System.out.println("The sum is: " + resp.get().getReturn());

    ...

### Async Callback

    //async callback Method
    public Future<?> addNumbers(int number1, int number2, AsyncHandler<AddNumbersResponse>);

Here the client application provides an `AsyncHandler` by implementing the `javax.xml.ws.AsyncHandler<T>` interface.

    /**
     * Async callback handler
     */
    class AddNumbersCallbackHandler implements
            AsyncHandler<AddNumbersResponse> {
        private AddNumbersResponse output;

        /**
         * @see javax.xml.ws.AsyncHandler#handleResponse(javax.xml.ws.Response)
         */
        public void handleResponse(Response<AddNumbersResponse> response) {
            try {
                output = response.get();
            } catch (ExecutionException e) {
                e.printStackTrace();
            } catch (InterruptedException e) {
                e.printStackTrace();
            }
        }

        AddNumbersResponse getResponse() {
            return output;
        }
    }

The async handler is then passed as the last parameter of the async callback method:

    //instantiates the callback handler
    AddNumbersCallbackHandler callbackHandler = new
            AddNumbersCallbackHandler();

    //invoke the async callback method
    Future<?> resp = port.addNumbersAsync(number1, number2, callbackHandler);
    while (!resp.isDone()) {
        //do something
    }
    System.out.println("The sum is: " + callbackHandler.getResponse().getReturn());

## Asynchronous Invocation Using Dispatch

For information on the Dispatch API and asynchronous invocations see