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

Here's an updated proposal, containing
the 4 changes discussed on last week's call.

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. 

For SCA reference interfaces defined using interface.java, the Java interface
MAY contain the 
additional client-side asynchronous polling and callback methods defined
by JAX-WS.
For SCA service interfaces defined using
interface.java, the Java interface MUST NOT contain
these methods.  If these methods
are present, SCA Runtimes MUST NOT include them in the
SCA reference interface as defined by
the Assembly specification.  These methods are 
recognized as follows. 

For each method M in the interface, if another method P in the interface
has 
   a. a method name that is M's method name with the characters "Async"
appended, and 
   b. the same parameter signature as M, and 
   c. a return type of Response<R> where R is the return type
of M 
  then P is a JAX-WS polling method that isn't part of the SCA interface
contract. 
 
For each method M in the interface, if another method C in the interface
has 
   a. a method name that is M's method name with the characters "Async"
appended, and 
   b. a parameter signature that is M's parameter signature with an
additional final parameter of type AsyncHandler<R> where R is the
return type of M, and 
   c. a return type of Future<?> 
  then C is a JAX-WS callback method that isn't 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); 
} 

SCA runtimes MUST support the use of the JAX-WS client asynchronous model.
In the above example, if the client implementation uses the asynchronous
form of 
the interface, the two 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

Simon Nash/UK/IBM@IBMGB

15/05/2008 12:08

To	"OASIS Java" <sca-j@lists.oasis-open.org>
cc
Subject	Re: [sca-j] ISSUE 23 - Asynchronous Client interface to Synchronous Service not well described in Java Common Annotations & APIs Specification

I thought the discussion of this on last week's call was very useful.  Based
on the views expressed, I am amending the proposal so that the special
treatment of these JAX-WS async methods applies to reference interfaces
only and not to service interfaces.  The following revised proposal
reflects this change. 

    Simon 

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. 

For SCA reference 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 MUST NOT be considered part of the SCA interface contract.
 These methods are 
recognized as follows. 

For each method M in the interface, if another method P in the interface
has 
   a. a method name that is M's method name with the characters "Async"
appended 
   b. the same parameter signature as M 
   c. a return type of Response<R> where R is the return type
of M 
  then P is a JAX-WS polling method that isn't part of the SCA interface
contract. 
 
For each method M in the interface, if another method C in the interface
has 
   a. a method name that is M's method name with the characters "Async"
appended 
   b. a parameter signature that is M's parameter signature with an
additional final parameter of type AsyncHandler<R> where R is the
return type of M 
   c. a return type of Future<?> 
  then C is a JAX-WS callback method that isn't 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); 
} 

SCA runtimes MUST support the use of the JAX-WS client asynchronous model.
In the above example, if the client implementation uses the asynchronous
form of 
the interface, the two 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

Simon Nash/UK/IBM@IBMGB

10/04/2008 16:58

To	"OASIS Java" <sca-j@lists.oasis-open.org>
cc
Subject	Re: [sca-j] ISSUE 23 - Asynchronous Client interface to Synchronous Service not well described in Java Common Annotations & APIs Specification

Here's an updated version based on the discussion on last week's call.

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. 

For SCA service and reference 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 MUST NOT be considered part of the SCA interface contract.
 These methods are 
recognized as follows. 

For each method M in the interface, if another method P in the interface
has 
   a. a method name that is M's method name with the characters "Async"
appended 
   b. the same parameter signature as M 
   c. a return type of Response<R> where R is the return type
of M 
  then P is a JAX-WS polling method that isn't part of the SCA interface
contract. 
 
For each method M in the interface, if another method C in the interface
has 
   a. a method name that is M's method name with the characters "Async"
appended 
   b. a parameter signature that is M's parameter signature with an
additional final parameter of type AsyncHandler<R> where R is the
return type of M 
   c. a return type of Future<?> 
  then C is a JAX-WS callback method that isn't 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); 
} 

SCA runtimes MUST support the use of the JAX-WS client asynchronous model.
In the above example, if the client implementation uses the asynchronous
form of 
the interface, the two 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

Simon Nash/UK/IBM

03/04/2008 12:16

To	"OASIS Java" <sca-j@lists.oasis-open.org>
cc
Subject	Re: [sca-j] ISSUE 23 - Asynchronous Client interface to Synchronous Service not well described in Java Common Annotations & APIs SpecificationLink

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

---

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

---

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