Develop asynchronous SCA clients

We can create clients that use Service Component Architecture (SCA) OASIS specifications to run asynchronously.

To learn about asynchronous invocations of SCA services, see the SCA OASIS Java Common Annotations and APIs specification. For a list of common annotations in SCA OASIS specifications, see http://docs.oasis-open.org/opencsa/sca-j/javadoc/index.html.

An SCA client can synchronously run an asynchronous service or asynchronously run a synchronous service. Typically, a client asynchronously runs an asynchronous service.

To develop an asynchronous SCA client, we can create three files:

• A Java client interface

• A Java client implementation that has an @Reference annotation

• An SCA OASIS composite

To dispatch client-side asynchronous requests, we can use a default SCA work manager.

A few limitations apply when using asynchronous interfaces from an SCA client:

• If the client application or its host server is stopped, responses to active asynchronous requests are lost, and are not delivered when the application is restarted.

• Because the SCA container invokes an asynchronous request from a separate thread, the client must not modify any arguments passed to the request until after it receives the response.

• Asynchronous invocation is not supported with services obtained using the org.oasisopen.sca.client.SCAClientFactory interface.

• A client can synchronously invoke an asynchronous service. The SCA container waits for up to 120 seconds for a response from the asynchronous service.

1. Create an asynchronous client interface.

   We can derive an interface from the business interface between the client and the service. For example, suppose that the service has the following business interface:

   package broker;
   public interface StockQuote {
   float getPrice(String symbol) throws UnknownSymbolException;
   }

   Copy the business interface and modify it to create an equivalent asynchronous client interface:

   package broker.client;
   import broker.UnknownSymbolException;
   import java.util.concurrent.Future;
   import javax.xml.ws.AsyncHandler;
   import javax.xml.ws.Response;
   public interface StockQuote {
       float getPrice(String symbol) throws UnknownSymbolException;
       Response<Float> getPriceAsync(String symbol);
       Future<?>getPriceAsync(String symbol, AsyncHandler<Float> callback);
   }

   An asynchronous client interface is a contract between the client and the SCA container. It is not used by the service.

   An asynchronous client interface has additional methods to support polling or callback delivery. Derive the polling method from its equivalent method in the business interface as follows:

   • Append the characters Async to the method name.

   • Change the return type to javax.xml.ws.Response.

   Derive the callback method from its equivalent method in the business interface as follows:

   • Append the characters Async to the method name.

   • Change the return type to java.util.concurrent.Future.

   • Add a javax.xml.ws.AsyncHandler argument which is typed by the return type of the original method.

2. Create the asynchronous client implementation.

   For example, create an implementation that uses the callback interface:

   package broker.client;
   import broker.UnknownSymbolException;
   import java.util.concurrent.ExecutionException;
   import javax.xml.ws.AsyncHandler;
   import javax.xml.ws.Response;
   import org.oasisopen.sca.annotation.Reference;
   public class StockQuoteClientImpl {
       @Reference
       public StockQuote quoteService;
   
       public void getStockPrice(String symbol)  {
           CallbackHandler callback = new CallbackHandler(symbol);
           quoteService.getPriceAsync(symbol, callback);
       }
   
       private class CallbackHandler implements AsyncHandler<Float>{
           private String symbol;
           public CallbackHandler(String symbol) {
               this.symbol = symbol;
           }
          public void handleResponse(Response<Float>arg0) {
              try {
                  Float price = arg0.get();
                  // Process the response            } catch (ExecutionException e) {
                 if (e.getCause() instanceof UnknownSymbolException) {
                     // Process the exception
                 }
              } catch (Throwable t) {
                  // Process the exception
              }
       }
   }

3. Create a composite file.

   For example, create an SCA OASIS composite that defines an implementation.java component which uses the implementation StockQuoteClientImpl class:

   <?xml version="1.0" encoding="UTF-8"?>
   <composite xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912"
              targetNamespace="http://www.example.com" name="StockQuoteClientComposite">
       <component name="StockQuoteClientComponent">
           <implementation.java class="broker.client.StockQuoteClientImpl"/>
       </component> 
   </composite>

   Asynchronous clients must use the binding.sca binding type because it is the only binding that supports asynchronous invocation. However, binding.sca is the default binding so we do not need to include it in the composite file.

4. Configure the default SCA work manager.

   The SCA container uses the default SCA work manager to dispatch client-side asynchronous requests. See Configuring the default SCA Work manager for the SCA layer.

What to do next

Deploy the SCA client and service in a business-level application.

Related tasks

Configure the default SCA Work manager for the SCA layer

Develop asynchronous SCA services and clients

Develop asynchronous SCA services

Configure the SCA default binding

Create SCA business-level applications

Specifications and API documentation