RE: Application Data Feature and related stuff

Glen,

I have one comment:

> As a SOAP sender, if the property
> http://www.w3.org/@@@@/@@/features/AD/data has a 
> value then each of the top-level child element 
> information items in the value SHOULD [ed:
> MUST?] be turned into a SOAP header.  The elements 
> are serialized according to their schemas, which 
> might include the SOAP "mustUnderstand" or "role" 
> attributes, which will have the usual meaning
> in the resultant headers.

> <attribute xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
>    ref="soap:mustUnderstand"
>    fixed="true"/>

This is SOAP 12 binding specific information at the abstract level,
<types/>. I am wondering if we could avoid that. Embedding binding specific
info at the abstract level takes away re-usability. In this specific case, I
would like to re-use it for SOAP 11 binding.

Asir

-----Original Message-----
From: www-ws-desc-request@w3.org [mailto:www-ws-desc-request@w3.org] On
Behalf Of Glen Daniels
Sent: Wednesday, June 23, 2004 1:05 PM
To: WS-Description WG
Subject: Application Data Feature and related stuff




WSDL'ers:

The following is the latest version of the application data feature,
associated SOAP module, and HTTP binding feature that Dave, Yaron and I
have been working on.  We believe we have come to substantial agreement
about the structure and mechanism here, but there are still a few loose
ends we'd like to sort out with the group (see the ed notes below).

Comments appreciated, and apologies for taking so long to get this out.

Thanks,
--Glen


= Application Data (AD) Feature =

This feature is identified with the URI
http://www.w3.org/@@@@/@@/features/AD

== Operation ==

This feature exists in order to enable the description of
application-defined additional data declarations outside of the normal
data channel (e.g. the SOAP body). The senders takes the value of the
property http://www.w3.org/@@@@/@@/features/AD/data, which is defined
below, and passes it to the receiver in a manner to be defined by the
particular bindings/modules implementing this specification.

= AD/data Property =

This property is identified with the URI
http://www.w3.org/@@@@/@@/features/AD/data.

== Description ==

The data property consists of a sequence of elements, each of which
represents an individual piece of application data.  Implementations of
this feature must ensure that the runtime value of this property is
correctly transferred from the sender to the receiver.

Here is an example of using the data property in a WSDL:

<types>
 <schema targetNamespace="http://foo"
         xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns="http://www.w3.org/2001/XMLSchema">
  <import namespace="http://www.w3.org/2003/05/soap-envelope"/>
  <!-- Define the data type we'll use later -->
  <complexType name="myDataType">
   <sequence>

    <!-- These elements are our data -->
    <element name="isGoldClubMember">
     <complexType>
      <simpleContent>
       <extension base="xs:boolean"/>
       <attribute xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
                  ref="soap:mustUnderstand"
                  fixed="true"/>
      </simpleContent>
     </complexType>
    </element>

    <element name="promotionalCode"
             type="xs:string"
             minOccurs="0"/>

   </sequence>
  </complexType>
 </schema>
</types>
<interface name="customerService">
 <operation name="reserveCar">
  <input element="myNS:reserveCarRequest">
   <property uri="http://www.w3.org/@@@@/@@/features/AD/data">
    <constraint xmlns:foo="http://foo">
     foo:myDataType
    </constraint>
   </property>
  </input>
 </operation>
</interface>

This example defines two pieces of application data, and associates them
with the input message of the "reserveCar" operation.  Notice that the
"promotionalCode" element is optional (minOccurs="0"), and that the
"isGoldClubMember" element has fixed the value of the SOAP 1.2
"mustUnderstand" element to "true".



= Application Data Module =

This module is identified with the URI
http://www.w3.org/@@@@/@@/modules/AD

== Features Implemented ==

This module implements the feature
http://www.w3.org/@@@@/@@/features/AD.

== Operation ==

This module specifies how to transmit "out of band" application data, as
defined in the Application Data feature, as SOAP headers.

As a SOAP sender, if the property
http://www.w3.org/@@@@/@@/features/AD/data has a value then each of the
top-level child element information items in the value SHOULD [ed:
MUST?] be turned into a SOAP header.  The elements are serialized
according to their schemas, which might include the SOAP
"mustUnderstand" or "role" attributes, which will have the usual meaning
in the resultant headers.  SOAP senders SHOULD also add an additional
header, with namespace "http://www.w3.org/@@@@/@@/modules/AD" and local
name "dataHeaders" - this header contains a list of element QNames, one
for each application data header created in the first step.

It is the responsibility of the receiving node to determine which, if
any, SOAP headers will populate the
http://www.w3.org/@@@@/@@/features/AD/data property.  Typically this
will be accomplished via using some metadata, such as an understanding
of a <constraint> specified in WSDL, or out-of-band agreements.  If the
"dataHeaders" SOAP header (described above) is present, the QNames
inside that header indicate which other headers are application data.
The contents of each SOAP header identified as application data will be
placed in a child element of the data property [ed: should we define a
particular "wrapper" element here as the top level one?].


=== The following gets added to the HTTP binding === 

== Features Implemented ==

The HTTP binding implements the feature
http://www.w3.org/@@@@/@@/features/AD.

= Operation = 

This section specifies how to transmit "out of band" application data,
defined in the Application Data feature, as HTTP headers.

As an HTTP sender, if the property
http://www.w3.org/@@@@/@@/features/AD/data has a value then each of the
top-level child element information items indicates a possible element
information item that SHOULD [ed:
MUST?] be turned into an HTTP header.  The http header name is
serialized from the element information item local name.  The http
header content is serialized from the element information item value.
The data elements should only be "xs:string" type, including xs:anyURI.
Any attributes on data elements are ignored.
Any complex data types are ignored.  Where the element information item
contains content that cannot be directly encoded per the HTTP
specification, it MUST be escaped.

It is the responsibility of the receiving node to determine which, if
any, HTTP headers will populate the
http://www.w3.org/@@@@/@@/features/AD/data property.  Typically this
will be accomplished via using some metadata, such as an understanding
of a <constraint> specified in WSDL, or out-of-band agreements.  The
contents of each such HTTP header will be placed in a child element of
the data property [should we define a particular "wrapper" element here
as the top level one?].  Each child element information item is
generated by using the http header name as the element information item
local name [ed: should we define a particular namespace?] and the http
header value as the element information item value.  Where the HTTP
header contains content that cannot be directly encoded in the element
information item, it MUST be escaped.

[ed: any discussion about escaping rules?]

Received on Thursday, 24 June 2004 08:57:00 UTC