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

RE: Header/Body Style Proposal

From: Yaron Goland <ygoland@bea.com>
Date: Thu, 22 Jan 2004 13:17:04 -0800
To: "'Sanjiva Weerawarana'" <sanjiva@watson.ibm.com>, "'Amelia A Lewis'" <alewis@tibco.com>, "'David Orchard'" <dorchard@bea.com>
Cc: <jmarsh@microsoft.com>, <www-ws-desc@w3.org>
Message-ID: <02a201c3e12d$15dbf360$65e5e40c@bea.com>

There are four scenarios that motivated my proposal. In each case static
headers are used whose definition rightfully belongs at the interface, not
the binding level. I believe that any one of these scenarios, much less all
four, justifies the inclusion of the header/body style in WSDL 2.0.

Scenario #1 - Backwards/Forwards Compatible Evolution

	A system deploys a new version of Interface Alpha called Alpha1. Alpha1
consists of nothing but backwards compatible changes to Alpha. Specifically,
Alpha1 adds new optional features to the Alpha operations. Due to the
numerous problems with XML Schema that David Orchard has pointed out [1]
it's not always possible to put the optional features directly into the old
message body. Therefore the new optional features are added as a header to
the original message. When a message arrives at Alpha1 the processor checks
to see if an extension header is present. If so then it implements the
message with the additional options offered by the extensions. If not, then
it processes the message as the original interface Alpha would have.

	If a Alpha1 client is talking to a Alpha server then the Alpha1 client can
send a Alpha1 message with the optional features in the header. The Alpha
server will ignore the optional header and process the message normally.

	This is why we can refer to Alpha1 as being both backwards and forwards
compatible. Alpha clients can send messages to Alpha1 servers and Alpha1
clients can send messages to Alpha servers and everyone gets a reasonable
experience.

	A classic example of this design pattern is byte-range headers in HTTP. If
someone sends a GET request with a byte-range header to a server that
doesn't support byte-ranges then the client receives back a normal GET
response. If the client sends the GET request with a byte-range header to a
server that does support byte-ranges then the client gets back a dedicated
byte-range response. But in all cases everyone gets a reasonable result.

	To implement this scenario in WSDL 2.0 we need a way to specify headers
directly in the interface definition so that the various features added in
the optional extensions can be directly specified.

Scenario #2 - Inbound Intermediary Communication

	A system deploys interface Beta. Interface Beta handles various types of
messages but is also able to handle certain kinds of data from
intermediaries. When intermediaries are deployed in the system Beta runs in
they need to know what kinds of application specific data can be handled by
the systems downstream. Beta is able to specify this information in its WSDL
by defining headers it understands. These headers are not infrastructure
based and do not represent functionality implemented at the WSDL level so it
is not useful to define them as WSDL functions as the WSDL engine will
obviously not provide support for an application specific header.

	For example, a bank implements a web service Beta that is used to evaluate
loan requests. The quality of service used to process the loan request will
depend on how much the bank values the customer. In the absence of any
specific customer 'value' data the loan system will use a default quality
level. Beta only knows about the customer's credit worthiness, it knows
nothing about how much the bank 'values' the customer. Instead an
intermediary is used that is tied to a database of customer 'value'
information. When any request enters the system the intermediary examines
the request, determines if it is a customer oriented request, if it is then
it looks up the customer in its database and slaps a header onto the request
with customer value information. It is that header that Beta has been
programmed to look for in setting its quality of service.

	The key issues in this scenario are - how did the intermediary know that
the message being sent to Beta was a customer request, how did it know how
to pull out the customer information and how did it know that Beta would be
able to handle the header?

	The answer to the first two questions is actually pretty easy if you are
familiar with BPEL. BPEL has a concept called message properties that are
defined using property Alias's. Both properties and property Aliases are
defined in the WSDL file. All that would be required therefore is to give
the intermediary the WSDL for Beta and the intermediary can see if the
'CustomerID' property (for example) is available (via a propertyAlias) on
any of the messages that Beta receives. If it is then the intermediary knows
that the message is customer related, can find the CustomerID and therefore
can do its database lookup.

	The third question, how did the intermediary know Beta would process the
header, is important because the intermediary doesn't want to do the work of
looking up the customer value if Beta is just going to ignore it. It is
tempting to just say 'oh well, there was a WSDL function that says that Beta
supports the header.' But that is an evasion. If that answer is acceptable
then we should pull out message definitions from WSDL as well since one can
just as easily say 'I don't need a message definition, I can just declare a
function'. The reality is that there is a syntax and it needs to be
declared, especially so that it can itself be versioned. E.g. Beta may
support the customer value header with a set of extensions.

	This is where being able to declare headers in the interface is so
important. By allowing Beta to specify its support for the header explicitly
in its interface the intermediary knows both that Beta supports the header
and what syntax of the header it supports.

Scenario #3 - WSDL Function Complementary Declaration

	Let us assume that WSDL functions take off. Even so, there is likely to be
a fairly long lag between when a function is defined and when it is widely
supported in WSDL engines. In the case of functions that define headers this
means it will be necessary to both include the function for WSDL engines
that support it and explicitly include the header declaration for WSDL
engines that don't support the function but whose applications do support
the associated functionality.

	For example, imagine a new header that is a signal that specifies that a
previously sent message has been successfully processed. A WSDL function is
defined that identifies that an interface supports receiving this type of
signal. However, it is going to take some time before all WSDL engines are
updated to provide support for this new function. In the meantime
applications that are build on WSDL engines that don't support the function
but still want to receive the header will have no choice but to explicitly
include the header's declaration so that they can see and process the
header. Therefore the header's definition is included in the interface even
though it is redundant with a function.

Scenario #4 - WSDL Interface Based Languages (e.g. BPEL)

	BPEL is a new Web Services programming language being standardized in OASIS
that uses WSDL 1.1 as its 'view' of the world. In BPEL everything is a
portType. It is universally expected within the BPEL TC that when WSDL 2.0
is released BPEL will move over to it (which, btw, is why SOAP 1.1 support
in WSDL 2.0 is so crucial since BPEL programs need to work with existing web
services). In fact, there is already a tracking item in BPEL to watch WSDL
2.0 and to try, as best we can given the requirement to be based on WSDL
1.1, to position BPEL for an easy transition over to WSDL 2.0 when it's
ready.

	In BPEL (using WSDL 2.0 terminology), if it isn't in the interface then it
can't be seen by the programmer. BPEL completely isolates the programmer
from the binding, which is a great thing as it allows programs to be truly
portable. This is, after all, the essence of the WSDL vision as I understand
it and why interfaces and bindings are kept separate.

	However this means that if the programmer needs access to a header, see my
previous scenarios for several examples of why a programmer would need this
access, the only way the programmer can get it is if the header is defined
in the interface. WSDL functions could be used here but only if the BPEL
engine supports that particular function. As scenario #3 illustrated there
is often a gap, sometimes an infinitely long one, between when a function is
introduced and when engines add support for it. In order for a BPEL
programmer to gain access to a header described by a function that isn't
supported by their engine they must be able to express the header's
definition in their interface definition.

[1] http://www.pacificspirit.com/Authoring/Compatibility/

> -----Original Message-----
> From: www-ws-desc-request@w3.org [mailto:www-ws-desc-request@w3.org]On
> Behalf Of Sanjiva Weerawarana
> Sent: Thursday, January 22, 2004 9:06 PM
> To: Amelia A Lewis; David Orchard
> Cc: jmarsh@microsoft.com; www-ws-desc@w3.org
> Subject: Re: Header/Body Style Proposal
>
>
>
> I'm +1 to Amy's strong -1 on this - we don't need an abstract header
> mechanism and we went thru many months (nearly 2 years of it) trying
> to simply WSDL and come up to a much better point that WSDL 1.1 was.
> I am not willing to give up an approach that was worked out with
> so much work at this point. What new information exists to re-open
> the abstract header issue?
>
> Sanjiva.
>
> ----- Original Message -----
> From: "Amelia A Lewis" <alewis@tibco.com>
> To: "David Orchard" <dorchard@bea.com>
> Cc: <jmarsh@microsoft.com>; <www-ws-desc@w3.org>
> Sent: Thursday, January 22, 2004 10:16 AM
> Subject: Re: Header/Body Style Proposal
>
>
> >
> > Strongly -1 to this.
> >
> > And if it's a choice between properties/features and the header/body
> > proposal, I'm strongly -1 on that proposal as well.
> >
> > Amy!
> > On Wed, 21 Jan 2004 14:57:37 -0800
> > David Orchard <dorchard@bea.com> wrote:
> >
> > > I haven't seen what a generic header-adding property/feature looks
> > > like as it hasn't been published.  It seems that this decision is
> > > dependent upon the generic header-adding property/feature being
> > > acceptable to the group.  The group has a choice of: a
> proposal on the
> > > table, or a proposal that has been due since November.  Aren't we
> > > running out of road here?
> > >
> > > Besides, I'm a bit negative on properties/features
> anyways, given that
> > > I can't figure out how to version them, extend them, use
> them, interop
> > > test them.  Seems to me like doing the published
> header/body proposal
> > > and dropping prop/feature solves a concrete (or at least we think
> > > concrete) problem and reduces complexity.
> > >
> > > Cheers,
> > > Dave
> > >
> > > > -----Original Message-----
> > > > From: www-ws-desc-request@w3.org
> > > > [mailto:www-ws-desc-request@w3.org]On Behalf Of Jonathan Marsh
> > > > Sent: Wednesday, January 21, 2004 12:20 PM
> > > > To: ygoland@bea.com; www-ws-desc@w3.org
> > > > Subject: 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
> > > > >
> > > >
> > > >
> > >
> >
> >
> > --
> > Amelia A. Lewis
> > Architect, TIBCO/Extensibility, Inc.
> > alewis@tibco.com
>
>
Received on Thursday, 22 January 2004 16:19:22 GMT

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