The asynchronous style of invocation requires extra stub code (for example, dedicated asychronous methods defined on the service endpoint interface). This special stub code is not generated by default, however. To switch on the asynchronous feature and generate the requisite stub code, you must use the mapping customization feature from the WSDL 2.0 specification.
Customization enables you to modify the way the wsdl2java utility generates stub
code. In particular, it enables you to modify the WSDL-to-Java mapping and to switch on
certain features. Here, customization is used to switch on the asynchronous invocation
feature. Customizations are specified using a binding declaration, which you define using
a jaxws:bindings
tag (where the jaxws prefix is tied to the
http://java.sun.com/xml/ns/jaxws" namespace). There are two alternative ways of specifying
a binding declaration:
-
External binding declaration - the
jaxws:bindings
element is defined in a file separately from the WSDL contract. You specify the location of the binding declaration file to the wsdl2java utility when you generate the stub code. -
Embedded binding declaration - you can also embed the
jaxws:bindings
element directly in a WSDL contract, treating it as a WSDL extension. In this case, the settings injaxws:bindings
apply only to the immediate parent element.
This section considers only the first approach, the external binding declaration. The template for a binding declaration file that switches on asynchronous invocations is shown below.
Template for an Asynchronous Binding Declaration
<bindings xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
wsdlLocation="@WSDL_LOCATION@/hello_world_async.wsdl"
xmlns="http://java.sun.com/xml/ns/jaxws">
<bindings node="wsdl:definitions">
<enableAsyncMapping>true</enableAsyncMapping>
</bindings>
</bindings>
Where AffectedWSDLContract specifies the URL of
the WSDL contract that is affected by this binding declaration. The AffectedNode is an XPath value that specifies which node (or
nodes) from the WSDL contract are affected by this binding declaration. You can set
AffectedNode to wsdl:definitions
, if
you want the entire WSDL contract to be affected. The {jaxws:enableAsyncMapping}} element
is set to true
to enable the asynchronous invocation feature.
For example, if you want to generate asynchronous methods only for the
GreeterAsync
port type, you could specify <bindings node="wsdl:definitions/wsdl:portType[@name='GreeterAsync']">
in
the preceding binding declaration.
Assuming that the binding declaration is stored in a file,
async_binding.xml
, you can generate the requisite stub files with
asynchronous support by entering the following wsdl2java command:
wsdl2java -client -d ClientDir -b async_binding.xml hello_world.wsdl
When you run the wsdl2java command, you specify the location of the binding
declaration file using the -b option. After generating the stub code in this way, the
GreeterAsync
service endpoint interface (in the file
GreeterAsync.java
) is defined as shown below.
Service Endpoint Interface with Methods for Asynchronous Invocations
/* Generated by WSDLToJava Compiler. */
package org.apache.hello_world_async_soap_http;
...
import java.util.concurrent.Future;
import javax.xml.ws.AsyncHandler;
import javax.xml.ws.Response;
...
public interface GreeterAsync {
public Future<?> greetMeSometimeAsync(
java.lang.String requestType,
AsyncHandler<org.myorg.types.GreetMeSometimeResponse> asyncHandler
);
public Response<org.myorg.types.GreetMeSometimeResponse>
greetMeSometimeAsync(java.lang.String requestType);
public java.lang.String greetMeSometime(java.lang.String requestType);
}
In addition to the usual synchronous method, greetMeSometime()
, two
asynchronous methods are also generated for the greetMeSometime
operation, as
follows:
-
greetMeSometimeAsync()
method withFuture<?>
return type and an extrajavax.xml.ws.AsyncHandler
parameter - call this method for the callback approach to asynchronous invocation. -
greetMeSometimeAsync()
method withResponse<GreetMeSometimeResponse>
return type - call this method for the polling approach to asynchronous invocation.
The details of the callback approach and the polling approach are discussed in the following subsections.