Java ^TM API for XML Web Services
(JAX-WS)
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.

1. Asynchronous Invocation Using Static Stub

Client application should apply jaxws:enableAsyncMappingbinding 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