Re: [sca-j] ISSUE 23 - Asynchronous Client interface to Synchronous Servicenot well described in Java Common Annotations & APIs Specification

[Simon Nash <NASH@uk.ibm.com>]

I took an action to propose different
wording for Mike's item 2.  Here's my proposal:

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. 

SCA runtimes MUST support the use of
this JAX-WS client asynchronous model.  For SCA service interfaces
defined using interface.java, the Java
interface MAY contain the additional client-side asynchronous polling
and callback methods defined by JAX-WS.
 If these methods are present, they are not considered part of
the SCA interface contract.

As an example, an interface may be defined
in WSDL as follows:

<!-- WSDL extract -->
<message name="getPrice">
   <part name="ticker" type="xsd:string"/>
</message>

<message name="getPriceResponse">
   <part name="price" type="xsd:float"/>
</message>

<portType name="StockQuote">
   <operation name="getPrice">
      <input message="tns:getPrice"/>
      <output message="tns:getPriceResponse"/>
   </operation>
</portType>

The JAX-WS asynchronous mapping will
produce the following Java interface:

// asynchronous mapping
@WebService
public interface StockQuote {
   float getPrice(String ticker);
   Response<Float> getPriceAsync(String
ticker);
   Future<?> getPriceAsync(String
ticker, AsyncHandler<Float>);
}

For SCA interface definition purposes,
this is treated as equivalent to the following:

// synchronous mapping
@WebService
public interface StockQuote {
   float getPrice(String ticker);
}

If the client implementation uses the
asynchronous form of the interface, the additional
getPriceAsync() methods can be used
for polling and callbacks as defined by the
JAX-WS specification."

    Simon 

Simon C. Nash, IBM Distinguished Engineer
Member of the IBM Academy of Technology
Tel. +44-1962-815156  Fax +44-1962-818999

"Barack, Ron" <ron.barack@sap.com>

31/01/2008 16:14

To	"OASIS Java" <sca-j@lists.oasis-open.org>
cc
Subject	[sca-j] 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:mike_edwards@uk.ibm.com]
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:  mike_edwards@uk.ibm.com

---

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

---

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