Copyright © 2002 W3C® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use, and software licensing rules apply.
This document is meant to be an illustration of the SOAP 1.2 Protocol Binding Framework applied to a well known internet transport mechanism, Email, specifically rfc2822.
This document is a NOTE made available by the W3C for discussion only. Publication of this Note by W3C indicates no endorsement of its content by W3C, nor that W3C has, is, or will be allocating any resources to the issues addressed by the Note. This document is a work in progress and may be updated, replaced, or rendered obsolete by other documents at any time.
This document was written by members of the Transport Binding Task Force (TBTF)-- a part of the XML Protocol WG-- on behalf of the XML Protocol WG. The XML Protocol WG agreed to the publication of this document. The XML Protocol WG has no plans for further work on this document.
This version has been published to clarify the status section of the previously published version.
A list of current W3C technical documents can be found at the Technical Reports page.
The motivation for this document is to illustrate the SOAP 1.2 Protocol Binding Framework and the creation of an alternative protocol binding specification to the Default HTTP binding. This second binding is meant to validate the Protocol Binding Framework for completeness and usability. Please note that this document is a non-normative description of an Email Binding.
It is not the responsibility of this SOAP binding to mandate a specific email infrastructure, therefore specific email infrastructure protocol commands (such as SMTP, POP3, etc) are not covered in this binding document. The underlying email infrastructure and the associated commands of specific email clients and servers along the message path are outside the scope of this email binding.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALLNOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119 [KEYWORDS].
Namespace URIs of the general form "some-URI" represent some application-dependent or context-dependent URI as defined in RFC2396 [URI]. The namespace prefixes "SOAP-ENV" and "ds" used in this document are associated with the namespaces "http://schemas.xmlsoap.org/soap/envelope/" and "http://www.w3.org/2000/09/xmldsig#", respectively.
This SOAP binding specification adheres to the SOAP Protocol Binding Framework (see SOAP Protocol Binding Framework), and as such uses abstract properties as a descriptive tool for defining the functionality of certain features.
Properties are named with XML qualified names (QNames). Property values are determined by the Schema type of the property, as defined in the specification which introduces the property. The following tables lists the standard prefix mappings which we assume to hold throughout this specification:
Prefix | Namespace |
---|---|
context | http://www.example.org/2001/12/soap/bindingFramework/ExchangeContext/ |
mep | http://www.example.org/2001/12/soap/mep/ |
fail | http://www.example.org/2001/12/soap/mep/FailureReasons/ |
reqresp | http://www.example.org/2001/12/soap/mep/request-response/ |
Email applications MUST use the media type "application/soap+xml" according to [soap-media-type] when including SOAP 1.2 messages in Email exchanges. See [soap-media-type] for parameters defined by this media type and their recommended use.
The binding described here is identified with the URI:
http://www.example.org/2002/02/soap/bindings/Email/
This binding is provided as an example binding when using Email and the standard Internet Message Format described in rfc2822. Unlike HTTP, Email does not inherently provide a request/response Message Exchange Operation. An Email message meant to be a response to the original request will be sent back to the original sender. A means of correlating the original request to the resulting response will be descibed as a binding feature.
An instance of a binding to Email[RFC2822] conforming to this binding specification MUST support the following message exchange pattern:
http://www.example.org/2001/12/soap/mep/request-response/ (see SOAP 1.2, Part 2, 6.2 Request-Response MEP)
Note that although this message exchange pattern permits temporal overlap between a SOAP Request Message and a SOAP Response Message, the store-and-forward nature of Email is such that this circumstance does not arise. This binding specification treats the transmission and reception of SOAP messages as discrete events.
The "http://www.w3.org/2002/06/soap/mep/request-response/" message pattern is described in SOAP 1.2, Part 2, 6.2 Request-Response MEP.
For binding instances conforming to this specification:
A SOAP Node instantiated at an email protocol interface (sending
and receiving) may take on the role (i.e. the property
reqresp:Role
) of RequestingSOAPNode
.
A SOAP Node instantiated at an email protocol interface (sending
and receiving) may take on the role (ie. the property
reqresp:Role
) of RespondingSOAPNode
.
The remainder of this section consists of descriptions of the
MEP state machine, and its particular relation to RFC 2822. In the
state tables below, the states are defined as values for the
property reqresp:State
(see
SOAP 1.2, Part 2, 6.2 Request-Response MEP), and are of
type reqresp:StateType
(an enumeration over
xsd:string
).
Failure reasons as specified in the tables represent values of
the property context:FailureReason
- their values are
QNames. If an implementation enters the "Fail" state, the
context:FailureReason
property will contain the value
specified for the particular transition.
The overall flow of the behaviour of a Requesting SOAP Node follows the outline state machine description contained in SOAP 1.2, Part 2, 6.2 Request-Response MEP. The following subsections describe each state in more detail.
Statename | Init | ||
Description | Formulate and Send Request Message | ||
Preconditons | See SOAP 1.2, Part 2, 6.2.3 Request-Response Formal Description | ||
Action on Entry | Formulate and send Email Request (see Table 3:Email Fields) | ||
Post Conditions | None | ||
Transitions | Event/Condition | NextState | Failure Reason |
Request Successfully Sent | Requesting | N/A | |
Failure to send Request | Fail | fail:TransmissionFailure |
Field Descriptions | |
Originator and Destination Fields | "From:" sender-node-uri CRLF "To:" request-uri CRLF "Message-ID:" correlation:requestMessageID CRLF |
Sender Node URI | The value of the URI carried in the
reqresp:ImmediateSender property of the message
exchange context. |
Request URI | The value of the URI carried in the
reqresp:ImmediateDestination property of the transport
message exchange context. |
Correlation Request Message ID | The Request email msg-id value is automatically generated at
the requesting node's email interface. The correlation feature
correlation:requestMessageID is described in Section
5.1. |
Content-Type (MIME) header | "application/soap+xml" (see Introduction) |
Email message body | XML 1.0 serialisation of the SOAP message XML Infoset carried in the reqresp:OutboundMessage property of the transport message exchange context. |
Statename | Sending | ||
Description | Waiting for correlated Email response(Request Message completely sent on exit from Init state) | ||
Preconditons | None | ||
Post Conditions |
|
||
Transitions | Event/Condition | NextState | Failure Reason |
Received correlated Email response | Sending + Receiving | NA | |
Reception Failure - Timeout | Fail | fail:ReceptionFailure |
Statename | Receiving | ||
Description | Receive Correlated Email response entity body, which is assumed to contain a SOAP envelope serialized according the XML 1.0 + Namespaces spec. | ||
Preconditons | None | ||
Post Conditions | On transitions to Success, instantiate or replace the property reqresp:InboundMessage with an infoset representation of the serialized envelope in the response body. | ||
Transitions | Event/Condition | NextState | Failure Reason |
Well formed Response Message Received | Success | ||
Reception Failure (broken connections etc.) | Fail | fail:ReceptionFailure |
|
Packaging Failure (inc. mismatched Content-Type) | Fail | fail:PackagingFailure |
|
Malformed Response Message, eg malformed XML, message contained a DTD, an invalid SOAP Envelope | Fail | fail:BadResponseMessage |
The overall flow of the behaviour of a Requesting SOAP Node follows the outline state machine description contained in SOAP 1.2, Part 2, 6.2 Request-Response MEP.
Statename | Init | ||
Description | Receive and validate the inbound Request Message | ||
Preconditons | Delivery of an Email message containing a SOAP envelope serialized according the XML 1.0. | ||
Post Conditions | None | ||
Transitions | Event/Condition | NextState | Action |
Receive Email message containing well formed Request Message. | Receiving |
This change of state represents a transfer of control of the inbound transport message exchange context to the local SOAP node. |
|
Receive Email message containing malformed Request Message | Fail |
The message is deemed to have been intended for the local SOAP node, but is deemed badly formed: ill-formed XML, contains a serialized DTD and/or does contain a valid SOAP envelope. The local SOAP node generates SOAP Fault message in accordance with the table below which it sends in the corresponding Email response message. The transport message exchange context may be destroyed or considered not to have been created. |
Statename | Receiving | ||
Description | Waiting for Response Message to become available in Message Exchange Context as a result of processing the Request Message (note Request Message fully received on exit from Init state). | ||
Preconditons | None | ||
Post Conditions | See Below | ||
Transitions | Event/Condition | NextState | Action or Failure Reason |
A Response Message becomes available in reqresp:OutBoundMessage indicating that the local SOAP node has generated a Response Message. | Receiving + Sending | reqresp:OutboundMessage MAY contain a SOAP
fault. Formulate and send the Response Message (see Table 9: Email Fields) |
Statename | Receiving + Sending | ||
Description | Completing Request Message reception and Response Message transmission. (Response Message sent on exit from Receiving State). | ||
Preconditons | None | ||
Post Conditions | See Below | ||
Transitions | Event/Condition | NextState | Action or Failure Reason |
Response Message Successfully sent | Success | NA | |
Failure to send Response Message | Fail | fail:TransmissionFailure |
Field Descriptions | |
Originator and Destination Fields | "From:" request-uri CRLF "To:" sender-node-uri CRLF "In-Reply-To:" correlation:requestMessageID CRLF |
Sender Node URI | The value of the URI carried in the
reqresp:ImmediateSender property of the transport
message exchange context. |
Request URI | The value of the URI carried in the
reqresp:ImmediateDestination property of the transport
message exchange context. |
Correlation Request Message ID | The Request email msg-id carried in the correlation property
correlation:requestMessageID is described in Section
5.1. |
Content-Type (MIME) header | "application/soap+xml" (see Introduction) |
Email message body | XML 1.0 serialisation of the SOAP message XML Infoset carried in the reqresp:OutBoundMessage property of the transport message exchange context. |
This transport binding specification defines a binding specific expression for the following features:
http://www.example.org/2001/12/soap/bindings/Email/correlation/
Other features that are compatible with the message exchange patterns listed above are supported using their generic in-envelope expression defined in the relevant feature specification.
This sub-section defines a binding specific optional feature named:
http://www.example.org/2001/12/soap/binding/Email/correlation/
In the text to follow, the prefix "correlation" is mapped to the URI "http://www.example.org/2001/12/soap/binding/Email/correlation/"
SOAP Requesters using this binding will need a mechanism to correlate response messages to their original, corresponding request message. This binding uses an externalised expression of the correlation feature (email msg-id) to supply this information.
Property Name | Description |
correlation:requestMessageID |
Used to hold the original request email message
id, which is automatically generated by the requesting nodes email
infrastructure.
The type of this property is String in the namespace http://www.w3.org/2001/XMLSchema-datatypes. |
The correlation:requestMessageID
property is
represented using Email fields. The following table shows the
points at which the property value and the Email fields are
exchanged.
Client | ||
Property Name | Request | Response |
correlation:requestMessageID |
The automatically generated
correlation:requestMessageID property is sent as the
value of the Email field Message-ID. |
N/A |
Server | ||
Property Name | Request | Response |
correlation:requestMessageID |
N/A | The original requesting Message-ID
correlation:requestMessageID will be returned to the
requesting node via the Email field In-Reply-To. |