Transport Message Exchange Pattern: Single-Request-Response

[Ed. Note: The use of single here is to capture the notion that this there is to be no implied timing relationship between contemporaneous exchanges conforming to this transport exchange pattern, ie. nothing can be said about the relative temporal ordering of the transmission and reception of messages arising from distinct exchanges. Might rename Independent-Request-Response. Single could be misinterpreted as just 1 response or a unicast pattern (both of which happen to be the case but are not the motivation for the prefix)]

Status

This is an attempt of a write-up of a request-response message exchange pattern description based on discussions within the XML Protocol WG TBTF. The document has no status whatsoever nor does it necessarily represent consensus within the TBTF or within the XML Protocol WG as a whole.

Message Exchange Pattern Name

This message exchange pattern is named by the URI

http://www.w3.org/2001/09/soap/transport-mep/single-request-response/ abbreviated to single-request-response throughout this document.

Transport binding specifications may use the full-name of this transport message exchange pattern to declare their support for the transport message exchange pattern and associated semantics described herein.

Property naming Convention

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.

Standard Prefix Mappings

The following are standard prefix mappings which we assume to hold throughout this document.

Informal Description

The single-request-response transport message exchange pattern defines a pattern for the exchange of two messages between two adjacent SOAP nodes along a SOAP Message Path. One message is exchanged in each direction between a Requesting SOAP Node and a Responding SOAP Node. 

The normal operation of a message exchange conforming to the single-request-response exchange pattern is such that a Request Message  is first transferred from Requesting SOAP Node to Responding SOAP Node. Following the successful processing of the Request Message by the Responding SOAP Node, a Response Message is then transferred from Responding SOAP Node to Requesting SOAP Node. 

Abnormal operation of a message exchange conforming to the single-request-response exchange pattern may arise due to a failure to transfer the Request Message, a failure at the Responding SOAP Node to process the Request Message, or a failure to transfer the Response Message. Such failures MAY be silent at requesting, responding or both SOAP Node involved in the exchange. Also, under abnormal operation each SOAP Node involved in the message exchange MAY differ in their determination of the successful completion of the message exchange.

Formal Description

[Ed.Note This is intended as a logical description of the operation of this MEP. It is not intended to describe a real implementation or to imply that a real implementation should be structured.]

To initiate an transport message exchange conforming to the single-request-response transport message exchange pattern, the Requesting SOAP Node instantiates a local transport message exchange context. This context is initialised as follows:

In addition other properties related to the operation of features to be used in conjunction with this particular instance of the transport message exchange are initialised in accordance with the relevant feature specification.

Once initialised control of the transport message exchange context is passed to a (conforming) local binding instance.

The diagram below shows the logical state transitions at requesting and responding SOAP Nodes during the lifetime of the message exchange. At each SOAP Node the value of the single:State property is updated (logically) to reflect the current state of the message exchange as perceived by the local binding instance. These state names are relative URIs, relative to a Base URI value carried in the single:Role property of the local transport message exchange context.

At the Responding SOAP Node a transport message exchange context is (logically) instantiated by the local binding instance when it starts to receive an inbound Request Message.

[Ed Node: The initial value for single:State feels a bit awkward. generally when a Message start to be received the transport-mep in operation may not be known in which case the intial receiving state cannot be scoped by mep name or node role with respect to the exchange.]

State Transition Tables

[Ed.Note Incomplete tables for illustrative purposes]

Requesting SOAP Node State Transition Table

Responding SOAP Node State Transition Table

Fault Handling

During the operation of the single-request-response transport message exchange pattern, the participating SOAP Nodes may generate SOAP Faults.

If a SOAP Fault is generated during the processing of a Request Message then relaying of that message toward ultimate Responding SOAP Node should be terminated and the generated SOAP Fault should be propagated toward the initial Requesting SOAP Node in place of the Response Message.

If a SOAP Fault is generated during the processing of a Response Message then the generated SOAP Fault should be propagated toward the initial Requesting SOAP Node in place of the Response Message.

[skw] This may be overly prescriptive, but it seems like a good starting point. Extensions like SOAP-RP and ebXML may modify Fault Handling behaviour.

Operation Through SOAP Intermediaries (Informal)

The single-request-response transport message exchange pattern can be extended over multiple transport binding hops to form an extended single-request-response transport message exchange with a SOAP message path that extends through multiple SOAP intermediaries.

By default, Response Message follow the same set of hops between SOAP Nodes as the Request Message, but in reverse order. Specific SOAP extensions (eg. SOAP-RP) may modify this default behaviour.

A Request Message received by a SOAP Intermediary may be processed and forwarded toward an ultimate Responding SOAP Node. By default, a Response Message SHOULD NOT be returned toward the initial Requesting SOAP Node until a Response Message has been received (and possibly processed) at the SOAP Intermediary.

A failure by a SOAP Intermediary to forward a Request Message or to receive a Response Message MAY result in the generation of a SOAP Fault at the SOAP Intermediary.

Operation Through SOAP Intermediaries (Formal)

TBD

[The remaining text may serve as useful backgrond, but is not part of this MEP description. It has not been maintained in sync with the above and associated bindings]

Transport Binding Framework Assumptions

[This section does not form part of the description of a Transport Message Exchange Pattern. It's purpose is to elaborate on the assumptions I am making in the transport mep description proposed below. With direction some of this might be suitable for inclusion in the TB Framework, but it is not being written for that purpose at this time. It is more an an attempt to be explicit about the mental model I am working with.]

The diagram below is based on the diagram in the framework document (http://www.w3.org/2000/xp/Group/1/08/31/). In part this formulation tries to address Doug's concern from the F2F that not all properties travel up and down the stack with the message.

Properties, Features and Property Containers

We have had some discussion of what constitutes a message and what is its relationship to properties and features. The view advanced here is that a message is an abstraction of the information that one SOAP Node wishes to exchange with another SOAP Node according to some message exchange pattern and with some specified set of features engaged for the message exchange. In this regard there is information that is essential to enable the exchange of the message that is not part of the message itself, sometime called message meta-data. The message itself and the various information items (that enable features) are abstracted as properties. Some properties are scoped per message exchange (for example the message itself) while others have more global significance within the SOAP Node. The value of some properties arise directly from the operation of the SOAP Node and the operation of message exchanges and features. Others arise in implementation specific ways from the local environment. In the diagram, Environment is some partition of the property space intended as a container for those properties that are NOT scoped on a per-message or per-message-exchange basis. It provides a view onto relevant properties that may be useful in the provision of various features eg,. userIds, passwords, key and certificates for authentication and privacy features. The view provided by the Environment may depend on a variety of local circumstances in system dependent ways - eg the visible UserID, password, key and certificate stores could be influenced by the OS user Id on whose behalf a message exchange is being executed. Such local matters are well outside the scope of the binding framework - however the nature of the abstract projection of such information as properties is not.

Similarly, Transport Message Exchange Context denotes a property container that carries all the properties that are particular to a specific instance of a message exchange, a message exchange being the thing that a message exchange pattern is a template for. Both Environment and Transport Exchange Message Context are property containers. Properties are named by URI. The definition of the semantics of a given named property will describe its intended use and (abstract) value range (which may be open). The value of a property may also be named (by URI) or simply be a literal whose semantics are determined by the value of other properties  - eg. the name of a state on a state transition table or graph may be scoped by the name of a message exchange pattern in use and the role that a given node is playing with respect to that message exchange pattern. Likewise the value that  a role property may take is potentially scoped by the message exchange pattern in force.

Having abstracted messages that are the subject of a message exchange as parameters it should be noted that the value of such parameters abstracts an XML Infoset representing a SOAP Envelope and its contents and an abstraction of any other information structures (sometimes called Attachments) that are transferred along with the SOAP Envelope by the action of the message exchange.

There is a important point here in that we are dealing with properties that have both names and values. In many cases the property name is expected to be defined as part of the binding framework, whereas the semantics of the property value may be the subject of the definition of a particular message exchange pattern. Likewise, with features, some properties eg. MsgID, may be of utility to more than one feature (eg transaction support, message correlation). In some cases the definition of a TMEP or some other feature may introduce properties whose sole utility is with respect to that TMEP or feature such that the value space and semantics of the property are in some sense closed. However, in other cases the purpose of a property (it's coarse semantics) is defined, but its value space is open, and there may be more fine grained semantics associated with particular values - eg. the state of a particular message exchange.

We leave it open (at least for now) whether a property may appear multiple times within a given container and also within both a transport message exchange context and within the Environment container. The definition of a given property should indicate the significance of any multiple assertions and any precedence rules associated with simultaneous assertions in multiple containers.

[We might want to more deeply structure the environment to provide for per binding instance property containers and other classes of property containers - however, here they are all just lumped as the environment].

Framework Property Definitions in support of the Definition of Transport Message Exchange Patterns

[Design Note: the design here is that the names of these properties are defined by the framework. The value spaces of many of these properties are URIs and the semantics of particular values are defined in transport message exchange pattern specifications. An alternate design would be for the property names as well as property values to be pattern specific in some cases. This was rejected because it would make generic description of the operation of a transport MEP more complex... for instance you couldn't speak of setting the ...Context/CurrentMessage property, instead it would be the http://www.w3.org/.../mep/single-request-response/RequestMessage property. This would push mean that more of the structure of a particular type of message exchange pattern would have to be exposed higher up. Its a design option we could persue... but its not the one presented here. Another alternate design would be to model a property container as an XML document/infoset. In this case properties get represented by element names and value constraints could be expressed in schema. There is perhaps some merit in this approach to... however it would take us down a path of developing a concrete syntax for an abstract property container that is unlikely every to be instantiated as an XML infoset in any real implementation. Also, the content model for the CurrentMessage property would likely be problematic (because it contains an XML Infoset representing a SOAP Envelope and potential an an abstract structure representing some arbitrarily interlinked attachments)]

Operational Model

[This is an abstract description... it is a model... it is not a prescription or recipe for how to build and implementation... its is a framework for a behavioural description of a what an implementation is required to do - and only then is as much as its behaviour is externally visible.]

A SOAP node initiates a transport message exchange by bringing a Transport Message Exchange Context into existence. Into this newly created context it instantiates all the properties necessary to engage the various features to be associated with the message exchange and to select the transport message exchange pattern for that exchange. The initiator of a transport message exchange is the party that sends the first message associated with the exchange. This initial message is carried in one of the properties of the transport message exchange context. Control of the transport message exchange context is passed to the a binding instance that supports the required message exchange pattern and feature set. The binding is then responsible for honouring the semantics of the transport message exchange pattern and the engaged feature set (possibly through delegation to other entities we have so far termed nested bindings). Throughout the progress of the transport message exchange the binding maintains the transport message exchange context in a consistent state, which may include the updating or replacement of a value held in a property. Throughout the progress of a transport message exchange the current state of the transport message exchange context is available for inspection by the local SOAP Node. Logically, once the transport message exchange completes, the associated transport message exchange context persists indefinitely - practically of course the resources associated with the context get recycled once they are of no further use, but that strays across the line into implementation!

A SOAP node that receives the initial message of a transport message exchange similarly instantiates a Transport Message Exchange Context to represent progress of the message exchange at that node. At some stage in the progress of the message exchange the binding must be able to determine the transport message exchange pattern in use and the active feature set associated with the message exchange.

All nodes involved in a transport message exchange may make reference to and update property values held in the appropriate local transport message exchange context and the local environment, subject to the semantics of the property and to any locally applies property access restrictions (no intent to model these, only to acknowledge the possibility that the environment might reject change or access to properties). 

Summary

• A transport message exchange pattern is a template for the exchange of messages between SOAP Nodes supported by one or more transport bindings instances.
  In general the definition of a transport message exchange pattern:
  • describes the lifecycle of an transport message exchange conforming to the pattern;
  • describes the temporal/causal relationships of multiple messages exchanged in conformance with the pattern;
  • describes the normal and abnormal termination of a message exchange conforming to the pattern.
• Transport binding specifications may declare their support for one or more named transport message exchange patterns.
• Transport message exchange patterns are named by URI.
• A transport message exchange has a lifecycle governed by a transport message exchange pattern.
• The state of a transport message exchange is modelled locally by a property container associated with that instance of message exchange.
• Properties associated with the provision of transport message exchange patterns and features are instantiated in property containers.
• Property containers may be associated with the local Node as a whole and/or with particular instances of a transport message exchange.

[What follows from here is intended to be a reasonable concrete specification of one abstract message exchange pattern - subject to the assumptions about the framework presented above]