W3C home > Mailing lists > Public > www-archive@w3.org > April 2005

[Fwd: Primer RPC Section]

From: David Booth <dbooth@w3.org>
Date: Sun, 17 Apr 2005 13:08:41 -0400
To: www-archive@w3.org
Message-Id: <1113757721.13968.3591.camel@nc6000.w3.org>

-----Forwarded Message-----
From: "Yalcinalp, Umit" <umit.yalcinalp@sap.com>
To: David Booth <dbooth@w3.org>, "Liu, Kevin" <kevin.liu@sap.com>
Cc: Roberto Chinnici <Roberto.Chinnici@Sun.COM>
Subject: Primer RPC Section
Date: Fri, 01 Apr 2005 00:03:36 +0200


Folks, 

The RPC primer section is included. I leave you the joy of converting
the section to xml ;-) (&AII is retained for simplification)

I am CC:ing Roberto as I used Java method signature as an example. Since
JAX RPC 2.0 is still an early draft, I used JAX RPC 1.1 as a reference
for illustration for type mapping. Roberto, let me know if you see any
issues with this. 

Comments are welcome. 

--umit
<<RPCPrimer.txt>> 

------------------------------------------------------------------

RPC Style in WSDL 2.0 is designed to facilitate programming language
bindings to WSDL constructs. The purpose of the RPC style is to
provide the necessary conditions in order to map a WSDL interface
operation to a method signature, such as a method signature in
Java(TM), C# or other languages.

An interface operation designated by In-Out MEP can be mapped easily
to a method signature in the target language which corresponds to an
RPC call by following the constraints that are specified in Section
3.1 [1]. These rules define the relationship between XML Schema
elements that constitute the input and ouput messages. Since the
interface operation designates a single method signature, the
relationship between the input and output elements is significant.  In
order to provide a meaningful signature for language bindings,
parameters in a method signature that are inputs, outputs, or those
that are both input and outputs as well as return value(s) in a
signature should be easily determinable. The rules in Section 3.1.1
determine how the content of the input and output elements map to the
parameters. For example, a local element that occurs both as the first
child of the input element and the output element designates an in-out
parameter for the method signature. Elements that occur only as
local element children of the input element are considered to
represent input parameters of the method signature. Similarly, 
elements that occur only as local element children of the output
element represent output parameters.

It is possible to designate the full signature of the intended mapping
by using the wrpc:signature &AII. Its value designates how each child
of the input and output element is used in the signature with the
order specified in the value. 

The example below illustrates how RPC style may be used to designate a
signature. This example is a modified version of the reservation
service.  We will modify the types in Section 2.3 that defines
messages for checking availability in a hotel reservation as well as
the the reservation interface from Section 2.4 as follows:

<!-- WSDL 2.0 snippet -->
  <types>
 
      <xs:element name="checkAvailability">
          <xs:complexType>
              <xs:sequence>      
                  <xs:element  name="checkInDate" type="xs:date"/>      
                  <xs:element  name="checkOutDate" type="xs:date"/>     
                  <xs:element  name="roomType" type="xs:string"/>      
              </xs:sequence>
          </xs:complexType>
      </xs:element>

      <xs:element name="checkAvailabilityResponse">
           <xs:complexType>
               <xs:sequence>      
                  <xs:element  name="roomType" type="xs:string"/> 
                  <xs:element  name="rateType" type="xs:string"/>
                  <xs:element  name="rate" type="xs:double"/>      
              </xs:sequence>
          </xs:complexType>
      </xs:element>
      ....
  </types>
  
  <interface  name = "reservationInterface" >
   
    <operation name="checkAvailability" 
            pattern="http://www.w3.org/@@@@/@@/wsdl/in-out" 
            style="http://www.w3.org/@@@@/@@/wsdl/style/rpc"
            wrpc:signature=
              "checkInDate #in checkOutDate #in roomType #inout rateType
#out rate #return">
        <input messageLabel="In" 
              element="tns:checkAvailability" />
        <output messageLabel="Out" 
              element="tns:checkAvailabilityResponse" />

    </operation>
 
    ...
  </interface>


Note that the interface operation's name "checkAvailability" is the
same as the localPart of the input element's QName,
"tns:checkAvailability" as required. The name of the operation is
used as the name of the method in a language binding,
subject to further mapping restrictions specific to the target
programming language. In this case, the name of the method would be
"checkAvailability". 

The local children elements of the input element and output element
designate
the parameters and the return type for a method call. Note that the
elements checkInDate, checkOutDate are input parameters, however the
element roomType is an in-out parameter as it appears both as local
element child of input and output elements of the operation to
indicate that the reservation system may change the room type
requested based on the availability. 

The reservation service also indicates the rate type that the
reservation may be based on, such as "rack rate" that is provided as
an output value. The return value for the method is designated as the
"rate" element with the same semantics as in the previous examples in
this document.

Based on the value of the wrpc:signature &AII, the method signature
that would be obtained following the order of the parameters. A sample
mapping is provided below for Java language. We used JAX RPC 1.1 [2]
for type mapping rules for mapping simple types to Java types and
designated inout and output parameters by using Holder classes.

public interface reservationInterface extends Remote{
    double checkAvailability(java.util.calendar checkInDate,
java.util.calendar checkOutDate,
                  StringHolder roomType, StringHolder rateType) throws
RemoteException ; 
    ....
}

Programming languages may further specify how faults are mapped to
langauage constructs and their scopes, such as Exceptions, but they
are not specific to RPC style.

References:

[1] Web Services Description Language (WSDL) Version 2.0 Part 2:
Adjuncts
[2] Java(TM) API for XML-based RPC JAX-RPC 1.1
(http://java.sun.com/xml/downloads/jaxrpc.html)

-- 
David Booth <dbooth@w3.org>
Received on Sunday, 17 April 2005 17:08:48 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Wednesday, 7 November 2012 14:17:51 GMT