Constraints & capabilities of Web services agents: a look at the current situation

2.1 From SOAP 1.2 extensibility to WSDL 2.0 extensibility

SOAP Version 1.2 [SOAP 1.2] formalizes the SOAP extensibility model by introducing SOAP Modules.

SOAP 1.2 also defines SOAP features, an extension of the SOAP messaging framework that can have on impact on both the SOAP Processing Model and the SOAP Protocol Binding Framework. Features may be expressed in a SOAP message using SOAP headers.

While SOAP 1.2 Modules may be described in terms of features, they may also define SOAP headers themselves. Therefore, an extension to SOAP may be described in two different ways.

SOAP features are an attractive way of describing extensibility: they are unambiguously identified with a URI, they may be concrete or abstract — i.e. describing abstractly a functionality, e.g. message reliability, or concretely, e.g. "the message recipient must return an acknowledgment of the following form to the message originator when a message received" —, they may be implemented by a binding or as a header. Moreover, their parameters are clearly identified as a list of properties which have a type and a value.

This is why there has been a desire to generalize them in the Web services architecture [WS Arch] as "capabilities", and in WSDL 2.0 [WSDL 2.0] as an abstract piece of functionality typically associated with the exchange of messages between communicating parties, untied from SOAP.

However, in the case a SOAP module does not use features and properties, parameters need to be defined another way. Because of these two ways of describing extensibility in SOAP 1.2, WSDL 2.0 also allows extensions to be expressed using its open content model, i.e. by allowing additional element information items and attribute information items in its component model.

2.2 The borderline with WSDL 2.0

A WSDL 2.0 [WSDL 2.0] document, whether it has been written by the provider entity, the requester entity or a third party, describes the Web service interface from the point of view of the service.

WSDL allows a service to declare the optional, or required, use of extensions and features. A provider agent cannot use an extension declared as optional in the WSDL document without evidence that the requester agent does support it.

One can see here that WSDL 2.0 provides the basis for describing supported and required extensions, i.e. capabilities and constraints, but additional syntax is required to compose and add conditions on the use of extensions. Specifically, the Web Services Description Working Group decided to stay out of the business was the composition of features (see WSDL 2.0 issue 134 about feature compositors).

However, this clearly is an area which is closely related to the kind description WSDL 2.0 provides, and therefore that can be expressed with another namespace in a WSDL 2.0 document.

3.1 A couple of scenarios

In order to help our discussion, let us consider the following scenarios:

1. The requester agent MUST use HTTP Authentication and MUST compress any messages sent to the provider agent. gzip and LZF compressions may be used. If gzip compression is used, then the provider agent will compress any subsequent with gzip. Otherwise, LZF compression will be used by the provider agent.

2. The provider agent MAY use either gzip, LZF or bzip2 compression. The requester agent, in its request, specifies which compression algorithms it supports, along with a preference, say LZF and gzip, in this order. The provider agent decides to compress the message with LZF as per the request agent's wishes.

The two above scenarios above will be referred to as example 1. and example 2. in the rest of this section.

3.2 Expressing composition of extensions

Both example 1. and 2. in 3.1 A couple of scenarios require a basic composition vocabulary: and, or, one of, any of, all of, etc. The Web Services Policy Framework [WS-Policy] proposal provides such a language, and a features compositors proposal for WSDL 2.0 [Compositors] also address this area.

3.3 Mapping conditions to message exchange patterns

Example 1. is interesting in that it declares a conditional behavior. The provider agent, because it has bandwidth limitations, only accepts compressed incoming messages, and will compress any outgoing messages. It supports two compression algorithms, and will reply with the same algorithm which was used in the original incoming message.

This is important information to the requester entity, as if the requester agent only supports gzip compression, it knows that using gzip compression in its request will get it a gzipped message that it can decompress. This is a simple example on an in-out message. However, messages exchange patterns (MEPs) may be more complex, such as in-out-out-out-in-out that would need to be accommodated too.

Using WSDL 2.0 operations and their input and output messages as a template for an expressing constraints and capabilities for an interaction makes sense. Conditions could be expressed in a WSDL 2.0 interface operation by references to sets of constraints.

Illustrating example 1.:

<operation>
  <input>
    <constraints:allOf required="true">
      <httpAuthentication/>
      <constraints:oneOf>
        <gzipCompression xml:id="gzipext"/>
        <lzfCompression/>
      </constraints:oneOf>
    </constraints:allOf>
  </input>
  <output>
    <constraints:oneOf required="true">
      <lzfCompression/>
      <gzipCompression constraints:ifUsed="#gzipext"/>
    </constraints:oneOf>
  </output>
</operation>

The syntax used here is only for illustration purposes and may not be well adapted to all cases. This may also be achieved as part of the orchestration of messages.

3.4 The requester agent's constraints and capabilities

Closely related to the provider entity expressing what the provider agent's capabilities are and what constraints it places on the interactions with requester agents, is the requester agent expressing its own constraints and capabilities. For example, knowing that the provider agent is likely to use some of those extensions it does not support, the requester agent may want to express certain preferences. This is illustrate by example 2. above.

We can see here similarities with HTTP/1.1 [RFC 2616] content and language negotiation mechanisms, as well as with the Composite Capability/Preference Profiles (CC/PP) [CC/PP] and exchange of those preferences [CC/PP Exch].

An agent should be able to include in its messages some constraints and capabilities statements, and those may need to be prioritized: in example 2., LZF is preferred to gzip as it is less CPU-intensive. A SOAP 1.2 module should be defined to carry such preferences.

6.1 Exposing the reliable messaging protocol requirement

The Web service requires "a reliable messaging protocol". Since there may be several available, there are two ways of addressing this problem:

1. the service provider can list all of the reliable messaging protocol it supports:

   <constraints:oneOf required='true'>
     <wsoap:module uri="http://example.com/reliableMessagingProtocol1"/>
     <wsoap:module uri="http://example.com/reliableMessagingProtocol2"/>
   </constraints:oneOf>

   In this case, one of the SOAP extensions identified by http://example.com/reliableMessagingProtocol1 (RMP 1) and http://example.com/reliableMessagingProtocol2 (RMP 2) is required.

2. the service provider can list a feature that indicates that a reliable messaging implementation needs to be used:

   <feature uri="http://example.com/reliableMessaging"
            required='true'/>

   In this case, any reliable message protocol specifications which will claim to implement the reliable messaging feature http://example.com/reliableMessaging will meet this requirement. If RMP1 and RMP2 do, than they will be acceptable solutions. A binding to HTTPR [HTTPR] could also be a candidate to implementing such a feature.

In the options above, wsoap:module and feature are defined by WSDL 2.0 ([WSDL 2.0] and [WSDL 2.0 Bindings]), while the additional syntax needed is in the constraints namespace.

It is worth noting that the first solution using SOAP modules brings the requirement from the abstract interface operation level down to the protocol binding level, i.e. that the requirement is tied to the SOAP binding. One could express 1 at the SOAP level (WSDL 2.0 binding component, i.e. in the binding element), and 2 at the abstract level (WSDL 2.0 interface level, i.e. in the interface element), as shown in 6.3 Expressing constraints and capabilites in a WSDL description.

This illustrates some of the nuances around 5 Expressing extensions: the time to make a choice.

6.2 Expressing the WS-Security requirement

WS-Security not having been defined in terms in terms of SOAP Version 1.2 concepts and therefore not being defined as a SOAP module or feature and property, special syntax needs to be defined in order to describe this extension, such as the one defined by WS-SecurityPolicy [WS-SecurityPolicy].

Inventing our own syntax, this could look like:

<wssecurity:encryption required="true">
  <header ref="foo"/>
  <wssecurity:token>
    <oneOf>
      <wssecurity:tokenType>x509</wssecurity:tokenType>
      <wssecurity:tokenType>user-name</wssecurity:tokenType>
    </oneOf>
  </wssecurity:token>
</wssecurity:encryption>

6.3 Expressing constraints and capabilites in a WSDL description

The use case could be expressed in a WSDL 2.0 document the following way, the requirement for a reliable messaging protocol is expressed both at the interface (with feature) and at the binding (with wsoap:module) levels:

<definitions>
  <interface name="w:i">
    <operation name="w:o">
      <input element="t:inmsg">
        <feature uri="http://example.com/reliableMessaging"
                 required='true'/>
        <wssecurity:encryption required="true">
	  <header ref="foo"/>
          <wssecurity:token>
            <constraints:oneOf>
              <wssecurity:tokenType>x509</wssecurity:tokenType>
              <wssecurity:tokenType>user-name</wssecurity:tokenType>
            </constraints:oneOf>
          <wssecurity:token>
      </input>
      <output element="t:outmsg"/>
     </operation>
  </interface>
  <binding  name="w:b" interface="w:i" type=".../soap12"
            wsoap:protocol="..." >
    <operation ref='w:o'>
      <input>
        <constraints:oneOf required='true'>
          <wsoap:module uri="http://example.com/reliableMessagingProtocol1"/>
          <wsoap:module uri="http://example.com/reliableMessagingProtocol2"/>
        </constraints:oneOf>
      </input>
      <output/>
    </operation>
  </binding>
</definitions>

6.4 Expressing constraints and capabilities in a SOAP header

A SOAP 1.2 module could carry the assertions defined above to refer to the subsequent messages part of the operation. Such a module could also be used to express requester preferences (see 3.4 The requester agent's constraints and capabilities).

WS-Addressing [WS-Addressing] proposes such a mechanism, carrying WS-Policy assertions [WS-Policy] along with addressing headers.

6.5 Expressing the service's P3P policy

One could use [Privacy in WSDL] introduced in 4 Advertising privacy policies of Web services and the generic P3P attribute p3patt:p3p to address the use case the following way:

<definitions>
  <interface name="w:i"
             p3patt:p3p="example-privacy-policy.xml">
    <operation name="w:o">
      <input element="t:inmsg">
        <feature uri="http://example.com/reliableMessaging"
                 required='true'/>
        <wssecurity:encryption required="true">
	  <header ref="foo"/>
          <wssecurity:token>
            <constraints:oneOf>
              <wssecurity:tokenType>x509</wssecurity:tokenType>
              <wssecurity:tokenType>user-name</wssecurity:tokenType>
            </constraints:oneOf>
          <wssecurity:token>
      </input>
      <output element="t:outmsg"/>
     </operation>
  </interface>
  <binding  name="w:b" interface="w:i" type=".../soap12"
            wsoap:protocol="..." >
    <operation ref='w:o'>
      <input>
        <constraints:oneOf required='true'>
          <wsoap:module uri="http://example.com/reliableMessagingProtocol1"/>
          <wsoap:module uri="http://example.com/reliableMessagingProtocol2"/>
        </constraints:oneOf>
      </input>
      <output/>
    </operation>
  </binding>
</definitions>