You can create clients that use Service Component Architecture
(SCA) OASIS specifications to run asynchronously.
Before you begin
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.
About this task
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, you 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, you 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.
Procedure
- Create an asynchronous client interface.
You
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.
- 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
}
}
}
- 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 you do not need to include it in the composite
file.
- 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.