RE: First Class Headers - Proposed Resolution for LC76d

I like this proposal very much. It's simple, it's clean, it's easy to
follow...

Best Regards,
Kevin
  

-----Original Message-----
From: www-ws-desc-request@w3.org [mailto:www-ws-desc-request@w3.org] 
Sent: Monday, Jan 24, 2005 05:46 AM
To: 'www-ws-desc@w3.org'
Cc: 'jeffsch@windows.microsoft.com'
Subject: First Class Headers - Proposed Resolution for LC76d



LC76d -  <http://www.w3.org/2002/ws/desc/4/lc-issues/#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/> 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-wsse
curity-secext-1.0.xsd">

    

  <xs:import

 
namespace="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssec
urity-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