- From: David Orchard <dorchard@bea.com>
- Date: Thu, 20 Jan 2005 21:24:16 -0800
- To: <www-ws-desc@w3.org>
- Message-ID: <32D5845A745BFB429CBDBADA57CD41AF0D100248@ussjex01.amer.bea.com>
Another cut of Header proposal.
This removes the text from Part 2 and inserts into Part 1 and Part 3,
whilst retaining f&p underneath.
= New Part 1 section (2.16?) 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 and the Message
Reference shorthand.
<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".
= Addition to 2.5.1 =
{header content model} OPTIONAL. A wsdls:token with one of the values
#any, #none, or #element. A value of #any indicates that the header
content is any single element. A value of #none indicates there is no
header content. A value of #element indicates that the header consists
of a elements contained within the content model referenced by the
{headerWrapperType} property.
{headerWrapperType} OPTIONAL. A reference to an XML element declaration
in the {element declarations} property of 2.1.1 The Definitions
Component
<http://www.w3.org/TR/2004/WD-wsdl20-20040803/#Definitions_details#Defin
itions_details> . The content of this element represents headers of the
message. When the {message content model} property has the value #any or
#none the {element} property MUST be empty
= Addition to 2.5.2 =
headerWrapperType="union of xs:QName, xs:Token"?
o An OPTIONAL headerWrapperType attribute information item as
described below in 2.5.2.2 headerWrapperType attribute information item
with input, or output [owner]
<http://www.w3.org/TR/2004/WD-wsdl20-20040803/#MessageReference_element_
attribute#MessageReference_element_attribute> .
2.5.2.3 headerWrapperType attribute information item with input , or
output [owner]
The headerWrapperType attribute information item has the following
Infoset properties:
* A [local name] of headerWrapperType .
* A [namespace name] which has no value.
The type of the headerWrapperType attribute information item is a union
of xs:QName and xs:Token where the allowed token values are #any or
#none.
=== Addition to Part 3 part 2 ===
The SOAP binding implements the Header SOAP Module:
http://www.w3.org/@@@@/@@/modules/Header
<http://www.w3.org/@@@@/@@/modules/AD> . By default, the Header module
is enabled. The Header module is turned off by setting the
"disableHeaderModule" to true.
In the example
<binding name="xs:NCName" interface="xs:QName"?
type=http://www.w3.org/2004/08/wsdl/soap12
<http://www.w3.org/2004/08/wsdl/soap12>
disableHeaderModule="xs:boolean"?
= New 2.9 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" attribute, which will have the usual meaning in the
resultant headers.
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?].
2.5 Disabling the Default SOAP Header Module
2.5.1 Description
This binding specification allows the user to disable the Header SOAP
Module http://www.w3.org/@@@@/@@/modules/Header
<http://www.w3.org/@@@@/@@/modules/AD> ..
2.5.2 Relationship to WSDL Component Model
The disableHeaderModule is a syntactic convenience and does not affect
the underlying component model.
2.5.3 XML Representation
<definitions >
<binding name="xs:NCName" interface="xs:QName"? type="xs:anyURI"
wsoap:protocol="xs:anyURI"
wsoap:disableHeaderModule="xs:boolean"?/> ...
</binding>
</definitions>
The XML representation for the disable Header Module is an OPTIONAL
attribute information item with the following Infoset properties:
* A [local name] of disableHeaderModule
* A [namespace name] of "http://www.w3.org/2004/08/wsdl/soap12"
== Add to Section 3 ==
The HTTP binding implements the feature
http://www.w3.org/@@@@/@@/features/Header
<http://www.w3.org/@@@@/@@/features/AD> .
= New content for section 3.3 =
- Header Construction: When formulating the HTTP message to be
transmitted, the contents of the headers (i.e. the contents of the HTTP
headers) MUST at least be what is defined by the corresponding Header
Feature. if the value of the {header content model}
<http://www.w3.org/TR/2004/WD-wsdl20-20040803#MessageReference_details>
property is #any then the header MAY be any one XML element. If the
value is #none then there is no impact on the headers. Finally if the
value is #element then the headers will be the elements in the content
model of element information item identified by the {wrapperHeaderType}
<http://www.w3.org/TR/2004/WD-wsdl20-20040803#MessageReference_details>
property.
= New Section 3.12 HTTP use of Header feature
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.
3.6 Disabling the Header Header feature
3.6.1 Description
This binding specification allows the user to disable the Header Feature
http://www.w3.org/@@@@/@@/features/Header
<http://www.w3.org/@@@@/@@/features/AD> .
3.6.2 Relationship to WSDL Component Model
The disableHeaderFeature is a syntactic convenience and does not affect
the underlying component model.
3.6.3 XML Representation
<definitions >
<binding name="xs:NCName" interface="xs:QName"? type="xs:anyURI"
whttp:disableHeaderFeature="xs:boolean"?/> ...
</binding>
</definitions>
The XML representation for the disable Header Feature is an OPTIONAL
attribute information item with the following Infoset properties:
* A [local name] of disableHeaderFeature
* A [namespace name] of "http://www.w3.org/2004/08/wsdl/http"
Cheers,
Dave (and Glenn?)
Received on Friday, 21 January 2005 05:24:19 UTC