RE: Header/Body Style Proposal

After only a brief read it appears this would constitute a reversal in
the direction we agreed to pursue at our November FTF, which is to
replace explicit structural support for headers at the abstract level
with a feature/property based mechanism.  One of the main motivators was
that static headers (those that can be usefully described in WSDL) are
both rare and not very interesting.

From http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0062.html:

  Headers:
    RESOLVED: Remove @headers attribute.
    RESOLVED: Rename @body to @message.
    RESOLVED: Rename @detail to @message
    ACTION: Glen to write up rationale for removing headers (and?)
proposal
            for a generic header-adding property/feature.

...which action is still open.  I don't expect it to be completed by the
FTF, but we can hope :-).

> -----Original Message-----
> From: www-ws-desc-request@w3.org [mailto:www-ws-desc-request@w3.org]
On
> Behalf Of Yaron Goland
> Sent: Tuesday, January 20, 2004 4:26 PM
> To: www-ws-desc@w3.org
> Subject: Header/Body Style Proposal
> 
> 
> Arguably the most common protocol design style for application
protocols
> is
> what this letter will refer to as the headerBody style. Protocols such
as
> HTTP, SOAP, FTP, IMAP, ACAP, SMTP, etc. all use application messages
that
> contain a single body and multiple headers.
> 
> Given the universal popularity of this design style this letter
proposes
> that WSDL 2.0 add direct support for this style to WSDL 2.0.
> 
> The headerBody style will use the message attribute to identify the
> message's body. A new XML element, for use as a child of
> input/output/infault/outfault in interface definitions, will be used
to
> specify one or more headers. The XML element is defined as headerDef
and
> has
> four attributes:
> 
>     * name - A NCNAME that uniquely identifies a header instance
within a
> specific input/output/infault/outfault within a specific operation
within
> a
> specific interface. Name is optional and is only needed if a binding
will
> need to provide additional information about the header.
>     * header - The QNAME of a XML element schema definition that
defines
> the
> contents of the header.
>     * max - An int which specifies the maximum number of times that
header
> instance can be repeated. Max is optional and its default value is 1.
>     * min - An int which specifies the minimum number of times that
header
> instance can be repeated. Min is optional and its default value is 1.
> 
> max MUST be greater than or equal to min.
> 
> The headerDef XML element can be used 0 or more times.
> 
> For example:
> 
> <definitions...>
>    <interface...>
>       <operation...>
>          <input message="My:body">
>             <headerDef header="My:header"/>
>             <headerDef header="My:otherHeader" min="3" max="7"/>
>             <headerDef name="optheader" header="My:header" min="0"/>
>          </input>
>       </operation>
>    </interface>
> </definitions>
> 
> The headerBody style depends on the binding to define if the header
> ordering
> is meaningful. In the previous example the first and third headers are
of
> the same type. Allowing types to repeat is useful for bindings where
the
> order of headers is meaningful.
> 
> The headerBody style will be useful with both of the bindings that
WSDL
> 2.0
> provides, SOAP and HTTP as both of these protocols are based on
> header/body
> style messages. If this style is adopted then we can remove the
element
> attribute from the wsoap:header XML element and replace it with a name
> attribute that would point to the name of the associated header in the
> interface definition. The mustUnderstand and role attribute would
remain
> the
> same.
> 
> The SOAP binding for the headerBody style would specify that when
sending
> a
> message the header ordering SHOULD be maintained by the WSDL
processor.
> 
> In the case of receiving a message the WSDL processor MUST be able to
> accept
> SOAP headers in any arbitrary order and MUST be able to accept headers
> that
> were not defined in the SOAP message's WSDL interface/binding
definition.
> 
> SOAP headers MAY be implicitly rather than explicitly included in an
> operation definition as a consequence of a WSDL function or a SOAP
module.
> In other words, rather than explicitly including a reliable messaging
or
> security header one can readily imagine such headers being added as a
> consequence of a WSDL function/SOAP module that required reliability
or
> security of a certain type.
> 
> However, in many cases support for a particular function or module may
not
> be widespread amongst WSDL processors (even if the application layer
above
> the WSDL processor is aware of and able to handle the header implied
by
> the
> function/module) and so it may be necessary to include the SOAP header
> definition explicitly, even if it is redundant to a particular
> function/module, in order to allow for the widest syntactic
compatibility.
> 
> The following is an example of a WSDL operation and SOAP binding that
uses
> the headerBody style.
> 
> <definitions xmlns:my="http://foo/bar">
>    <types>
>       <xs:scheme targetName="http://foo/bar">
>          <xs:element name="headerOrBody" type="xs:string">/
>       </xs:scheme>
>    </types>
>    <interface name="sample"
> styleDefault="http://www.w3.org/@@@@/@@/wsdl/style/headerBody">
>       <operation name="sampleOp1"
> pattern="http://www.w3.org/@@@@/@@/wsdl/in-only">
>          <input message="my:headerOrBody">
>             <headerDef name="sampleOp1Header" header="my:headerOrBody"
> min="0"/>
>          </input>
>       </operation>
>    </interface>
>    <binding name="soapSimplebind">
>       <wsoap:binding
> protocol="http://www.w3.org/2003/05/soap/bindings/HTTP/"/>
>       <operation name="sampleOp1Binding">
>          <input messageReference="sampleOp1">
>             <header name="sampleOp1Header" mustUnderstand="True"/>
>          </input>
>       </operation>
>    </binding>
> </definitions>
> 
> To save space I used the same element for the header and the body.
What's
> interesting about this example is that while sampleOp1Header is
optional
> (min="0"), the binding specifies that mustUnderstand = "True". What
this
> means is that IF the header is used THEN the mustUnderstand attribute
MUST
> be put on the header and assigned the value true.
> 
> Either of the following SOAP 1.2 messages would be legal using the
> previous
> definition and binding:
> 
> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
>                          xmlns:my="http://foo/bar">
>    <env:Header>
>       <my:headerOrBody mustUnderstand="true">really?</my:headerOrBody>
>    </env:Header>
>    <env:Body>
>       <my:headerOrBody>Uh huh</my:headerOrBody>
>    </env:Body>
> </env:Envelope>
> 
> Or
> 
> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
>                          xmlns:my="http://foo/bar">
>    <env:Body>
>       <my:headerOrBody>Ahhh</my:headerOrBody>
>    </env:Body>
> </env:Envelope>
> 
> The HTTP binding would work similarly to SOAP but I'm waiting until
the
> HTTP
> POST/PUT proposal gets a bit firmer before I try to put in details. I
> think
> the most interesting issue with HTTP header support is how to
translate
> the
> XML element name and body for the WSDL header into a HTTP header. One
can
> imagine a myriad of different encoding possibilities. A minimal
encoding
> would require the header body to be a string. But one could also
imagine
> an
> encoding that either strips out elements or replaces elements with a
> divider
> character such as a ";". Perhaps we will need to support both and
specify
> which one to use on a header by header basis.
> 
> 	Thanks,
> 
> 			Yaron
>

Received on Wednesday, 21 January 2004 15:19:44 UTC