Issue 127: Proposed modified proposal

[Anish Karmarkar <Anish.Karmarkar@oracle.com>]

[cc'ing Chen, our JAX-WS expert, who wrote this proposal]

[Note: In addition, to suggesting a different interface, the proposal 
below also tries to rationalize what SCA-J does with what would make 
sense from a JAX-WS.next POV.]


Issue 127 proposal [1] [2] reuses the javax.xml.ws.AsyncHandler 
interface, which was originally designed for JAX-WS client-side async, 
for the server-side programming model. The java doc for AsyncHandler 
says: "The AsyncHandler interface is implemented by clients that wish to 
receive callback notification of the completion of service endpoint 
operations invoked asynchronously."

This is little bit different than the use case that we are trying to 
solve on the server-side. While it makes sense to try and reuse existing 
interfaces, in this case we would like to suggest creating a new 
interface that is more appropriate for the use case.

The example in the proposal, is incorrect in that the handleResponse() 
of the AsyncHandler<T> interface is handleResponse(Response<T> res) 
instead of handleResponse(T res). The application code must use an 
instance of Response<Float> object, instead of just Float.

We believe this is awkward in that it forces the application developer 
to implement the javax.xml.ws.Response<T> interface and the methods 
required by its super interface java.util.concurrent.Future<T> in order 
to satisfy the AsyncHandler. Instead of reusing the client-side 
AsyncHandler on the server-side programming model, we would like to 
propose a new ResponseDispatch interface for this usage:

public interface StockQuote {
   void getPriceAsync(String ticker, ResponseDispatch<Float> dis);
}

The ResponseDispatch object is the mechanism by which the service 
implementation sends back the response message resulting from the 
invocation of the service method. The ResponseDispatch 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 ResponseDispatch in 
serialized form and release resources while waiting for the completion 
of whatever activities result from the processing of the initial invocation.

The ResponseDispatch object is allocated by JAX-WS container 
implementation and is expected to contain whatever metadata is required 
to deliver the response message back to the client that invoked the 
service operation. The method using ResponseDispatch must have a void 
return, and must not use javax.xml.ws.Holder as parameter.
The ResponseDispatch also has the API to send faults; the application 
may chose to use a data-bound Service Exception (annotated with 
@WebFault) or SOAPFaultException for arbitrary fault.

public interface ResponseDispatch<T> {
   void sendResponse(T res);
   void sendFault(Throwable e);
   Map<String, Object> getContext();

}

A long running async method MUST use the sendFault method to send faults 
back to the client, instead of throwing the service exception during the 
invocation of the async method. Throwing an exception during the 
invocation of the business method should be interpreted as a system 
error, and the container may be configured to re-deliver the request if 
the container implementation supports such a feature; the request 
re-delivering is implementation specific and is not specified in this 
proposal.

The Service Exceptions for an async method should not be declared using 
the throw clause. The new new @AsyncFault annotation is introduced for 
async method to describe Service Exceptions:

//This example is borrowed from the presentation at [2]
@AsyncFault({ServiceBusinessException.class,
              ServiceRuntimeException.class})
public void makeReservation(ReservationRequest req,
                             ResponseDispatch<ConfirmationData> res);

The ResponseDispatch will also enable an asynchronous style JAX-WS 
service Provider programming model if directly processing raw XML is 
preferred.

public interface AsyncProvider<T> {
   void invoke(T request, ResponseDispatch<T> res);
}

For example, a AsyncProvider implementation can chose to parameterize 
with SOAPMessage:

public class MyAsyncServiceProvider implements AsyncProvider<SOAPMessage> {
   public void invoke(SOAPMessage request,
                      ResponseDispatch<SOAPMessage> dispatch) {
     store(request, dispatch);
     ...
   }
}



Comments?

-Anish
--

[1] http://lists.oasis-open.org/archives/sca-j/200911/bin00000.bin
[2] 
http://www.oasis-open.org/apps/org/workgroup/sca-j/download.php/35238/sca-javacaa-1.1-spec-cd03-rev1_Issue127b.pdf