W3C home > Mailing lists > Public > www-ws-desc@w3.org > January 2005

Re: First Class Headers - Proposed Resolution for LC76d

From: Prasad Yendluri <pyendluri@webmethods.com>
Date: Wed, 26 Jan 2005 14:24:34 -0800
Message-ID: <41F818A2.6040800@webmethods.com>
To: www-ws-desc@w3.org, asirv@webmethods.com
CC: jeffsch@windows.microsoft.com
Hi Asir,

I echo the remarks of Jean-J and Kevin on simple and easy to follow 
nature of the proposal. It is pretty comprehensive as well.

As I reviewed, I came up with a few comments.

Regards, Prasad

General Comments:
-------------------

1. This proposal does not address if all headers that can be exchanged 
via input, output or fault messages in an interface (operations) MUST be 
declared. Or if this is only a subset of all the potential headers 
(including things that are added dynamically) that the definer of the 
interface chose to declare.

2. The  @required of the {header} component and the @disableHeaders at 
the {binding} component level are in total contradiction.

The "REQUIRED" @required on the {header} component is defined to be: 
"An xs:boolean. If the value of this property is true, then the Web 
Service consumer/client MUST use the Header that is identified by the 
{element declaration}."

Where as, the purpose of the disableHeadersDefault AII at the binding 
level is to "disable" header generation at the binding level.

So, if @required on a {header} component at the interface/operation 
level says the "header MUST be used", a binding can arbitrarily override 
that to ignore that (and even all) header(s)?

I am not sure that is desirable at all.

3. Somewhat related to the above. Headers concept is not native to many 
of the potential bindings; and the HTTP binding already identifies 
issues/difficulties with binding {header} components at the abstract 
level. Any proposal that introduces headers needs to speak to this 
aspect of, if bindings that have no concept of headers *can* be used 
with interfaces that specify {header} components and if so, a general 
guidance on how the header components can be bound would be helpful.

Specific Comments on individual parts:

Section (1) Introduce a NEW Header Component
---------------------------------------------------

4. In the proposal, the Header component is defined recursively  using 
the term header to define itself. 

"A Header Component describes an abstract piece of *header* that is 
associated with the exchange of messages between the communicating parties."

We need to fix this.

5. The {namespace name} on the header REQUIRED but no defaulting is 
defined. I believe we need to permit the use of elements declared 
locally in the default (local) namespace as headers. Perhaps that is the 
intent but that is not clear from the proposal.

6. {mustUnderstand} OPTIONAL. An xs:boolean. If the property is true, 
then the bindings that support expression of mandatory data should mark 
them as mandatory in an appropriate way.

Why is it a "should mark them as mandatory" and not a "must"? 
With this it seems a specific SOAP binding can choose not to mark the 
headers with "mustUnderstand=true" even when at the interface/operation 
level {header} components sets this attribute to true.
 
Section (4) Syntax Level Default Mechanism to Disable Header Construction
------------------------------------------------------------------------------

7. The proposal states, "disableHeaderDefault AII (at the binding 
component level) is a syntax level convenient mechanism and does not 
contribute anything to the component model."

Is that really so? Does it not specify the default value for this 
attribute for all sub-components unless explicitly overridden?

Also, I hope we would add some actual description of 
disableHeaderDefault AII is all about. The proposal is drafted in a form 
that can be inserted in the spec in appropriate sections, hence I ask.

Section (5) Mechanism to Disable Header Construction for the Binding 
Fault Component
----------------------------------------------------------------------------------
8. "{disable headers} OPTIONAL. An xs:boolean. If this property exists 
and is true, then header construction is turned off."

We need to be more specific here. Does turned off mean, the {header} 
components are not serialized at all or not serialized as headers? Can 
they go as some other piece of the serialized message?

Section (7) Add to SOAP Binding's Default Binding Rules
-----------------------------------------------------------
9. "Default value of the Binding Operation Component's {disable headers} 
property is false."

The  {operation} component in binding is not shown to have this AII 
(e.g. in section (6) of the proposal).

Section (8) Add to HTTP Binding's Default Binding Rules
-----------------------------------------------------------
10. "an Header component's {element} property in the {headers} property 
MUST be turned into HTTP header if possible."

Eliminate use of MUST and "if possible" in the same sentence above.

-------- Original Message --------
Subject: 	First Class Headers - Proposed Resolution for LC76d
Resent-Date: 	Mon, 24 Jan 2005 13:47:15 +0000
Resent-From: 	www-ws-desc@w3.org
Date: 	Mon, 24 Jan 2005 08:46:20 -0500
From: 	Asir Vedamuthu <asirv@webmethods.com>
To: 	'www-ws-desc@w3.org' <www-ws-desc@w3.org>
CC: 	'jeffsch@windows.microsoft.com' <jeffsch@windows.microsoft.com>


LC76d - http://www.w3.org/2002/ws/desc/4/lc-issues/#LC76d

#1: At the Melbourne F2F, I observed a simple majority to explore header 
proposals that are independent of the Features and Properties framework. 
This draft is one such mechanism. It accommodates SOAP 1.1, SOAP 1.2 and 
HTTP Bindings. AFAIK, this draft resolves all the sub issues raised by 
Jeffrey Schlimmer in LC76d.

The number two driving force behind this proposal is the desire for 
simplicity. I bet the user community will enthusiastically receive a 
product that simplifies their work and reduces their time to market.

This is the first draft. I made it as brief as possible. If there is 
sufficient interest, I will continue to produce newer versions that will 
accommodate your requirements and issues. At the least, this proposal 
will provide sufficient information to the WSDL Working Group to make an 
informed decision.

Comments, suggestions, corrections, thumbs up, thumbs down .. are 
greatly appreciated.

Regards,

Asir S Vedamuthu
asirv at webmethods dot com
http://www.webmethods.com/

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


  First Class Headers - Proposed Resolution for LC76d

Lets begin with a simple example. The following example shows the WSDL 
definition of a simple service providing stock quotes. This service 
supports a single operation called GetLastTradePrice, which is deployed 
using the SOAP 1.2 protocol over HTTP. I added 3 statements to turn on 
WS-Security header support. Again, just 3 statements - import schema 
statement, header in input message reference component and header in 
output message reference component.

<?xml version="1.0"?>
<wsdl:definitions name="StockQuote" xmlns:wsdl="http://www.w3.org/@@@@/@@/wsdl"
  targetNamespace="http://example.com/stockquote"
  xmlns:tns="http://example.com/stockquote"
  xmlns:wsoap="http://www.w3.org/@@@@/@@/wsdl/soap"
  xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
    
  <xs:import
   namespace="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
   schemaLocation="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"/>
     
  <wsdl:types>
    <xs:schema targetNamespace="http://example.com/stockquote"
      xmlns:xs="http://www.w3.org/2001/XMLSchema">
      <xs:element name="TradePriceRequest">
        <xs:complexType>
          <xs:all>
            <xs:element name="tickerSymbol" type="xs:string"/>
          </xs:all>
        </xs:complexType>
      </xs:element>
      <xs:element name="TradePrice">
        <xs:complexType>
          <xs:all>
            <xs:element name="price" type="xs:float"/>
          </xs:all>
        </xs:complexType>
      </xs:element>
    </xs:schema>
  </wsdl:types>
  
  <wsdl:interface name="StockQuoteInterface">
    <wsdl:operation name="GetLastTradePrice" 
      pattern="http://www.w3.org/@@@@/@@/wsdl/in-out">
      <wsdl:input element="tns:GetLastTradePriceInput">
      	<wsdl:header element="wsse:Security" required="true" mustUnderstand="true"/>
      </wsdl:input>
      <wsdl:output element="tns:GetLastTradePriceOutput">
        <wsdl:header element="wsse:Security" required="true" mustUnderstand="true"/>
      </wsdl:output>
    </wsdl:operation>
  </wsdl:interface>
  
  <wsdl:binding name="StockQuoteSoapBinding" interface="tns:StockQuoteInterface"
    type="http://www.w3.org/@@@@/@@/wsdl/soap" 
    wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP/">
    <wsdl:operation ref="tns:GetLastTradePrice" 
      wsoap:action="http://example.com/GetLastTradePrice"/>
  </wsdl:binding>
  
  <wsdl:service name="StockQuoteService" interface="tns:StockQuoteInterface">
    <wsdl:documentation>My first service</wsdl:documentation>
    <wsdl:endpoint name="StockQuoteEndPoint" binding="tns:StockQuoteBinding" 
    address="http://example.com/endpoint/stockquote"/>
  </wsdl:service>
  
</wsdl:definitions>

Proposed solution has nine parts:


    (1) Introduce a NEW Header Component


        Header Component

An Header Component describes an abstract piece of header that is 
associated with the exchange of messages between the communicating 
parties. The presence of an Header Component in a WSDL description 
indicates that the service supports the header and may require a Web 
Service consumer/client that interacts with the service to use that 
header. Zero or more such headers may be used.


        Header Component has 5 properties:

    * {namespace name} REQUIRED. An xs:anyURI. This URI MUST be absolute
      as defined by [IETF RFC 2396].
    * {local name} REQUIRED. An xs:NCName.
    * {element} REQUIRED. A reference to an XML element declaration in
      the {element declarations} property of The Definitions Component.
      This element represents a header.
    * {required} REQUIRED. An xs:boolean. If the value of this property
      is true, then the Web Service consumer/client MUST use the Header
      that is identified by the {element declaration}.
    * {mustUnderstand} OPTIONAL. An xs:boolean. If the property is true,
      then the bindings that support expression of mandatory data should
      mark them as mandatory in an appropriate way.


        Header Component's XML Representation is,

<header element="xs:QName" mustUnderstand="xs:boolean"? required="xs:boolean"?>
  <documentation />?
</header>


        Header Component's mapping is,

    * {element} = The element declaration from the {element
      declarations} property of The Definitions Component resolved to by
      the value of the element attribute information item if present,
      otherwise empty. It is an error for the element attribute
      information item to have a value and that value does not resolve
      to a global element declaration from the {element declarations}
      property of The Definitions Component.
    * {namespace name} = actual value of the {element declaration}'s
      [namespace name] property.
    * {local name} = actual value of the {element declaration}'s [local
      name] property.
    * {mustUnderstand} = actual value of the mustUnderstand attribute
      information item if present, otherwise absent.
    * {required} = actual value of the required attribute information
      item if present, otherwise "false".


    (2) Hook Header Component into the Interface Fault Component


        Add the property {headers}

Add the property {headers} to the Interface Fault Component: {headers} 
OPTIONAL. A set of Header components.


        Modify the XML Representation of Interface Fault Component

<definitions>
  <interface>
    <fault
          name="xs:NCName" 
          element="xs:QName"? >
      <documentation />?
      [ <header /> | <feature /> | <property /> ]*
    </fault>
  </interface>
</definitions>


        Modify the Mapping of Interface Fault's XML Representation to
        Component Properties

Addition to Table 2-3:

{headers} = The set of Header components corresponding to the header 
element information items in [children], if any.


    (3) Hook Header Component into the Message Reference Component


        Add the property {headers}

Add the property {headers} to the Message Reference Component: {headers} 
OPTIONAL. A set of Header components.


        Modify the XML Representation of Message Reference Component

<definitions>
  <interface>
    <operation>
      <input
            messageLabel="xs:NCName"?
            element="union of xs:QName, xs:Token"? > 
        <documentation />?
        [ <header /> | <feature /> | <property /> ]*
      </input>
      <output
            messageLabel="xs:NCName"?
            element="union of xs:QName, xs:Token"? >
        <documentation />?
        [ <header /> | <feature /> | <property /> ]*
      </output>
    </operation>
  </interface>
</definitions>


        Modify the Mapping of Message Reference's XML Representation to
        Component Properties

Addition to Table 2-6:

{headers} = The set of Header components corresponding to the header 
element information items in [children], if any.


    (4) Syntax Level Default Mechanism to Disable Header Construction


        Modify the XML Representation of Binding Component

<definitions>
  <binding
        name="xs:NCName" 
        interface="xs:QName"?
        type="xs:anyURI"
        disableHeadersDefault="xs:boolean"? >
    <documentation />?
    [ <fault /> | <operation /> | <feature /> | <property /> ]*
  </binding>
</definitions>

disableHeaderDefault AII is a syntax level convenient mechanism and does 
not contribute anything to the component model.


    (5) Mechanism to Disable Header Construction for the Binding Fault
    Component


        Add the property {disable headers} to Binding Fault Component

{disable headers} OPTIONAL. An xs:boolean. If this property exists and 
is true, then header construction is turned off. Scope of {disable 
headers} is limited to the WSDL Header components defined for the 
Interface Fault Component in {fault reference}. This property does not 
interact with any other WSDL feature, Bindings, Extensions or Feature 
and Properties framework.


        Modify the XML Representation of Binding Fault Component

<definitions>
  <binding>
    <fault
          ref="xs:QName" disableHeaders="xs:boolean"? >
      <documentation />?
      [ <feature /> | <property /> ]*
    </fault>
  </binding>
</definitions>


        Modify the Mapping of Binding Fault's XML Representation to
        Component Properties

Addition to Table 2-11:

{disable headers} = The actual value of the disableHeaders attribute 
information item, if present. If not, the actual value of the 
disableHeadersDefault attribute information item of the parent 
wsdl:binding element information item, if present. If not the value as 
defined by the concrete binding, if applicable.


    (6) Mechanism to Disable Header Construction for the Binding Message
    Reference Component


        Add the property {disable headers} to Binding Message Reference
        Component

{disable headers} OPTIONAL. An xs:boolean. If this property exists and 
is true, then header construction is turned off. Scope of {disable 
headers} is limited to the WSDL Header components defined for the 
Interface Operation component being bound by the containing Binding 
Operation component. This property does not interact with any other WSDL 
feature, Bindings, Extensions or Feature and Properties framework.


        Modify the XML Representation of Binding Message Reference Component

<definitions>
  <binding>
    <operation>
      <input
            messageLabel="xs:NCName"? disableHeaders="xs:boolean"? >
        <documentation />?
        [ <feature /> | <property /> ]*
      </input>
      <output
            messageLabel="xs:NCName"? disableHeaders="xs:boolean"? >
        <documentation />?
        [ <feature /> | <property /> ]*
      </output>
    </operation>
  </binding>
</definitions>


        Modify the Mapping of Binding Fault's XML Representation to
        Component Properties

Addition to Table 2-11:

{disable headers} = The actual value of the disableHeaders attribute 
information item, if present. If not, the actual value of the 
disableHeadersDefault attribute information item of the ancestor 
wsdl:binding element information item, if present. If not the value as 
defined by the concrete binding, if applicable.


    (7) Add to SOAP Binding's Default Binding Rules


        SOAP Header block construction

Default value of the Binding element's disableHeadersDefault AII is 
false. Default value of the Binding Operation Component's {disable 
headers} property is false.

If the {headers} property exists and non empty, and {disable headers} is 
false, element information item conforming to an Header Component's 
{element} property in the {headers} property MUST be turned into a SOAP 
Header block.

These elements are serialized according to their schemas, and if the 
Header Component's {mustUnderstand} property exists with the value 
"true", that particular SOAP header should be marked as 
"mustUnderstand='true'" or "mustUnderstand='1'" as per the SOAP 
specification.


    (8) Add to HTTP Binding's Default Binding Rules


        HTTP Header construction

Default value of the Binding element's disableHeadersDefault AII is 
false. Default value of the Binding Operation Component's {disable 
headers} property is false.

If the {headers} property exists and non empty, and {disable headers} is 
false, element information item conforming to an Header component's 
{element} property in the {headers} property MUST be turned into HTTP 
header if possible.

Only element information items of type "xs:string" or "xs:anyURI" may be 
serialized. All complex data types are ignored. Attributes on data 
elements are ignored.

Each such element information item is serialized as follows:

The HTTP header name used is the element information item local name. 
The element information item local name MUST follow the field-name 
production rules as specified in section 4.2 of [IETF RFC 2616]; if not, 
the element information item MUST be ignored. If an HTTP header 
corresponding to the element information item local name is set by a 
different mechanism other than the HTTP Binding, such as the HTTP stack 
or another feature, then an error MUST be raised.

The HTTP header content is serialized from the corresponding element 
information item value in UTF-8. If this serialization is NOT possible, 
then the element information item MUST be ignored.


    (9) Changes to XML Schema for WSDL 2.0

PENDING
Received on Wednesday, 26 January 2005 22:26:08 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Monday, 7 December 2009 10:58:34 GMT