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

SOAP Header Blocks in WSDL (was RE: First Class Headers - Propose d Resolution for LC76d

From: Asir Vedamuthu <asirv@webmethods.com>
Date: Sun, 30 Jan 2005 16:10:27 -0800
Message-ID: <5B10E50E14A4594EB1B5566B69AD9407068E69E1@maileast>
To: 'Sanjiva Weerawarana' <sanjiva@watson.ibm.com>, "Liu, Kevin" <kevin.liu@sap.com>, www-ws-desc@w3.org
> I will likely have a heart attack over that one at this point
 
Easy :-) I like the wsoap:header proposal. As I said, it passes my simple
test - independent of F and P framework and something simple. Attached
proposal is one such mechanism. This proposal relies on schema for
optionality, choice, maxOccurs, etc.
 
Asir
 
-----Original Message-----
From: www-ws-desc-request@w3.org [mailto:www-ws-desc-request@w3.org] On
Behalf Of Sanjiva Weerawarana
Sent: Sunday, January 30, 2005 12:56 PM
To: Liu, Kevin; www-ws-desc@w3.org
Subject: Re: First Class Headers - Proposed Resolution for LC76d


I am at (1) and have been for a while. I am not convinced that we need
an interface-level way to describe these beasts.
 
If someone wants to put back wsoap:header then I will not have a heart
attack and die over that one. 
 
However doing what Asir suggested amounts to going back to <message>. I
think I will likely have a heart attack over that one at this point.
 
Sanjiva.

----- Original Message ----- 
From: Liu, Kevin <mailto:kevin.liu@sap.com>  
To: Sanjiva Weerawarana <mailto:sanjiva@watson.ibm.com>  ;
www-ws-desc@w3.org <mailto:www-ws-desc@w3.org>  
Sent: Saturday, January 29, 2005 1:13 AM
Subject: RE: First Class Headers - Proposed Resolution for LC76d

Hi Sanjiva,
 
I see a few questions we are trying to answer here:
 
1. do we need a way to describe headers (in interface and binding level) in
wsdl2.0?
2. if so, do we need to use Features & Properties to do that?
3. or we can just support it without F&P? 
 
I think the group has agreed that the answer for 1 is yes. DavidO has
produced serval proposal in the direction of 2, Asir's alternative proposal
is trying to resolve the issue in the direction of 3.
 
Per your message below, it's not clear to me if you are asking the group to
reconsider its decsion on 1, or you prefer the direction of 2, or you just
think the header support should be left to extensions? 

Best Regards,
Kevin
  

-----Original Message-----
From: www-ws-desc-request@w3.org [mailto:www-ws-desc-request@w3.org] 
Sent: Thursday, Jan 27, 2005 09:04 AM
To: www-ws-desc@w3.org
Subject: Re: First Class Headers - Proposed Resolution for LC76d


I'm sorry to rain on the parade, but I don't think this is a good direction.
 
First of all, we've been here before; I made a similar proposal when I made
the <message> elimination proposal. Then we decided to remove it ..
 
The problems with this proposal are:
- what's the intended programming model for this? I know that's out of scope
  for us, but do you expect that a stub, for example, would have an
additional
  parameter for each header? Having this messes up the nice clean simple
  programming model one can derive from WSDL as it stands now.
 
- One of the reasons @headers was removed IIRC was because it was too weak:
  you cannot say there's an optional header or a choice or a repeating
  thing. This proposal has the same problems (and in fact that was part
  of the motivation for dropping <message>).
 
- Putting this feels to me like we are basically inlining <message> inside
  the <input> etc. elements. Its like the doc/lit rule that WS-I came up
with ..
  only 1 body part and any # of header parts. I don't like it one bit
because
  it loses the clean and simpleness we achieved with a lot of work over a
very
  long time.
 
I'm sure I can think of more problem over time ;-).
 
Sanjiva.
 

----- Original Message ----- 
From: Prasad Yendluri <mailto:pyendluri@webmethods.com>  
To: www-ws-desc@w3.org <mailto:www-ws-desc@w3.org>  ; asirv@webmethods.com
<mailto:asirv@webmethods.com>  
Cc: jeffsch@windows.microsoft.com <mailto:jeffsch@windows.microsoft.com>  
Sent: Thursday, January 27, 2005 4:24 AM
Subject: Re: First Class Headers - Proposed Resolution for LC76d

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 <mailto:www-ws-desc@w3.org> 	
Date: 	Mon, 24 Jan 2005 08:46:20 -0500	
From: 	Asir Vedamuthu  <mailto:asirv@webmethods.com> <asirv@webmethods.com>

To: 	'www-ws-desc@w3.org <mailto:www-ws-desc@w3.org> '
<mailto:www-ws-desc@w3.org> <www-ws-desc@w3.org>	
CC: 	'jeffsch@windows.microsoft.com
<mailto:jeffsch@windows.microsoft.com> '
<mailto:jeffsch@windows.microsoft.com> <jeffsch@windows.microsoft.com>	

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" <http://www.w3.org/@@@@/@@/wsdl>


  targetNamespace="http://example.com/stockquote"
<http://example.com/stockquote> 

  xmlns:tns="http://example.com/stockquote" <http://example.com/stockquote> 

  xmlns:wsoap="http://www.w3.org/@@@@/@@/wsdl/soap"
<http://www.w3.org/@@@@/@@/wsdl/soap> 

 
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecuri
ty-secext-1.0.xsd"
<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-wssecurit
y-secext-1.0.xsd"
<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-wsse
curity-secext-1.0.xsd"
<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"
<http://example.com/stockquote> 

      xmlns:xs="http://www.w3.org/2001/XMLSchema"
<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"
<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"
<http://www.w3.org/@@@@/@@/wsdl/soap>  

    wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP/"
<http://www.w3.org/2003/05/soap/bindings/HTTP/> >

    <wsdl:operation ref="tns:GetLastTradePrice" 

      wsoap:action="http://example.com/GetLastTradePrice"
<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"
<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 Monday, 31 January 2005 00:11:12 GMT

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