Out Of Body Experiences (application header feature)

Hi folks!

Sorry for the delay on this AI.  Here's the background/rationale on this:

A given extension (security, transactability, complex MEPs) generally
involves more than a single header.  Often there are constellations of
headers which must work together semantically in order to provide the given
functionality - sometimes with multiple headers in the same message, other
times with sets of headers which work together across several messages.  In
addition, many times the decision as to whether to send a particular header
in a particular message is more complex than "just send it", requiring
information only available in the extension's rules and specification.

The features and properties mechanism in WSDL 2.0 already provides a way to
specify parameters relevant to particular extensions, and leaves the actual
semantics of those extensions (when to insert a particular header, and which
values said header should contain) up to the final arbiter, the extension
spec and the code which has been written to implement it.  To rephrase this
important point - extensions designed using the F&P mechanism or other
similar architectures tend to expose a data-based "API" which controls the
operation of the extension.  This allows the specification of particular
properties/assertions in a WSDL document without breaking the abstraction
boundary of the spec and getting into the structure/mechanics of the
particular headers which might be flowing at any given time.

In WSDL 1.1, the only way to specify header behavior which was mentioned in
the spec was the <soap:header> element.  This mechanism is a simple
assertion - ALWAYS send this exact header.  Even though it was possible to
define custom extensibility elements to perform the same task as F&P/Policy,
most early usage of header-based description in WSDL was by specifying
individual headers with <soap:header>.  Unfortunately, this has several
problems mentioned above - it's a brute-force means to accomplish an end
which is often more subtle, and it can be error prone when involving all but
the simplest of extensions.

One of the valid use cases brought up for this kind of "always send this
header with this message" mechaism is application-specific extension data.
In other words, when an application doesn't want to, or cannot, change the
structure of the SOAP body, but wants to send new information which really
isn't part of an extension specification per se, it can use the header
mechanism to send this data "out-of-band".  We believe this is a common and
useful goal, but that actually specifying individual SOAP headers for each
such piece of data may not be the best way to go about acheiving it.  As
such, an "Out of Band Application Data" feature and associated SOAP module
are proposed to enable this functionality without encouraging people to
essentially design their own ad-hoc extensions to acheive a simple and
common purpose.

Finally, with the understanding that there are in fact some occasions when
you really do want to be able to specify a particular header in WSDL, we
still do have the <soap:header> mechanism for doing so.  I think it is
important, though, for the group to put forward the idea that best practice
in this area is to use SOAP modules and F&P/Policy to inject particular
values into extension state machines, and not generally to specify headers
directly.  When desiring to use headers for "application level" data, it is
suggested that something like the feature+module below be utilized.

It's not that I don't want people to ever be able to touch the SOAP header
via direct metadata.  It's that I don't want people to think that that's the
right way to deal with most extensions.

Feature and Module descriptions below.

Thanks,
--Glen

(Please note that these are drafts whose sole purpose is to demonstrate the
concepts involved.  They may need serious cleanup before being ready for
prime-time.)

[ Out-of-Body Application Data Feature ]

This feature is identified with the URI
http://www.w3.org/2004/02/features/OOBData

* Operation

This feature exists in order to propagate application-defined data outside
of the normal data channel (e.g. the SOAP body).  The sender take the value
of the property http://www.w3.org/2004/02/features/OOBData/data, which can
be any XML infoset, and passes it to the receiver in a manner to be defined
by particular bindings/modules implementing this specification.

[ Out-Of-Body Application Data Module ]

This module is identified with the URI
http://www.w3.org/2004/02/modules/OOBData

* Features Implemented

This module implements the feature
http://www.w3.org/2004/02/features/OOBData.

* Operation

This module introduces a SOAP header with the local name of "data" in the
namespace http://www.w3.org/2004/02/modules/OOBData (we will use the prefix
"oob" to refer to this namespace in our examples).

As a SOAP sender, if the property
http://www.w3.org/2004/02/features/OOBData/data has a value, the contents
should be serialized inside the <oob:data> header.

As a SOAP receiver, the contents of the <oob:data> header should be made
available to the application as the value of the property
http://www.w3.org/2004/02/features/OOBData/data.

* Example

<env:Header>
 <oob:data xmlns:oob="http://www.w3.org/2004/02/modules/OOBData">
  <myApplicationData/>
  <more:data xmlns:more="http://myNamespace">3.14159</more:data>
 </oob:data>
</env:Header>

Received on Thursday, 12 February 2004 11:04:16 UTC