Re: Out Of Body Experiences (application header feature)

In response to Glen's proposal Tibco and BEA have worked together to 
create the following proposal for consideration by the WG.

[Note: The following presumes that property and feature values will be 
extended to allow more than just simple types. It also presumes that it 
will be possible to specify feature and properties on 
input/output/infault/outfault elements in the interface definition. If 
either of these assumptions should prove to be false then the feature's 
definition will be appropriately modified.]

[Additional Data Declaration (ADD) Feature]

Feature URI: http://www.w3.org/2004/02/modules/ADD
Required: True
Value:
<dataDef xmlns="http://www.w3.org/2004/02/modules/ADD">
    <dataEntry name="NCNAME"?
               occurs="optional | once | zeroOrMore | oneOrMore"?
               def="QNAME"> +
    </dataEntry>
</dataDef>

[OVERVIEW]

The ADD feature is placed on input/output/infault/outfault (IOIO) 
elements in the interface definition. It contains a series of dataEntry 
elements that each identify additional data to be sent along with the 
main message. A dataEntry is defined as a triple consisting of an 
optional name, an indication of how many times the additional data can 
appear on the bound message (which match ?, 1, + and *) and a QNAME that 
identifies the schema definition of the dataEntry's contents.

All dataEntry elements must be bound at the binding level. In the case 
of a SOAP binding each dataEntry will be implicitly bound and show up as 
an individual SOAP header. It is possible to specify additional 
information about a dataEntry's binding by explicitly referencing a 
dataEntry by name in the binding. To facilitate this the wsoap:header 
element is modified to make the element attribute optional and introduce 
an optional ADD attribute that can be used to give the name of the 
dataEntry to be modified.

[EXAMPLE]

Definitions targetNamespace="f:oo" xmlns:f="f:oo"
    Interface name="I"
       Operation name="O" pattern="some:pattern"
          input messageReference="M" message="a:message"
             feature uri="http://www.w3.org/2004/02/modules/ADD"/
                     require="true"
                dataDef
                   dataEntry occurs="oneOrMore" def="a:Def"
                   dataEntry name="another" occurs="optional"/
                             def="a:headerDef"
    Binding name="B"
       wsoap:binding protocol="a:protocol"
       operation name="0"
          input messageReference="M"
             wsoap:header ADD="another" mustUnderstand="true"/
                          role="some:one"
    Service name="S" interface="f:I"
       endpoint name="E" binding="f:B"

In this example someone sending a message to service S endpoint E would 
send a SOAP message whose body would be defined by a:message. The SOAP 
envelope would contain one or more instances of the header defined by 
a:Def. The SOAP envelope may also contain an instance of a SOAP header 
defined by a:headerDef. If the a:headerDef header is included by the 
original sender then its role will be set to some:one and its 
mustUnderstand attribute will be set to true.

[DETAILS]

The ADD feature is used to define additional data that is to be included 
alongside the message. This data MUST NOT be of any relevance to the 
WSDL stack or its bindings beyond syntax validation.

The ADD feature MUST only be attached to input/output/infault/outfault 
(IOIO) elements in the interface definition. It is legal, however, to 
have more than one instance of the ADD feature on a single IOIO element.

The ADD feature's value is a XML element dataDef which consists of one 
or more dataEntry elements. Each dataEntry element describes a single 
piece of additional data that can be bound independently of all other 
dataEntry elements in the same feature. An example of a SOAP binding is 
given below and a HTTP example will be provided once the HTTP binding 
settles down a bit.

Each dataEntry consists of an optional name attribute, an optional 
occurs attribute and a def attribute.

The value of a name attribute of a dataEntry MUST be unique amongst all 
dataEntry names defined on the same IOIO element. The name is only 
needed when the implicit binding is not sufficient and so is optional.

The occurs attribute defines how often the dataEntry will appear with 
the message. The choices are "optional", which means that the dataEntry 
will appear zero or one times; "once", which means the dataEntry will 
appear one time; "zeroOrMore", which means the dataEntry will appear 
zero or more times and "oneOrMore", which means the dataEntry will 
appear one or more times. The occurs attribute is optional and if absent 
defaults to "once".

The def attribute contains a QNAME which points at the schema definition 
of the dataEntry's value. It is legal for multiple dataEntry elements in 
a dataDef to share the same value for their def attributes.

The ADD feature MUST only be used with bindings that support the feature.

[Proposed Modification To The Syntax and Semantics of the WSDL 2.0 SOAP 
Binding]

The dataEntry elements in the ADD feature(s) on a particular IOIO 
element are, by default, mapped directly to SOAP headers. The value of 
each SOAP header is defined by the dataEntry element's def attribute, 
the role will default to unspecified (e.g. ultimate destination) and 
mustUnderstand will default to unspecified (e.g. false).

If one wishes to define SOAP specific data about a header, such as a 
role or the value of mustUnderstand, then the wsoap:header element is 
used. However, the wsoap:header element is modified such that one can 
either specify an element attribute or one can specify an ADD attribute. 
The ADD attributes value is of type NCNAME and will match the name of 
the dataEntry that is being specified. Any data entry not bound 
explicitly using a wsoap:header MUST be bound implicitly.

Glen Daniels wrote:

> 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 Wednesday, 3 March 2004 14:00:58 UTC