ISSUE 23 - Asynchronous Client interface to Synchronous Service not well described in Java Common Annotations & APIs Specification

http://www.osoa.org/jira/browse/JAVA-23

Von: Mike Edwards 
[mailto:] 
Gesendet: Mittwoch, 2. Januar 2008 
12:44
An: OASIS Java
Betreff: [sca-j] [NEW ISSUE] 
Asynchronous Client interface to Synchronous Service not well described 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