To use the wsdl:operation element for an asynchronized mapping, an SEI based on asynchronous wsdl:operation mapping must be created by using the wsimport tool.

This section introduces how to create such an asynchronous wsdl:operation mapping.

To create asynchronous wsdl:operation mapping, bindings should be customized using the wsimport tool. The following is the binding configuration file, custom-schema.xml.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<bindings xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    wsdlLocation="http://localhost:8088/AddNumbers/addnumbers?wsdl"
    xmlns="http://java.sun.com/xml/ns/jaxws">
    <bindings node="wsdl:definitions">
        <enableAsyncMapping>true</enableAsyncMapping>
    </bindings>
</bindings>

If the binding setting is configured for wsdl:definitions as in the previous example, all wsdl:operation elements in the WSDL document have the same asynchronization setting.

The following is the portion of the build.xml file that uses the custom-schema.xml file.

...

<target name="build_client" depends="do-deploy-success, init">
    <antcall target="wsimport">
        <param name="package.name" value="async.client" />
        <param name="binding.file" value="-b ${src.conf}/custom-client.xml" />
        <param name="wsdl.file"
            value="http://localhost:8088/AddNumbers/addnumbers?wsdl" />
    </antcall>
    <antcall target="do-compile">
        <param name="javac.excludes" value="fromjava/server/" />
    </antcall>
</target>

...

Portable artifacts, which are created through the wsimport tool, are used to create the SEI with asynchronous methods as in the following.

public int addNumbers(int number1, int number2)
    throws java.rmi.RemoteException;
public Response<AddNumbersResponse> addNumbers(int number1, int number2);
public Future<?> addNumbers(int number1, int number2, 
                            AsyncHandler<AddNumbersResponse>);

As shown in the previous example, the two methods (polling and callback), whose return values are Response<AddNumbersResponse> and Future<?>, have been created. The following sub-sections describe how to create a Java client class using the two methods.

Asynchronous clients can be configured by using the polling or callback method.

How to create a client by using the polling method

The following is the polling method of an asynchronous SEI obtained through the wsimport tool.

public Response<AddNumbersResponse> addNumbers(int number1, int number2);

The following is an example of a client web service implemented by the method mapped to the polling method. The client application invokes an asynchronous polling method of SEI, and can check for the result.

javax.xml.ws.Response<AddNumbersResponse> resp = port.addNumbersAsync(10, 20);
while(!resp.isDone()){
}
System.out.println(resp.get().getReturn());
...

As shown in the previous example, the method mapped to the polling method returns the javax.xml.ws.Response object. The object can determine when the operation is complete by using the isDone() method inherited from java.util.concurrent.Future<T>, and return the result.

The following example shows a part of a client application code that supports the polling method.

public class AddNumbersClient {

   ...

   public static void main(String[] args) {
       try {
           AddNumbersImpl port = new AddNumbersService().getAddNumbersImplPort();

           // Asynchronous polling
           Response<AddNumbersResponse> resp = port.addNumbersAsync(10, 20);
           Thread.sleep(2000);
           AddNumbersResponse output = resp.get();
           System.out.println("#############################################");
           System.out.println("### JAX-WS Webservices examples - polling ###");
           System.out.println("#############################################");
           System.out.printf("call webservices in an Asynchronous Polling way...");
           System.out.printf("result : %d\n", output.getReturn());

           ...

       } catch (Exception e) {
           e.printStackTrace();
       }
   }

    ...

}

How to create a client by using the callback method

The following is the callback method of an asynchronous SEI obtained through the wsimport tool.

public Future<?> addNumbers(int number1, int number2,
    AsyncHandler<AddNumbersResponse>);

The method mapped to the callback method provides a handler object that implements the javax.xml.ws.AsynchHandler interface as an additional parameter.

The following is an example code of a handler object that implements the AsynchHandler interface.

public class AddNumbersClient {

    ...

    static class AddNumbersCallbackHandler implements
            AsyncHandler<AddNumbersResponse> {

        private AddNumbersResponse output;

        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 handler object invokes the handleResponse method when it obtains the web service operation result from the server at runtime. The client application can obtain the result by using the getResponse() method.

The following example is a part of client application code that uses the asynchronous callback method of SEI through the handler object. The client application invokes the asynchronous callback method of SEI, and checks for the result.

AddNumbersCallbackHandler callbackHandler = new AddNumbersCallbackHandler();
Future<?> resp = port.addNumbersAsync(number1, number2, callbackHandler);
while(!resp.isDone()){
}
System.out.println(callbackHandler .getResponse().getReturn());

As shown in the previous example, the method mapped to the callback method returns the javax.util.concurrent.Future object. The object can determine when the operation is complete by using the isDone() method, and return the result.

The following example is a part of the client application code that uses the asynchronous callback method of SEI.

public class AddNumbersClient {

  public static void main(String[] args) {
    try {
        AddNumbersImpl port = new AddNumbersService().getAddNumbersImplPort();
          ...

        // Asynchronous callback
        AddNumbersCallbackHandler callbackHandler = new AddNumbersCallbackHandler();
        Future<?> response = port.addNumbersAsync(10, 20, callbackHandler);
        Thread.sleep(2000);

        output = callbackHandler.getResponse();
        System.out.println("#############################################");
        System.out.println("### JAX-WS Webservices examples - callback ###");
        System.out.println("#############################################");
        System.out.printf("call webservices in an Asynchronous Callback way...");
        System.out.printf("result: %d\n", output.getReturn());
     } catch (Exception e) {
         e.printStackTrace();
     }
  }
    ...
}

This section shows how to execute an asynchronous client by using the implemented classes and other configuration files in this section.

Create a web service configured with asynchronous operations and deploy it to JEUS by using the following command.

$ ant build deploy

Once the service is deployed successfully, build the client.

Create a client configured with the handler framework, and invoke the service from the client.

As shown in the following, the console outputs the result of calling the polling and callback methods that have been processed successfully.

$ ant run

...

run:
     [java] #############################################
     [java] ### JAX-WS Webservices examples - polling ###
     [java] #############################################
     [java] call webservices in an Asynchronous Polling way...result : 30
     [java] #############################################
     [java] ### JAX-WS Webservices examples - callback ###
     [java] #############################################
     [java] call webservices in an Asynchronous Callback way...result: 30

...

BUILD SUCCESSFUL