[NEW ISSUE] Asynchronous Client interface to Synchronous Service not welldescribed in Java Common Annotations & APIs Specification

RAISER:   Mike Edwards

TARGET: Java Common Annotations &
APIs Specification

DESCRIPTION:

(Section and line numbers here relate
to the OASIS TC working draft sca-javacaa-draft-20070926.doc)

The Java Common Annotation and APIs
specification is causing confusion about the facilities provided

to support asynchronous clients to synchronous
services - there needs to be a better explanation about

what SCA supports.

The first section that deals with this
is section 6.1 on @OneWay.  It makes the following statement in lines

215 - 218:

"SCA does not currently define
a mechanism for making non-blocking calls to methods that return values

or are declared to throw exceptions.
It is recommended that service designers define one-way methods 

as often as possible, in order to give
the greatest degree of binding flexibility to deployers."

The first sentence here is in fact in
contradiction with section 9 on "WSDL to Java and Java to WSDL"

The JAX-WS mapping has a full set of
capabilities for client asynchronous invocation of a synchronous

service.  Section 9 alludes to
the need for some examples of the asynchronous invocation in line 1523:

"Note: This specification needs
more examples and discussion of how JAX-WS's client asynchronous model
is used." 

PROPOSAL:

The following is a multipart proposal
for changes and additions to the specification to deal with the issue:

1) Alter the text in Section 6.1 between
lines 215 - 218, to read as follows:

"For a Java client to make a non-blocking
call to methods that either return values or which throw exceptions,

a Java client MUST use the JAX-WS asychronous
client API model that is described in section 9. 

It is recommended that service designers
define one-way methods 

as often as possible, in order to give
the greatest degree of binding flexibility to deployers."

2) Add the following text as a new Section
9.1:

"9.1 JAX-WS Client Asynchronous
API for a synchronous service

The JAX-WS specification defines a mapping
of a synchronous service invocation which provides a client

application with a means of invoking
that service asynchronously, so that the client can invoke a service

operation and proceed to do other work
without waiting for the service operation to complete its processing.  

The client application can retrieve
the results of the service either through a polling mechanism or via a

callback method which is invoked when
the operation completes.

As an example, if the client code for
a synchronous service invocation is like this:

      OrderResponse placeOrder(
OrderRequest oRequest );

the equivalent asynchronous service
invocation is like this:

      Future<?>
placeOrderAsync( OrderRequest oRequest,

           AsyncHandler<OrderResponse>
responseHandler );

and the asynchronous response to the
invocation is sent back to the client via an asynchronous response handler
declared as follows:

class OrderResponseHandler implements
AsyncHandler<OrderResponse> {

   public void handleResponse(
Response<OrderResponse> theResponse ){

      OrderResponse orderResponse
= theResponse.get();

   }

}

Polling is provided via the Future object
returned from the asycnhronous invocation."

Yours,  Mike.

Strategist - Emerging Technologies, SCA & SDO.

Co Chair OASIS SCA Assembly TC.

IBM Hursley Park, Mail Point 146, Winchester, SO21 2JN, Great Britain.

Phone & FAX: +44-1962-818014    Mobile: +44-7802-467431  

Email:  

Unless stated otherwise above:

IBM United Kingdom Limited - Registered in England and Wales with number
741598. 

Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6
3AU