This section describes the status of this document at the time of its publication. Other documents may supersede this document. ThestatusdocumentseriesismaintainedatW3C.
This document is a Proposed Edited Recommendation of the W3C.
It updates the original Recommendation by the inclusion of the errata.
Changes between these two versions are described in a
diff document.
Additionally, it incorporates changes to the SOAP Request Response Message
Exchange pattern (MEP) to permit the SOAP envelope in the response to be
optional, to allow for one-way message interactions.
This document has been produced by the XML Protocol Working Group, which
is part of the Web Services
Activity.
IthasbeenreviewedbyW3CMembersandotherinterestedparties,andhasbeenendorsedbytheDirectorRecommendation.Itstableusedasreferencematerialcitedasanormativereferencefromanotherdocument.W3C'sroleinmakingtheRecommendationdrawattention
W3C Advisory Committee Representatives are invited to submit their formal review per the specificationandtopromoteitswidespreaddeployment.ThisenhancesfunctionalityandinteroperabilityWeb.Commentsonthisdocumentwelcome.Pleasethem
Informationaboutimplementationsrelevant
Members of the W3C Advisory Committee will find the appropriate review form for this specification
SOAP Version 1.2 supercedes all previous versions of SOAP, including SOAP Version 1.1 [SOAP 1.1]
The SOAP 1.2 Implementation Report can be found intheImplementationReportPatentdisclosuresrelevanttothisspecificationmaybefoundonWorkingGroup's
This document is governed by the 24 January 2002 CPP as amended by the W3C Patent Policy Transition Procedure. W3C maintains a public list of any patent disclosure,conformancepolicy.
A list of current W3C Recommendations and
other technical reports can be found at http://www.w3.org/TR.
1. Introduction
SOAP Version 1.2 (SOAP) is a lightweight protocol intended
for exchange of structured information in a
decentralized, distributed environment. The SOAP specification
consists of three parts. Part 2 (this document)
defines a set of adjuncts that MAY be used with the SOAP
messaging framework:
-
The SOAP Data Model represents application-defined data structures and values
as a directed, edge-labeled graph of nodes (see 2. SOAP Data Model).
-
The SOAP Encoding defines a set of rules for encoding
instances of data that conform to the SOAP Data Model for
inclusion in SOAP messages (see 3. SOAP Encoding).
-
The SOAP RPC Representation defines a convention for how
to use the SOAP Data Model for representing RPC calls and
responses (see 4. SOAP RPC Representation).
-
The section for describing features and bindings defines
a convention for describing features and binding in terms
of properties and property values (see 5. A Convention for Describing Features and Bindings).
-
The section on SOAP-Supplied Message Exchange
Patterns and Features defines a request response
message exchange pattern and a message exchange
pattern supporting non-SOAP requests for SOAP
responses, (see 6. SOAP-Supplied Message Exchange Patterns and Features).
-
The SOAP Web Method feature defines a feature for
control of methods used on the World Wide Web (see
6.4 SOAP Web Method Feature).
-
The SOAP HTTP Binding defines a binding of SOAP
to HTTP (see [RFC 2616]) following the
rules of the SOAP Protocol
Binding Framework, [SOAP Part 1] (see 7. SOAP HTTP Binding).
SOAP 1.2 Part 0 [SOAP Part 0] is a non-normative document intended to
provide an easily understandable tutorial on the features of the SOAP Version
1.2 specifications.
SOAP 1.2 Part 1 [SOAP Part 1] defines the SOAP messaging
framework.
Note:
In previous versions of this specification the SOAP
name was an acronym. This is no longer the case.
1.1 Notational Conventions
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL",
"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
and "OPTIONAL" in this document are to be interpreted as
described in RFC 2119 [RFC 2119].
This specification uses a number of namespace prefixes throughout; they
are listed in Table 1. Note that the choice of any namespace
prefix is arbitrary and not semantically significant (see XML Infoset [XML InfoSet]).
Namespace names of the general form "http://example.org/..."
and "http://example.com/..." represent
application or context-dependent URIs (see RFC 23962396]
This specification uses the Extended Backus-Naur Form
(EBNF) as described in XML 1.0 [XML 1.0].
With the exception of examples and sections explicitly marked
as "Non-Normative", all parts of this specification are
normative.
2. SOAP Data Model
The SOAP Data Model represents application-defined data
structures and values as a directed edge-labeled graph of nodes.
Components of this graph are described in the following
sections.
The purpose of the SOAP Data Model is to provide a mapping
of non-XML based data to some wire representation. It is important
to note that use of the SOAP Data Model, the accompanying SOAP
Encoding (see 3. SOAP Encoding), and/or the SOAP RPC
Representation (see 4. SOAP RPC Representation) is
OPTIONAL. Applications which already model data in XML may not need to use the SOAP
Data Model. Due to their optional nature, it is NOT a
requirement to implement the SOAP Data Model, the SOAP
Encoding and/or the SOAP RPC Representation as part of a
SOAP node.
2.1 Graph Edges
Edges in the graph are said to originate at a
graph node
and terminate at a graph node. An edge that
originates at a graph
node is known as an outbound edge with respect to that
graph node. An edge that terminates at a graph node is known as an inbound
edge with respect to that graph node. An edge MAY originate and
terminate at the same graph node. An edge MAY
have only an originating graph node, that is be outbound only. An edge MAY have only a
terminating graph node, that is be inbound only.
The outbound edges of a given graph node MAY be
distinguished by label or by position. Position
is a total order on such edges; thus, if any
outbound edges from a given node are distinguished by
position, then all outbound edges from that node are so distinguished.
2.1.1 Edge labels
An edge label is an XML qualified name. Two edge
labels are equal if and only if their XML expanded names are
equal. I.e.
-
Their local name values are the same.
-
Either of the following is true:
-
Both of their namespace name values are missing.
-
Their namespace name values are both present and are
both the same.
See 2.3 Values for uses of edge labels and position
to distinguish the members of encoded values, and
XML Schema [XML Schema Part 2] for more
information about comparing XML qualified names.
2.2 Graph Nodes
A graph node has zero or more outbound edges. A graph node that has no
outbound edges has an optional lexical value. All graph nodes have an
optional type name of type xs:QName in the namespace named
"http://www.w3.org/2001/XMLSchema" (see
XML Schema [XML Schema Part 2]).
2.2.1 Single and Multi Reference Nodes
A graph node may be single reference or
multi reference. A
single reference graph node has a single inbound edge. A multi
reference graph node has multiple inbound edges.
2.3 Values
A simple value is represented as a graph node with a lexical value.
A compound value is represented as a graph node with zero or more
outbound edges as follows:
-
A graph node whose outbound edges are distinguished solely
by their labels is known as a "struct". The outbound edges
of a struct MUST be labeled with distinct names (see
2.1.1 Edge labels).
-
A graph node whose outbound edges are distinguished solely
by position is known as an "array". The outbound edges of
an array MUST NOT be labeled.
3. SOAP Encoding
SOAP Encoding provides a means of encoding instances of data
that conform to the data model described in 2. SOAP Data Model. This encoding
MAY be used to transmit data in SOAP header blocks and/or SOAP
bodies. Other data models, alternate encodings of the SOAP
Data Model as well as unencoded data MAY also be used in SOAP
messages (see SOAP 1.2 Part 1 [SOAP Part 1],
SOAP
encodingStyle Attribute for specification of alternative
encoding styles and see 4. SOAP RPC Representation for
restrictions on data models and encodings used to represent SOAP
Remote Procedure Calls (RPC)).
The serialization rules defined in this section are
identified by the URI
"http://www.w3.org/2003/05/soap-encoding". SOAP
messages using this particular serialization SHOULD indicate
that fact by using the SOAP encodingStyle attribute
information item (see SOAP 1.2 Part 1 [SOAP Part 1]
SOAP
encodingStyle Attribute).
3.1 Mapping between XML and the SOAP Data Model
XML allows very flexible encoding of data. SOAP Encoding
defines a narrower set of rules for encoding the graphs
described in 2. SOAP Data Model. This section
defines the encoding at a high level, and the subsequent
sub-sections describe the encoding rules in more detail. The
encodings described in this
section can be used in conjunction with the mapping of RPC
requests and responses specified in 4. SOAP RPC Representation.
The encodings are described below from the perspective of a
de-serializer. In each case, the presence of an XML
serialization is presumed, and the mapping to a corresponding
graph is described.
More than one encoding is typically possible
for a given graph. When serializing a graph for transmission
inside a SOAP message,
a representation that deserializes to the identical graph MUST
be used; when multiple such representations are possible, any
of them MAY be used. When receiving an encoded SOAP message,
all representations MUST be accepted.
3.1.1 Encoding Graph Edges and Nodes
Each graph edge is encoded as an element information
item and each element information item
represents a graph edge. 3.1.3 Encoding Compound Values
describes the relationship between edge labels and the [local name] and
[namespace name] properties of such element
information items.
The graph node at which an edge terminates is
determined by examination of the serialized XML as follows:
-
If the element information item representing
the edge does not have a ref attribute
information item (see 3.1.5.2 ref Attribute Information Item)
among its attributes then that element information
item is said to represent a node in
the graph and the edge terminates at that node.
In such cases the element
information item represents both a graph edge
and a graph node
-
If the element information item representing
the edge does have a ref attribute
information item (see 3.1.5.2 ref Attribute Information Item) among its attributes,
then the value of that attribute information
item MUST be identical to the value of exactly one
id attribute information item (
see 3.1.5.1 id Attribute Information Item) in the same envelope.
In this case the edge terminates at the graph node
represented by the element information item
on which the id attribute information
item appears. That element information
item MUST be in the scope of an
encodingStyle attribute with a value of
"http://www.w3.org/2003/05/soap-encoding"
(see SOAP 1.2 Part 1 [SOAP Part 1],
SOAP encodingStyle
Attribute).
All nodes in the graph are encoded as described in 1
above. Additional inbound edges for multi reference graph nodes
are encoded as described in 2 above.
3.1.2 Encoding Simple Values
The lexical
value of a graph node representing a simple value is the sequence of
Unicode characters identified by the character
information item children of the element
information item representing that node.
The element information item representing a simple value node MAY have
among its attributes a 'nodeType' attribute information item (see 3.1.7 nodeType Attribute Information Item).
Note that
certain Unicode characters cannot be represented in XML (see XML 1.0 [XML 1.0]).
3.1.3 Encoding Compound Values
An outbound edge of a graph node is encoded as an
element information item child of the
element information item that represents the
node (see 3.1.1 Encoding Graph Edges and Nodes).
Particular rules apply depending on what kind of compound
value the graph node represents. These rules are as follows:
-
For a graph edge which is distinguished by label, the [local name] and
[namespace name] properties of the child
element information item
together determine the value of the edge
label.
-
For a graph edge which is distinguished by position:
-
The ordinal position of the graph edge corresponds
to the position of the child element information
item relative to its siblings
-
The [local name] and [namespace name]
properties of the child element information
item are not significant.
-
The element information item representing a compound
value node MAY have among its attributes a
nodeType attribute information
item (see 3.1.7 nodeType Attribute Information Item).
-
The following rules apply to the encoding of a graph node that
represents an "array":
-
If a graph edge does not terminate in a graph node then
it can either be omitted from the serialization or it can be
encoded as an element information item
with an xsi:nil attribute
information item whose value is "true".
3.1.4 Computing the Type Name Property
The type name property of a graph node is a {namespace name,
local name} pair computed as follows:
-
If the element information item representing the
graph node has an xsi:type attribute
information item
among its attributes then the type name property of the
graph node is the value of the xsi:type attribute
information item.
Note:
This attribute is of type xs:QName (see
XML Schema [XML Schema Part 2]); its value consists of the
pair {namespace name, local name}. Neither the prefix used to
construct the QName nor any information relating to any
definition of the type is considered to be part of the
value. The SOAP graph carries only the qualified name of the
type.
-
Otherwise if the parent element information item of the
element information item representing the graph
node has an enc:itemType attribute
information item (see 3.1.4.1 itemType Attribute Information Item)
among its attributes then the type
name property of the graph node is the value of the
enc:itemType attribute information item
-
Otherwise the value of the type name property of the graph
node is unspecified.
Note:
These rules define how the type name property
of a graph node in
a graph is computed from a serialized encoding. This
specification does not mandate validation using any particular
schema language or type system. Nor does it include built in types or
provide any standardized faults to reflect value/type
name conflicts.
However, nothing prohibits development of
additional specifications to describe the use of SOAP Encoding with
particular schema languages or type systems. Such additional
specifications MAY mandate validation using particular
schema language, and MAY specify faults to be generated if
validation fails. Such additional specifications MAY specify
augmentations to the deserialized graph based on information
determined from such a validation. The use by SOAP Encoding of xsi:type
is intended to facilitate integration with the W3C XML Schema
language (see C. Using W3C XML Schema with SOAP Encoding). Other XML based
schema languages, data schemas and programmatic type systems
MAY be used but only to the extent that they are compatible
with the serialization described in this specification.
3.1.4.1 itemType Attribute Information Item
The itemType attribute information item has
the following Infoset properties:
-
A [local name] of itemType .
-
A [namespace name] of "http://www.w3.org/2003/05/soap-encoding".
-
A [specified] property with a value of "true".
The type of the itemType attribute
information item is xs:QName.
The value of the itemType attribute
information item is used to compute the type name
property (see 3.1.4 Computing the Type Name Property) of members of
an array.
3.1.5 Unique identifiers
3.1.5.1 id Attribute Information Item
The id attribute information item has
the following Infoset properties:
The type of the id attribute
information item is xs:ID.
The value of the id attribute information
item is a unique identifier that can be referred to by
a ref attribute information item
(see 3.1.5.2 ref Attribute Information Item).
3.1.5.2 ref Attribute Information Item
The ref attribute information item has
the following Infoset properties:
The type of the ref attribute information
item is xs:IDREF.
The value of the ref attribute information
item is a reference to a unique identifier defined
by an id attribute information item
(see 3.1.5.1 id Attribute Information Item).
3.1.5.3 Constraints on id and ref Attribute Information
Items
The value of a ref attribute information item MUST also be
the value of exactly one id attribute information item.
A ref attribute information item and
an id attribute information item
MUST NOT appear on the same element information item.
3.1.6 arraySize Attribute Information Item
The arraySize attribute information item has
the following Infoset properties:
The type of the arraySize attribute
information item is enc:arraySize.
The value of the arraySize attribute information item
MUST conform to the following EBNF grammar
[1] | arraySizeValue | ::= | ("*" | concreteSize) nextConcreteSize* |
[2] | nextConcreteSize | ::= | whitespace concreteSize |
[3] | concreteSize | ::= | [0-9]+ |
[4] | white space | ::= | (#x20 | #x9 | #xD | #xA)+ |
The array'sdimensionsarerepresentedbyeachiteminthelistofsizes(unspecifiedsizeincasetheasterisk).numberitemsindimensionsinarray.Theasterisk,ifpresent,MUSTappearpositionarraySize attribute information item is
"*", thatisbydefaultarraysareconsideredtohavesize.
3.1.7 nodeType Attribute Information Item
The nodeType attribute information item has
the following Infoset properties:
-
A [local name] of nodeType .
-
A [namespace name] of "http://www.w3.org/2003/05/soap-encoding".
-
A [specified] property with a value of
"true".
The type of the nodeType attribute
information item is enc:nodeType.
The value of the nodeType attribute information item
MUST, if present, be one of the strings "simple" or "struct" or "array". The value
indicates what kind of a value this node represents - a simple value, a
compound struct value or a compound array value respectively.
3.2 Decoding Faults
During deserialization a SOAP receiver:
-
SHOULD generate an "env:Sender" SOAP
fault with a subcode of enc:MissingID
if the message contains a ref attribute
information item but no corresponding id
attribute information item (see 3.1.5.3 Constraints on id and ref Attribute Information
Items).
-
SHOULD generate an "env:Sender" SOAP
fault with a subcode of enc:DuplicateID
if the message contains two or more id attribute
information item that have the same value. (see 3.1.5.3 Constraints on id and ref Attribute Information
Items).
-
MAY generate an "env:Sender" SOAP fault with a
subcode of enc:UntypedValue if the type name
property of an encoded graph node is unspecified.
4. SOAP RPC Representation
One of the design goals of SOAP is to facilitate
the exchange of messages that map conveniently to definitions
and invocations of methodprocedurecallsplatformindependent
As mentioned in section 2. SOAP Data Model, use and
implementation of the SOAP RPC Representation is OPTIONAL.
The SOAP encodingStyle attribute information item (see
SOAP 1.2 Part 1 [SOAP Part 1] SOAP encodingStyle
Attribute) is used to indicate the encoding style of
the RPC representation. The encoding thus specified MUST support the 2. SOAP Data Model. The encoding style defined in 3. SOAP Encoding supports such constructs and is therefore
suitable for use with the SOAP RPC Representation.
This SOAP RPC Representation is not predicated on any SOAP
protocol binding. When SOAP is bound to HTTP, an RPC invocation
maps naturally to an HTTP request and an RPC response maps to an
HTTP response. (see 7. SOAP HTTP Binding). However, the
SOAP RPC Representation is not limited to the SOAP HTTP Binding.
To invoke an RPC, the following information is needed:
The address of the target SOAP node.
A procedure or method name.
-
The identities
and values of any arguments to be passed to the procedure or method. Arguments used to
identify Web resources SHOULD be distinguished from those representing data or control information (see
4.1.1 Identification of RPC Resources.)
-
Values for properties as required by any features of the
binding to be used. For example, "GET" or "POST"
for the http://www.w3.org/2003/05/soap/features/web-method/Method property of the 6.4 SOAP Web Method Feature.
Optional header data.
SOAP RPC relies on the protocol binding to provide a mechanism
for carrying the URI of the target SOAP node. For HTTP the request URI
indicates the resource against which the invocation is being
made. Other than requiring it to be a valid URI, SOAP places no
restriction on the form of an identifier (see RFC 23962396]
The SOAP RPC Representation employs the 6.2 SOAP Request-Response Message Exchange Pattern and 6.3 SOAP Response Message Exchange Pattern. Use of the SOAP RPC Representation with other MEPs MAY be possible, but is beyond the
scope of this specification.
4.1 Use of RPC on the World Wide Web
The following guidelines SHOULD be followed when deploying
SOAP RPC applications
on the World Wide Web.
4.1.1 Identification of RPC Resources
The World Wide Web identifies resources with URIs, but common programming conventions convey identification information in the arguments to
procedures, or in the names of those procedures. For example, the call:
updateQuantityInStock(PartNumber="123", NewQuantity="200")
suggests that the resource to be
updated is the QuantityInStock for PartNumber "123".
Accordingly, when mapping to
or from a programming language method or procedurecall,procedurecall,
Note:
Conventions for specific URI encodings of procedure
names and arguments, as well as for controlling the
inclusion of such arguments in the SOAP RPC body could be established in conjunction with the development
of Web Service interface description languages. They could be developed when SOAP is bound to particular
programming languages or could be established on an application
4.1.2 Distinguishing Resource Retrievals from other RPCs
The World Wide Web depends on mechanisms that optimize commonly performed information retrieval
tasks. Specifically, protocols such as HTTP [RFC 2616] provide a GET method which is
used to perform safe
retrievals, i.e.
Certain procedure or method calls represent requests for information retrieval. For example, the call:
getQuantityInStock(PartNumber="123")
might be used to retrieve the quantity established in
the example above.
The following conventions can be employed to implement SOAP retrievals and other
RPCs on the Web:
The SOAP RPC Representation does not define any other value for the
http://www.w3.org/2003/05/soap/features/web-method/Method .
4.2 RPC and SOAP Body
RPC invocations (except for safe retrievals: see 4.1.2 Distinguishing Resource Retrievals from other RPCs) and responses are both carried in the
SOAP Body element (see SOAP 1.2 Part 1 [SOAP Part 1] SOAP Body) using the
following representation:
4.2.1 RPC Invocation
An RPC invocation is modeled as follows:
Applications MAY process invocations with missing
parameters but also MAY fail to process the invocation and return a fault.
4.2.2 RPC Response
An RPC response is modeled as follows:
The response is represented by a single struct
containing an outbound edge for the return value and each [out]
or [in/out] parameter. The name of the struct is not significant.
Each parameter is represented by an outbound edge
with a label corresponding to the name of the parameter. The conventions of
B. Mapping ApplicationDefined
A non-void return value is represented as follows:
-
There MUST be an outbound edge with a local name of result and a namespace
name of "http://www.w3.org/2003/05/soap-rpc"
which terminates in a terminal node
-
The type of that terminal node is a xs:QName and its value
is the name of the outbound edge which terminates in the
actual return value.
If the return value of the procedure is void
then an outbound edge with a local name of result and a namespace
name of "http://www.w3.org/2003/05/soap-rpc"
MUST NOT be present.
Invocation faults are handled according to the
rules in 4.4 RPC Faults. If a protocol binding
adds additional rules for fault expression, those MUST also
be followed.
4.2.3 SOAP Encoding Restriction
When using SOAP encoding (see 3. SOAP Encoding) in
conjunction with the RPC convention described here, the SOAP
Body MUST contain only a single child element
information item, that child being the serialized RPC
invocation or response struct.
4.3 RPC and SOAP Header
Additional information relevant to the encoding of an RPC
invocation but not part of the formal procedure or method
signature MAY be expressed in a SOAP envelope carrying an RPC invocation or response.
Such additional information MUST be expressed as SOAP header blocks.
4.4 RPC Faults
The SOAP RPC Representation introduces additional SOAP fault
subcode values to be used in conjunction with the fault codes
described in SOAP 1.2 Part 1 [SOAP Part 1] SOAP Fault Codes.
Errors arising during RPC invocations are reported
according to the following rules:
A fault with a Value of
Code set to "env:Receiver" SHOULD
be generated when the receiver cannot handle the message
because of some temporary condition, e.g. when it is out of
memory.
Note:
Throughout this document, the term "Value of
Code " is used as a shorthand for "value of
the Value child element information
item of the Code element
information item" (see SOAP 1.2 Part 1 [SOAP Part 1], SOAP Code
Element ).
-
A fault with a Value of Code
set to "env:DataEncodingUnknown"
SHOULD be generated when the arguments
are encoded in a data encoding unknown to the
receiver.
-
A fault with a Value of Code
set to "env:Sender" and a
Value of Subcode set to
"rpc:ProcedureNotPresent"
MAY be generated when the receiver
does not support the procedure or method specified.
Note:
Throughout this document, the term "Value of
Subcode " is used as a shorthand for "value of
the Value child element information
item of the Subcode element
information item" (see SOAP 1.2 Part 1 [SOAP Part 1], SOAP Subcode
element).
-
A fault with a Value of Code
set to "env:Sender" and a
Value of Subcode set to
"rpc:BadArguments"
MUST be generated when the receiver
cannot parse the arguments or when there is a
mismatch in number and/or type of the arguments
between what the receiver expects and what was
sent.
Other faults arising in an extension or from the
application SHOULD be generated as described in SOAP 1.2 Part 1 [SOAP Part 1] SOAP Fault Codes.
In all cases the values of the Detail and
Reason element information items
are implementationdefined.
Note:
Senders might receive different faults from
those listed above in response to an RPC invocation if the
receiver does not support the (optional) RPC convention described
here.
5. A Convention for Describing Features and Bindings
This section describes a convention describing Features (including
MEPs) and Bindings in terms of properties and property values. The
convention is sufficient to describe the distributed states of Feature
and Binding specifications as mandated by the Binding Framework (see
SOAP 1.2 Part 1 [SOAP Part 1] SOAP Protocol Binding
Framework) and it is used to describe a Request-Response MEP (see 6.2 SOAP Request-Response Message Exchange Pattern), a Response MEP (see 6.3 SOAP Response Message Exchange Pattern), the SOAP Web Method feature (see 6.4 SOAP Web Method Feature) and the SOAP HTTP Binding (see 7. SOAP HTTP Binding) elsewhere in this document. Along with the convention
itself, an informal model is defined that describes how properties
propagate through a SOAP system. Note that this model is intended to be
illustrative only, and is not meant to imply any constraints on the
structure or layering of any particular SOAP implementation.
5.1 Model and Properties
In general, a SOAP message is the information that one SOAP node wishes to
exchange with another SOAP node according to a particular set of features,
including a MEP. In addition, there may be information essential to exchanging
a message that is not part of the message itself. Such information is sometimes
called message metadata. In the model, the message, any message metadata,
and the various information items that enable features are represented as
abstractions called properties.
5.1.1 Properties
Under the convention, properties are represented as follows:
Properties are named with URIs.
Where appropriate, property values SHOULD have
an XML Schema [XML Schema Part 1] [XML Schema Part 2] type listed in the specification which
introduces the property.
5.1.2 Property Scope
Properties within a SOAP node differ in terms of their scope and the
origins of their values. As shown in the figure below, we make the
distinction between permessage-exchange
Figure 1: Model describing properties shared between SOAP and Binding
5.1.2.1 Message Exchange Context
A message exchange context is a collection of properties whose scope is
limited to an instance of a given message exchange pattern. An example
of a message exchange context property is the identifier of the message
exchange pattern in use.
5.1.2.2 Environment Context
The environmentcontextenvironmentcontext
The values of properties in Environment Context may depend upon local
circumstances (as depicted by the external arrow from Environment Context in
the figure above). More specifically, the properties in the example
could be influenced by an operating system user ID on whose behalf a
message exchange is being executed. The mapping of information in a
particular implementation to such properties is outside the scope of
the binding framework although the abstract representation of such
information as properties is not.
5.1.3 Properties and Features
A feature may be expressed through multiple properties and a single property
may enable more than one feature. For example, the properties called User ID and
Password may be used to enable a feature called Authentication. As a second example,
a single property called Message ID could be used to enable one feature called
Transaction and a second feature called Message Correlation.
6. SOAP-Supplied Message Exchange Patterns and Features
6.1 Property Conventions for SOAP Message Exchange Patterns
Table 2 describes the properties
(in accordance with the property naming conventions
defined in this document) that support the description of
message exchange patterns (MEPs). Other properties may
be involved in the specification of particular MEPs,
but the properties in this table are generally applicable to all MEPs.
Table 2: Property definitions supporting the description of MEPs
| Property Name |
Property Description |
Property Type |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/ExchangePatternName |
The name
of the MEP in
operation. |
xs:anyURI |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason |
A value that denotes a patternspecific,bindingindependentbindingspecific |
xs:anyURI |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role |
The identifier of the patternspecific |
xs:anyURI |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/State |
The identifier of the current state of the message
exchange. This value is managed by the binding
instance and may be inspected by other entities
monitoring the progress of the message
exchange. |
xs:anyURI |
6.2 SOAP Request-Response Message Exchange Pattern
This section defines the message exchange pattern (MEP) called "Request-Response". The
description is an abstract presentation of the operation of
this MEP. It is not intended to describe a real
implementation or to suggest how a real implementation should
be structured.
6.2.2 Description
The SOAP Request-Response MEP defines a
pattern for the exchange of a SOAP message acting as a
request followed by a SOAPSOAP
In the normal operation of a message exchange conforming to
the Request-Response MEP, a
request message is first transferred from the requesting SOAP
node to the responding SOAP node. Following the successful
processing of the request message by the responding SOAP node,
a response message is transferred from the responding
SOAP node to the requesting SOAP node.
Abnormal operation during a Request-Response message exchange
might be caused by 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 might be silent at either or both of the requesting and
responding SOAP nodes involved, or might result in the generation of a SOAP
or binding-specific fault (see 6.2.4 Fault Handling).
Also, during abnormal operation
each SOAP node involved in the message exchange might differ in
its determination of the successful completion of the message
exchange.
The scope of a Request-Response MEP is limited to
the exchange of a request message and a response message between
one requesting and one responding SOAP node. This pattern does
not mandate any correlation between multiple requests nor
specific timing for multiple requests. Implementations MAY choose
to support multiple ongoing requests (and associated response
processing) at the same time.
6.2.3 State Machine Description
The Request-Response MEP defines a set of properties described in Table 3.
Table 3: Property definitions for Request-Response MEP
| Property Name |
Property Description |
Property Type |
http://www.w3.org/2003/05/soap/mep/OutboundMessage |
An abstract structure that represents the current
outbound message in the message exchange. This
abstracts both SOAP Envelope and any other
information structures that are transferred along
with the envelope. |
Not specified |
http://www.w3.org/2003/05/soap/mep/InboundMessage |
An abstract structure that represents the current
inbound message in the message exchange. This
abstracts both SOAP Envelope and any other
information structures that are transferred along
with the envelope. |
Not specified |
http://www.w3.org/2003/05/soap/mep/ImmediateDestination |
The identifier of the immediate destination of an
outbound message. |
xs:anyURI |
http://www.w3.org/2003/05/soap/mep/ImmediateSender |
The identifier of the immediate sender of an inbound
message. |
xs:anyURI |
To initiate a message exchange conforming to the
Request-Response MEP, the requesting SOAP node instantiates a
local message exchange context. Table 4 describes how
the context is initialized.
Table 4: Instantiation of a Message Exchange Context
for a requesting SOAP node
| Property Name |
Property Value |
Notes |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/ExchangePatternName |
"http://www.w3.org/2003/05/soap/mep/request-response/"
|
|
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason |
"None" |
A relative URI whosebaseURIisthevalueofhttp://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/ExchangePatternNamehttp://www.w3.org/2002/12/soap/bindingFramework/ExchangeContext/ExchangePatternName |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role |
"RequestingSOAPNode/" |
A relative URI whosebaseURIisthevalueofhttp://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/ExchangePatternNamehttp://www.w3.org/2002/12/soap/bindingFramework/ExchangeContext/ExchangePatternName |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/State |
"Init" |
A relative URI whosebaseURIisthevalueofhttp://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Rolehttp://www.w3.org/2002/12/soap/bindingFramework/ExchangeContext/Role |
http://www.w3.org/2003/05/soap/mep/OutboundMessage |
An abstraction of the request message |
|
http://www.w3.org/2003/05/soap/mep/ImmediateDestination |
An identifier (URI) that denotes the responding SOAP node |
|
There may be other properties related to the operation of
the message exchange context instance. Such properties are
initialized according to their own feature specifications.
Once the message exchange context is initialized, control
of the context is passed to a (conforming) local binding
instance.
The diagram below shows the logical state transitions at
the requesting and responding SOAP nodes during the lifetime
of the message exchange. At each SOAP node, the local binding
instance updates (logically) the value of the
http://www.w3.org/2003/05/soap/bindingFramework/
ExchangeContext/State property to reflect the current
state of the message exchange. The state names are relative
URIs, relative to a base URI value carried in the
http://www.w3.org/2003/05/soap/bindingFramework/
ExchangeContext/Role property of the local message
exchange context.
Figure 2: Request-Response MEP State Transition Diagram.
When the local binding instance at the responding SOAP
node starts to receive an inbound request message, it
(logically) instantiates a message exchange context. Table 5
describes the properties that the binding initializes as
part of the context's instantiation.
Table 5: Instantiation of Message Exchange Context for
an inbound request message at a responding SOAP node
| Property Name |
Property Value |
Notes |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/ExchangePatternName |
"http://www.w3.org/2003/05/soap/mep/request-response/"
|
Initialized as early as possible during the life cycle
of the message exchange. |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason |
"None" |
A relative URI whosebaseURIisthevalueofhttp://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/ExchangePatternNamehttp://www.w3.org/2002/12/soap/bindingFramework/ExchangeContext/ExchangePatternName |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role |
"RespondingSOAPNode"
|
A relative URI whosebaseURIisthevalueofhttp://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/ExchangePatternNamehttp://www.w3.org/2002/12/soap/bindingFramework/ExchangeContext/ExchangePatternName
Initialized as early
as possible during the life cycle the message
exchange. |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/State |
"Init" |
A relative URI whosebaseURIisthevalueofhttp://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Rolehttp://www.w3.org/2002/12/soap/bindingFramework/ExchangeContext/Role |
When the requesting and responding SOAP nodes transition between
states, the local binding instance (logically) updates a number of
properties. Table 6 and Table 7 describe these updates for the requesting
and the responding SOAP nodes, respectively.
Table 6: Requesting SOAP Node State Transitions
| CurrentState |
Transition Condition |
NextState |
Action |
| "Init" |
Unconditional |
"Requesting" |
Initiate transmission of request message
abstracted in
http://www.w3.org/2003/05/soap/mep/OutboundMessage . |
| "Requesting" |
Message transmission failure |
"Fail" |
Set
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason to
"transmissionFailure" |
| Start receiving response message |
"Sending+Receiving" |
Set
http://www.w3.org/2003/05/soap/mep/ImmediateSender to denote the sender of the response message (may differ from the values in http://www.w3.org/2003/05/soap/mep/ImmediateDestination ).
Start making an abstraction of the response message available in http://www.w3.org/2003/05/soap/mep/InboundMessage . |
| "Sending+Receiving" |
Message exchange failure |
"Fail" |
Set
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason to
"exchangeFailure" |
| Completed sending request message. Completed receiving response message. |
"Success" |
http://www.w3.org/2003/05/soap/mep/InboundMessage ), then process it according to the SOAP processing model. |
Table 7: Responding SOAP Node State Transitions
| CurrentState |
Transition Condition |
NextState |
Action |
| "Init" |
Start receiving request message |
"Receiving" |
Set
http://www.w3.org/2003/05/soap/mep/ImmediateSender to denote the sender of the request message (if determinable).
Start making an abstraction of the request message available in http://www.w3.org/2003/05/soap/mep/InboundMessage .
Pass control of message exchange context to SOAP processor. Process the Inbound message according to the SOAP Processing model. |
| "Receiving" |
Message reception failure |
"Fail" |
Set
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason to
"receptionFailure". |
Start of response messagehttp://www.w3.org/2003/05/soap/mep/OutboundMessage |
"Receiving+Sending" |
Initiate transmission of response messagehttp://www.w3.org/2003/05/soap/mep/OutboundMessage . |
| "Receiving+Sending" |
Message exchange failure |
"Fail" |
Set http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason to
"exchangeFailure". |
| Completed receiving request message. Completed sending response message. |
"Success" |
|
Bindings that implement this MEP
MAY provide for streaming of SOAP responses.
That is, responding SOAP nodes MAY begin transmission
of a SOAP response while a SOAP request is still being
received and processed. When SOAP nodes implement
bindings that support streaming, the following
rules apply:
All the rules in SOAP 1.2 Part 1 [SOAP Part 1]
Binding
Framework regarding streaming of individual SOAP
messages MUST be obeyed for both request and response SOAP
messages.
When using streaming SOAP bindings, requesting SOAP nodes
MUST avoid deadlock by accepting and if necessary processing
SOAP response information while the SOAP request is being transmitted.
Note:
Depending on the implementation used and the size of
the messages involved, this rule MAY require that SOAP applications
stream application-level response processing in parallel with request
generation.
A requesting SOAP node MAY enter the "Fail" state,
and thus abort transmission of the outbound SOAP request,
based on information contained in an incoming streamed SOAP
response.
6.2.4 Fault Handling
During the operation of the Request-Response MEP, the
participating SOAP nodes may generate SOAP faults.
If a SOAP fault is generated by the responding SOAP node
while it is in the "Receiving" state, the SOAP
fault is made available in http://www.w3.org/2003/05/soap/mep/OutboundMessage and the
state machine transitions to the "Receiving+Sending" state.
This MEP makes no claims about the disposition or
handling of SOAP faults generated by the requesting SOAP node
during any processing of the response message that follows the
"Success" state in the requesting SOAP node's state transition
table (see Table 6).
6.3 SOAP Response Message Exchange Pattern
This section defines the message exchange pattern (MEP)
called "SOAP Response". The description is an abstract
presentation of the operation of this MEP. It is not intended to
describe a real implementation or to suggest how a real
implementation should be structured.
6.3.2 Description
The SOAP Response MEP defines a pattern for
the exchange of a non-SOAP message acting as a request
followed by a SOAP message acting as a response. In the
absence of failure in the underlying protocol, this MEP
consists of exactly two messages, only one of which is a
SOAP message:
-
A request
transmitted in a binding-specific manner that does not include a SOAP envelope and hence does not
involve any SOAP processing by the receiving SOAP node.
-
A response message which contains a SOAP
envelope. The MEP is completed by the processing of the SOAP envelope
following the rules of the SOAP processing model (see
SOAP 1.2 Part 1 [SOAP Part 1], section
SOAP Processing Model).
Abnormal operation during a SOAP Response message exchange might be
caused by a failure to transfer the request message or the
response message. Such failures might be silent at either or both
of the requesting and responding SOAP nodes involved, or might
result in the generation of a SOAP or binding-specific fault (see
section 6.3.4 Fault Handling). Also, during abnormal
operation each SOAP node involved in the message exchange might
differ in its determination of the successful completion of the
message exchange.
The scope of a SOAP Response MEP is limited to
the request for an exchange of a response message between
one requesting and one responding SOAP node. This pattern does
not mandate any correlation between multiple requests nor
specific timing for multiple requests. Implementations MAY choose
to support multiple ongoing requests (and associated response
processing) at the same time.
Note:
This MEP cannot be used in conjunction with features expressed as SOAP header blocks in the request because there is no SOAP envelope in which to carry them.
6.3.3 State Machine Description
The SOAP Response MEP defines a set of properties described in Table 8.
Table 8: Property definitions for SOAP Response MEP
| Property Name |
Property Description |
Property Type |
http://www.w3.org/2003/05/soap/mep/OutboundMessage
|
An abstract structure that represents the current
outbound message in the message exchange. This
abstracts both SOAP Envelope Infoset (which MAY be null) and any other
information structures that are transferred along
with the envelope. |
Not specified |
http://www.w3.org/2003/05/soap/mep/InboundMessage
|
An abstract structure that represents the current
inbound message in the message exchange. This
abstracts both SOAP Envelope Infoset (which MAY be null) and any other
information structures that are transferred along
with the envelope.
|
Not specified |
http://www.w3.org/2003/05/soap/mep/ImmediateDestination
|
The identifier of the immediate destination of an
outbound message. |
xs:anyURI |
http://www.w3.org/2003/05/soap/mep/ImmediateSender
|
The identifier of the immediate sender of an inbound
message. |
xs:anyURI |
To initiate a message exchange conforming to the
SOAP Response MEP, the requesting SOAP node instantiates a
local message exchange context. Table 9 describes how
the context is initialized.
Table 9: Instantiation of a Message Exchange Context
for a requesting SOAP node
| Property Name |
Property Value |
Notes |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/ExchangePatternName
|
"http://www.w3.org/2003/05/soap/mep/soap-response/"
|
|
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason
|
"None" |
A relative URI whosebaseURIisthevalueofhttp://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/ExchangePatternNamehttp://www.w3.org/2002/12/soap/bindingFramework/ExchangeContext/ExchangePatternName |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role
|
"RequestingSOAPNode" |
A relative URI whosebaseURIisthevalueofhttp://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/ExchangePatternNamehttp://www.w3.org/2002/12/soap/bindingFramework/ExchangeContext/ExchangePatternName |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/State
|
"Init" |
A relative URI whosebaseURIisthevalueofhttp://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Rolehttp://www.w3.org/2002/12/soap/bindingFramework/ExchangeContext/Role |
http://www.w3.org/2003/05/soap/mep/OutboundMessage
|
An abstraction of the request
message that does not include a SOAP
envelope infoset. |
|
http://www.w3.org/2003/05/soap/mep/ImmediateDestination
|
An identifier (URI) that denotes
the responding SOAP node |
|
There may be other properties related to the operation of
the message exchange context instance. Such properties are
initialized according to their own feature specifications.
Once the message exchange context is initialized, control
of the context is passed to a (conforming) local binding
instance.
The diagram below shows the logical state transitions at
the requesting and responding SOAP nodes during the lifetime
of the message exchange. At each SOAP node, the local binding
instance updates (logically) the value of the
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/State property to
reflect the current state of the message exchange. The state names
are relative URIs, relative to a Base URI value carried in
the http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role property of the local
message exchange context.
Figure 3: SOAP Response MEP State Transition Diagram
When the local binding instance at the responding SOAP
node starts to receive an inbound request message, it
(logically) instantiates a message exchange context. Table 10
describes the properties that the binding initializes as
part of the context's instantiation.
Table 10: Instantiation of Message Exchange Context for
an inbound request message
| Property Name |
Property Value |
Notes |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/ExchangePatternName
|
"http://www.w3.org/2003/05/soap/mep/soap-response/" |
Initialized as early as possible during the life cycle of the message exchange. |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/FailureReason
|
"None" |
A relative URI whosebaseURIisthevalueofhttp://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/ExchangePatternNamehttp://www.w3.org/2002/12/soap/bindingFramework/ExchangeContext/ExchangePatternName |
http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role
|
"RespondingSOAPNode" |
A relative URI whosebaseURIisthevalueofhttp://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/ExchangePatternNamehttp://www.w3.org/2002/12/soap/bindingFramework/ExchangeContext/ExchangePatternName
Initialized as early as possible during the life cycle the message exchange. |
http://www.w3.org/2003/05/so |