Asynchronous handling of Long Running Service Operations

7.3.1SCA Asynchronous Service Interface

As an example, for a WSDL portType with a single operation "getPrice" with a String request parameter and a float response, the synchronous Java interface mapping appears in snippet 7-1:

// synchronous mapping

public interface StockQuote {

float getPrice(String ticker);

}

Snippet 7-1: Example synchronous Java interface mapping

The JAX-WS client asynchronous API for the same portType adds two asynchronous forms for each synchronous method, as shown in snippet 7-2:

// asynchronous mapping

public interface StockQuote {

float getPrice(String ticker);

Response getPriceAsync(String ticker);

Future getPriceAsync(String ticker, AsyncHandler);

}

Snippet 7-2: Example JAX-WS client asynchronous Java interface mapping

The SCA Asynchronous Service interface has a single method similar to the final one in the asynchronous client interface, as shown in snippet 7-2:

// asynchronous mapping

@Requires("sca:asyncInvocation")

public interface StockQuote {

void getPriceAsync(String ticker, AsyncHandler);

}

Snippet 7-3: Example SCA asynchronous service Java interface mapping

The main characteristics of the SCA asynchronous mapping are:

• 
  there is a single method, with a name with the string "Async" appended to the operation name
  
• 
  it has a void return type
  
• 
  it has two input parameters, the first is the request message of the operation and the second is an AsyncHandler typed by the response message of the operation
  

The AsyncHandler parameter is the mechanism by which the service implementation sends back the response message resulting from the invocation of the service method. The AsyncHandler is serializable and it can be invoked once at any time after the invocation of the service method, either before or after the service method returns. This enables the service implementation to store the AsyncHandler in serialized form and release resources while waiting for the completion of whatever activities result from the processing of the initial invocation.

The AsyncHandler object is allocated by the SCA runtime/binding implementation and it is expected to contain whatever metadata is required to deliver the response message back to the client that invoked the service operation.

The SCA asynchronous service Java interface mapping of a WSDL request-response operation MUST appear as follows:

The interface is annotated with the "asyncInvocation" intent.

For each service operation in the WSDL, the Java interface contains an operation with

- a name which is the JAX-WS mapping of the WSDL operation name, with the suffix "Async" added

- a void return type

- a set of input parameter(s) which match the JAX-WS mapping of the input parameter(s) of the WSDL operation plus an additional last parameter which is an AsyncHandler object typed by the JAX-WS mapping of the output parameter of the WSDL operation, where AsyncHandler is the type defined in the JAX-WS specification.
[JCA60002]

An SCA Runtime MUST support the use of the SCA asynchronous service interface for the interface of an SCA service. [JCA60003].

The AsyncHandler object passed in as a parameter to a method of a service implementation using the SCA asynchronous service Java interface can be invoked once only through its handleResponse method to return the response resulting from the service method invocation. If the SCA asynchronous service interface AsyncHandler handleResponse method is invoked more than once, the SCA runtime MUST throw an IllegalStateException. [JCA60004]

For the purposes of matching interfaces (when wiring between a reference and a service, or when using an implementation class by a component), an interface which has one or more methods which follow the SCA asynchronous service pattern MUST be treated as if those methods are mapped as the equivalent synchronous methods, as follows:

Asynchronous service methods are characterized by:

1. 
   void return type
   
2. 
   a method name with the suffix "Async"
   
3. 
   a last input parameter with a type of AsyncHandler