Package com.sun.xml.ws.api.server

Interface AsyncProvider<T>

public interface AsyncProvider<T>

Asynchronous version of Provider.

Applications that use the JAX-WS RI can implement this interface instead of Provider to implement asynchronous web services (AWS.) AWS enables applications to perform operations with long latency without blocking a thread, and thus particularly suitable for highly scalable service implementation, at the expesnce of implementation complexity.

Programming Model

Whenever a new reuqest arrives, the JAX-WS RI invokes the invoke(T, com.sun.xml.ws.api.server.AsyncProviderCallback<T>, jakarta.xml.ws.WebServiceContext) method to notify the application. Normally, the application then schedules an execution of this request, and exit from this method immediately (the point of AWS is not to use this calling thread for request processing.)

Unlike the synchronous version, which requires the response to be given as the return value, with AWS the JAX-WS RI will keep the connection with client open, until the application eventually notifies the JAX-WS RI via AsyncProviderCallback. When that happens that causes the JAX-WS RI to send back a response to the client.

The following code shows a very simple AWS example:

 @WebService
 class MyAsyncEchoService implements AsyncProvider<Source> {
     private static final Executor exec = ...;

     public void invoke( final Source request, final AsyncProviderCallback<Source> callback, final WebServiceContext context) {
         exec.execute(new Runnable() {
             public void run() {
                 Thread.sleep(1000);     // kill time.
                 callback.send(request); // just echo back
             }
         });
     }
 }
 

Please also check the Provider and its programming model for general provider programming model.

WebServiceContext

In synchronous web services, the injected WebServiceContext instance uses the calling Thread to determine which request it should return information about. This no longer works with AWS, as you may need to call WebServiceContext much later, possibly from entirely different thread.

For this reason, AsyncProvider passes in WebServiceContext as a parameter. This object remains usable until you invoke AsyncProviderCallback, and it can be invoked from any thread, even concurrently. AWS must not use the injected WebServiceContext, as its behavior is undefined.

Since:

2.1

Author:

Jitendra Kotamraju, Kohsuke Kawaguchi

See Also:

Provider

Method Summary

Modifier and Type	Method	Description
void	invoke(T request, AsyncProviderCallback<T> callback, jakarta.xml.ws.WebServiceContext context)	Schedules an execution of a request.

Method Detail

invoke

void invoke(@NotNull
            T request,
            @NotNull
            AsyncProviderCallback<T> callback,
            @NotNull
            jakarta.xml.ws.WebServiceContext context)

Schedules an execution of a request.

Parameters:

request - Represents the request message or payload.

callback - Application must notify this callback interface when the processing of a request is complete.

context - The web service context instance that can be used to retrieve context information about the given request.