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

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

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.

## 1. 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 async customization for details on how this can be applied to the WSDL file.

Lets look at the following WSDL excerpt:

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

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>);

### 1.1 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());
            ...

### 1.2 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());

## 2. Asynchronous Invocation Using Dispatch

## For information on the Dispatch API and asynchronous invocations see Dispatch and Asynchronous Invocations