WSDL Extensions for the (Alternative) Email Binding

Status

This document is not an official product of any W3C working group, or of TIBCO Software, Inc. It is the culmination of a number of proposals and supporting materials submitted by TIBCO to the XMLP and Web Services Description working groups. Specifically, this document addresses the question of creating standard extensions to WSDL for the binding of abstract properties, as established by features and MEPs, to storage locations in internet email, using the binding information from the SOAP binding and the framework suggested in the WSDL property binding extension framework.

In its current form, the document is intended primarily for discussion, as a means of investigating the practicality of the proposed property binding extension framework for WSDL.

Table of Contents

Status

Definitions

Fixed Property Bindings

Default Property Bindings

Informal Default Property Binding Schema

References

Definitions

The email binding establishes optional or required support for a number of features and message exchange patterns. The namespaces of all the features and MEPs exposing properties which are bound in this document are listed below, together with the prefixes which will be used for each, throughout the document.

The features and MEPs listed above establish the abstract properties listed below. For each property, its QName is given, along with its type and its optionality. More information about particular properties may be found in the sections Fixed Property Bindings, Default Property Bindings, and Informal Schema. In particular, the suggested/default binding of various properties may be found in these sections. The schema is considered normative, as it is intended for reference within a WSDL. The text is thus illustrative.

* : more complex than the simple required/optional, really.

Fixed Property Bindings

Fixed property bindings establish a storage location for the specified properties which is the only permissible location for that property to be stored to and retrieved from, for all service instances using the protocol binding. Appearance of an alternate binding in a service description is an error.

The following properties have fixed storage locations for the email binding extension. These bindings may be specified, but should not be.

mimecont:version

The version property must be bound to the protocolHeader Mime-Version. In email, this header may not be omitted. The property is required, and fixed, in a required feature.

mimecont:transfer-encoding

The transfer-encoding property must be bound to the protocolHeader Content-Transfer-Encoding. The property is required, and fixed, in a required feature.

mimecont:content-type

The content-type property must be bound to the protocolHeader Content-Type. The property is required, and fixed, in a required feature.

Other properties in the mime-content namespace

As with the foregoing properties, all other properties in the MIME namespace, if bound, must be bound to the corresponding MIME protocolHeader (generally, a header that starts with "Content-".

Properties in the mime-composite namespace

[[Note that this probably needs to be revisited after examining the current soap with attachments draft and revising mime composite accordingly.]] Like properties of the mime content feature, all properties exposed by the mime composite feature must be bound to their corresponding protocolHeader ... or the corresponding partHeader, when dealing with a message part rather than a complete message. These properties are fixed, but not required, in an optional feature. [[Issue: this introduces a problem in the definition of the enumeration. Fixed may mean must be bound to this location, or none, but is actually orthogonal to required/optional. Prohibited, in contrast, makes the locationType and other information altogether irrelevant.]]

Default Property Bindings

Default property bindings establish a storage location for the specified properties which is to be used if and only if the service does not supply an alternative. In other words, this specification effectively establishes information that a conforming processor must insert into the WSDL, if it finds a missing required element that has a default definition.

addr:original-source

The specified default is a standard SMTP header, From. The property is required, in a required feature.

addr:final-destination

The specified default is a standard SMTP header, To. The property is required, in a required feature.

addr:response-address

The specified default is a standard SMTP header, Reply-To. The property is optional, in a required feature.

corr:message-id

The specified default is a construction. The headers From, Subject, and Date are concatenated, using the underscore character between each part. The property is required, in a required feature.

corr:references

The specified default is an SMTP extension header, X-Soap-References. The property is listed as optional, but is required in response messages; the feature is required.

faildest:failure-destination

The specified default is the first bound property of the sequence: addr:response-address, addr:original-source. The property is required, in an optional feature.

solicit:TermCondition

The specified default is an SMTP extension header, X-Termination-Condition. The property is required, in a required (built-in) feature (of a particular exchange pattern).

solicit:Synchronous

Use of the property is prohibited. It may not be bound. Internet email does not usefully support synchronous operation in any meaningful sense. The property is prohibited, in a required (built-in) feature (of a particular exchange pattern).

solicit:Deadline

The specified default is an SMTP extension header, X-Deadline. The property is optional (actually, required for certain values of solicit:TermCondition), in a required (built-in) feature (of a particular exchange pattern).

solicit:NumRespondents

The specified default is an SMTP extension header, X-Max-Responses. The property is optional (actually, required for certain values of solicit:TermCondition), in a required (built-in) feature (of a particular exchange pattern).

Informal Default Property Binding Schema

This section is based on a suggestion by Christopher Ferris, that a protocol binding might establish a standard/default set of bindings for properties. This set of bindings could then be simply referenced by the WSDL. This version continues to assume that override (per-service) is possible. In fact, it arguably illustrates why one would want to do so: to prohibit something optional, to require something optional, or to simply change the storage location, because the ones suggested here seem inappropriate.

<wsdl:protocolBinding uri="http://www.tibco.com/xmlns/soap/bindings/distEmail/"
                      xmlns:distEmail="http://www.tibco.com/xmlns/soap/bindings/distEmail/"
                      xmlsn:addr="http://www.tibco.com/xmlns/soap/message-address">
                      <!-- the other namespaces aren't used internally, so we haven't bothered to define them -->
  <wsdl:featureBinding name="message-address" uri="http://www.tibco.com/xmlns/soap/message-address/" use="required">
    <wsdl:simpleProperty name="original-source" locationType="wsdl:protocolHeader"
                         use="required">From</wsdl:simpleProperty>
    <wsdl:simpleProperty name="final-destination" locationType="wsdl:protocolHeader"
                         use="required">To</wsdl:simpleProperty>
    <wsdl:simpleProperty name="response-address" locationType="wsdl:protocolHeader"
                         use="optional">Reply-To</wsdl:simpleProperty>
  </wsdl:featureBinding>
  <wsdl:featureBinding name="message-correlation" uri="http://www.tibco.com/xmlns/soap/message-correlation/" use="required">
    <wsdl:complexProperty name="message-id" use="required">
      <wsdl:algorithm name="distEmail:catHeaders">_</wsdl:algorithm>
      <wsdl:simpleProperty locationType="wsdl:protocolHeader">From</wsdl:simpleProperty>
      <wsdl:simpleProperty locationType="wsdl:protocolHeader">Subject</wsdl:simpleProperty>
      <wsdl:simpleProperty locationType="wsdl:protocolHeader">Date</wsdl:simpleProperty>
    </wsdl:complexProperty>
    <wsdl:simpleProperty name="references" locationType="wsdl:protocolHeader"
                         use="optional">X-Soap-References</wsdl:simpleProperty>
  </wsdl:featureBinding>
  <wsdl:featureBinding name="failure-destination" uri="http://www.tibco.com/xmlns/soap/failure-destination/" use="optional">
    <!-- an interesting consequence of feature definition: if the (optional) feature is used, then its
         sole property is required. -->
    <wsdl:propertyChoice name="failure-destination" use="required">
      <wsdl:simpleProperty locationType="wsdl:propertyReference">addr:response-address</wsdl:simpleProperty>
      <wsdl:simpleProperty locationType="wsdl:propertyReference">addr:original-source</wsdl:simpleProperty>
    </wsdl:propertyChoice>
    <!-- a different, perfectly reasonable possibility -->
    <!-- wsdl:simpleProperty name="failure-destination" locationType="wsdl:protocolHeader"
                         use="required">X-Errors-To</wsdl:simpleProperty -->
  </wsdl:featureBinding>
  <wsdl:featureBinding name="mime-content" uri="http://www.tibco.com/xmlns/soap/mime-content/" use="required"">
    <wsdl:simpleProperty name="version" locationType="wsdl:protocolHeader"
                         use="fixed">Mime-Version</wsdl:simpleProperty>
    <wsdl:simpleProperty name="content-type" locationType="wsdl:protocolHeader"
                         use="fixed">Content-Type</wsdl:simpleProperty>
    <wsdl:simpleProperty name="transfer-encoding" locationType="wsdl:protocolHeader"
                         use="fixed">Content-Transfer-Encoding</wsdl:simpleProperty>
  </wsdl:featureBinding>
  <wsdl:featureBinding name="mime-composite" uri="http://www.tibco.com/xmlns/soap/mime-composite/" use="optional">
    <wsdl:simpleProperty name="content-id" locationType="mime:partHeader"
                         use="fixed">Content-Id</wsdl:simpleProperty>
    <wsdl:simpleProperty name="content-location" locationType="mime:partHeader"
                         use="fixed">Content-Location</wsdl:simpleProperty>
    <wsdl:simpleProperty name="current-part" locationType="mime:part" use="fixed" />
  </wsdl:featureBinding>
  <wsdl:mepBinding name="solicit-response" uri="http://www.tibco.com/xmlns/soap/mep/solicit-response/">
    <wsdl:simpleProperty name="TermCondition" locationType="wsdl:protocolHeader"
                         use="required">X-Termination-Condition</wsdl:simpleProperty>
    <wsdl:simpleProperty name="Synchronous" locationType="wsdl:none" use="prohibited" />
    <wsdl:simpleProperty name="NumRespondents" locationType="wsdl:protocolHeader"
                         use="optional">X-Max-Responses</wsdl:simpleProperty>
    <wsdl:simpleProperty name="Deadline" locationType="wsdl:protocolHeader"
                         use="optional">X-Deadline</wsdl:simpleProperty>
  </wsdl:mepBinding>
</wsdl:properties>

References

Based on the features, MEPs, and the alternative email binding proposal submitted to the XML Protocol working group as an illustration of the SOAP 1.2 extensibility mechanism and an implementation of pub/sub semantics in SOAP.