SOAP Version 1.2 Email Binding

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.

Status of this document

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.

Motivation

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.

Notational Conventions

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.

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.

Table 1: Standard prefix mappings
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/

4 Request-Response Message Exchange Operation

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.

4.1 Behaviour of Requesting SOAP Node

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.

4.1.1 Init

Table 2: State Description: Init
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`

Table 3: Email Fields
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.

4.1.2 Sending

Table 4:State Description: Sending
Statename	Sending
Description	Waiting for correlated Email response(Request Message completely sent on exit from Init state)
Preconditons	None
Post Conditions	Instantiate or replace the property `reqresp:ImmediateSender` with a URI value that denotes the sender of the Email response (if known) In all cases, any Email fields that are significant to features expressed outside the SOAP envelope are processed in accordance with the relevant feature specification.

Transitions	Event/Condition	NextState	Failure Reason
	Received correlated Email response	Sending + Receiving	NA
	Reception Failure - Timeout	Fail	`fail:ReceptionFailure`

4.1.3 Sending + Receiving

Table 5: State Description: Sending + Receiving State
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`

4.1.4 Success and Fail

These are the terminal states of for a given instance of a request-response transport message exchange. Control over the transport message exchange context returns to the local SOAP node.

4.2 Behaviour of Responding SOAP Node

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.

4.2.1 Init

Table 6: State Description: Init
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	Instantiate or replace the property reqresp:ImmediateSender with a URI value that denotes the sender of the Email message request Instantiate or replace the property reqresp:InboundMessage with a value that represents an infoset representation of the received Request Message. Any Email headers that are significant to features expressed outside the SOAP envelope (eg correlation via msg-id) are processed in accordance with the relevant feature specification. 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.

4.2.2 Receiving

Table 7: State Description: Receiving
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)

4.2.3 Receiving + Sending

Table 8: State Description: Receiving + Sending
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`

Table 9: Email Fields
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.

4.2.4 Success and Fail

These are the terminal states of for a given instance of a request-response transport message exchange. From the point-of-view of the local node this message exchange has completed.

5. Features Expressed External to the Message Envelope

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.

5.1 Message Correlation using msg-id

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.

Feature Properties
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.

Feature Operation (Client side)
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

Feature Operation (Server side)
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.

6. SOAP Email Examples

See SOAP 1.2 Primer, 3.2 SOAP over Email

7. References

[KEYWORDS]: S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels," RFC 2119, Harvard University, March 1997
[SOAP-1.2 Part 1]: W3C Working Draft "SOAP 1.2 Part 1: Messaging Framework," Martin Gudgin, Marc Hadley, Jean-Jacques Moreau, Henrik Frystyk Nielsen
[SOAP-1.2 Part 2]: W3C Working Draft "SOAP 1.2 Part 2: Adjuncts," Martin Gudgin, Marc Hadley, Jean-Jacques Moreau, Henrik Frystyk Nielsen
[SOAP-attachment]: W3C Note, "SOAP Messages with Attachments," 11 December 2000.
[URI]: T. Berners-Lee, R. Fielding, L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax," RFC 2396, MIT/LCS, U.C. Irvine, Xerox Corporation, August 1998.
[XML-ns]: W3C Recommendation, "Namespaces in XML," 14 January 1999.
[RFC2822]: IETF Request for Comments, (Obsoletes 822) "RFC2822 ," April 2001.
[soap-media-type]: IETF "INTERNET DRAFT: The 'application/soap+xml' media type", M. Baker, M. Nottingham, January 14, 2002. (Work in progress). (See http://www.ietf.org/internet-drafts/draft-baker-soap-media-reg-00.txt.)
[xml-1]: W3C Recommendation "Extensible Markup Language (XML) 1.0 (Second Edition)," Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 6 October 2000.