Re: First Class Headers - Proposed Resolution for LC76d

This looks good to me.

JJ.

Asir Vedamuthu wrote:

> 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 10:08:29 UTC