RE: Headers proposal V 1.1 (compatible with V1.0) from Tom Jordahl on 2005-01-21 (www-ws-desc@w3.org from January 2005)

From: Tom Jordahl <tomj@macromedia.com>
Date: Thu, 20 Jan 2005 21:48:06 -0500
To: David Orchard <dorchard@bea.com>, www-ws-desc@w3.org
Message-ID: <CB1FF0A474AEA84EA0206D5B05F6A4CB0C1B180D@pop-newton.allaire.com>
This paragraph needs correction:

 

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/Header/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/Header" and local name "dataHeaders" -
this header contains a list of element QNames, one for each application data
header created in the first step.

 

 

Should be changed to:

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/Header/data
<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" attribute,
which will have the usual meaning in the resultant headers. 

 

 

Tom Jordahl
Macromedia Server Development 

  _____  

From: www-ws-desc-request@w3.org [mailto:www-ws-desc-request@w3.org] On
Behalf Of David Orchard
Sent: Thursday, January 20, 2005 9:37 PM
To: www-ws-desc@w3.org
Subject: Headers proposal V 1.1 (compatible with V1.0)

 

= Header Extension =

 

This extension is a feature is identified with the URI

http://www.w3.org/@@@@/@@/features/Header

 

== 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 take the value of the property
http://www.w3.org/@@@@/@@/features/Header/data
<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.

 

= Header data Property =

 

This property is identified with the URI
http://www.w3.org/@@@@/@@/features/Header/data
<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"
headerWrapperType="foo:myDataType"/>

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

 

 

= Header SOAP Module =

 

This module is identified with the URI

http://www.w3.org/@@@@/@@/modules/Header
<http://www.w3.org/@@@@/@@/modules/AD> 

 

== Features Implemented ==

 

This module implements the feature

http://www.w3.org/@@@@/@@/features/Header
<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/Header/data
<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/Header
<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/Header/data
<http://www.w3.org/@@@@/@@/features/AD/data>  property.  Typically this will
be accomplished via using some metadata, such as an understanding of the
headerWrapperType specified in WSDL, or out-of-band agreements.  If any SOAP
header blocks (described above) have an "isApplicationHeader" is present,
then that header block is 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 SOAP binding === 

 

The soap binding implements the Header Module.  By default, the Header
module is enabled.  The Header module is turned off by setting the
"disableHeaderModule" to true, ie

 

<soap:binding name="StockQuoteSOAP" interface="StockQuote"
disableHeaderModule="true">

 

 

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

 

== Features Implemented ==

 

The HTTP binding implements the feature

http://www.w3.org/@@@@/@@/features/Header
<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.  The HTTP binding
implements this feature.  By default, the is enabled.

 

As an HTTP sender, if the property

http://www.w3.org/@@@@/@@/features/Header/data
<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/Header/data
<http://www.w3.org/@@@@/@@/features/AD/data>  property.  Typically this will
be accomplished via using some metadata, such as an understanding of the
headerWrapperType 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.

 

The Header module is turned off by setting the "disableHeaderFeature" to
true.

 

Issue: compose http and soap headers? 

 

Cheers,

Dave (and Glenn?)
Received on Friday, 21 January 2005 02:48:42 UTC