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

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"
<> 

31/01/2008 16:14

To

"OASIS Java" <>

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:]

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 

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