SOAP messages are
fundamentally one-way transmissions from a SOAP sender to a SOAP receiver;
however, SOAP messages are often combined to implement patterns such as
request/response.
SOAP implementations
can be optimized to exploit the unique characteristics of particular network
systems. For example, the HTTP binding described in [1](SOAP
in HTTP) provides a request/response message exchange pattern that may be
leveraged by SOAP applications.
SOAP provides a
distributed processing model that assumes that a SOAP message originates at an
initial SOAP sender and is sent to an ultimate SOAP receiver via zero or more
SOAP intermediaries. This section defines the SOAP distributed processing
model. Section 5 defines a framework for describing how additional features
such as routing, reliability and security fit into the distributed processing
model.
A SOAP node can be
the initial SOAP sender, the ultimate SOAP receiver, or a SOAP intermediary, in
which case it is both a SOAP sender and a SOAP receiver.
A SOAP node
receiving a SOAP message MUST perform processing according to the SOAP
processing model as described in this section and by the remainder of this
specification.
In processing a SOAP
message, a SOAP node is said to act in one or more SOAP roles, each of which is
identified by a URI known as the SOAP role name. The roles assumed MUST be
invariant during the processing of an individual SOAP message; because this
specification deals only with the processing of individual SOAP messages, no
statement is made regarding the possibility that a given piece of software
might or might not act in varying roles when processing more than one SOAP
message.
The following roles
are defined by this specification:
"http://www.w3.org/2001/12/soap-envelope/role/next" Each SOAP
node MUST act in this role and can additionally assume zero or more other SOAP
roles.
"http://www.w3.org/2001/12/soap-envelope/role/none" SOAP nodes
MUST NOT act in this role.
"http://www.w3.org/2001/12/soap-envelope/role/ultimatereceiver" To
establish itself as the as the ultimate SOAP receiver a SOAP node MUST act in
this role. SOAP intermediaries MUST NOT act in this role.
While the purpose of
a SOAP role name is to identify a SOAP node, there are no routing or message
exchange semantics associated with the SOAP role name. For example, SOAP roles
MAY be named with a URI useable to route SOAP messages to an appropriate SOAP
node. Conversely, it is also appropriate to use SOAP roles with names that are
related more indirectly to message routing (e.g. "http://example.org/banking/anyAccountMgr")
or which are unrelated to routing (e.g. a URI meant to identify "all cache
management software"; such a header might be used, for example, to carry
an indication to any concerned software that the containing SOAP message is
idempotent, and can safely be cached and replayed.)
Except for "http://www.w3.org/2001/12/soap-envelope/role/next",
"http://www.w3.org/2001/12/soap-envelope/role/none" and "http://www.w3.org/2001/12/soap-envelope/role/ultimatereceiver"
this specification does not prescribe the criteria by which a given node determines
the set of roles in which it acts on a given message. For example,
implementations can base this determination on factors including, but not
limited to: hardcoded choices in the implementation, information provided by
the transport binding (e.g. the URI to which the message was physically
delivered), configuration information made by users during system installation,
etc.
SOAP header blocks
carry optional role attribute
information items (see 4.2.2 SOAP role Attribute)
that are used to target them to the appropriate SOAP node(s). This
specification refers to the (implicit or explicit) value of the SOAP role attribute as the SOAP role for the
corresponding SOAP header block.
A SOAP header block
is said to be targeted to a SOAP node if the SOAP role for the header block
matches a role played by the SOAP node.
Header blocks
targeted to the special role
"http://www.w3.org/2001/12/soap-envelope/role/none" are carried with
the message to the ultimate receiver, but are never formally
"processed". Such blocks MAY carry data that is required for
processing of other blocks.
The ultimate SOAP
recipient of a SOAP message is additionally responsible for processing the
message body. The SOAP message path for that message ends at the ultimate
recipient.
It is likely that
specifications for a wide variety of header functions will be developed over
time, and that some SOAP nodes MAY include the software necessary to implement
one or more such extensions. A SOAP header block is said to be understood by a
SOAP node if the software at that SOAP node has been written to fully conform
to and implement the semantics conveyed by the combination of local name and
namespace name of the outer-most element information item of that SOAP
header block.
SOAP header blocks
carry optional mustUnderstand attribute
information items (see 4.2.3 SOAP mustUnderstand
Attribute). When the value of such an attribute information item
is logically “True”, the SOAP block is said to be mandatory.
For every mandatory
SOAP header block targeted to a node, that node MUST either process the block
or not process the SOAP message at all, and instead generate a fault (see 2.6 Processing SOAP Messages and 4.4 SOAP Fault).
Mandatory blocks
MUST be presumed to somehow modify the semantics of other headers or body
elements. Tagging SOAP blocks as mandatory thus assures that such changes in
semantics will not be silently (and, presumably, erroneously) ignored by a SOAP
node to which the header block is targetted.
The mustUnderstand attribute
information item is not intended as a mechanism for detecting errors in
routing, misidentification of nodes, failure of a node to serve in its intended
role(s), etc., any of which may result in a failure to even attempt processing
of a given SOAP header block from a SOAP envelope. This specification therefore
does not require any fault to be generated based on the presence or value of
this attribute on a SOAP header block not targeted at the current processing
node, for example when it is suspected that such a block has survived
erronously due to a routing or targeting error at a preceeding intermediairy.
In particular, it is not an error for a mandatory header block targeted to a
role other than the ones assumed by the ultimate SOAP receiver to reach that
node without having been processed.
A SOAP body consists
of zero or more namespace qualified element information items, which
are the immediate children of the Body element
information item. The ultimate SOAP receiver MUST correctly process all
such body elements. However, Part 1 of this specification (this document)
mandates no particular structure or interpretation of such elements, and
provides no standard means for specifying the processing to be done.
This section sets
out the rules by which SOAP messages are processed. Unless otherwise stated,
processing must be semantically equivalent to performing the following steps
separately, and in the order given. Note however that nothing in this
specification should be taken to prevent the use of optimistic concurrency,
roll back, or other techniques that might provide increased flexibility in
processing order as long as all SOAP messages, SOAP faults and
application-level side effects are equivalent to those that would be obtained
by direct implementation of the following rules in the order shown below.
1.
Determine the set of roles in which the node is to act.
The contents of the SOAP envelope, including header blocks and the body, MAY be
inspected in making such determination.
2.
Identify all header blocks targeted at the node that are
mandatory.
3.
If one or more of the header blocks identified in the
preceding step are not understood by the node then generate a single SOAP
MustUnderstand fault (see 4.4.6 MustUnderstand Faults).
If such a fault is generated, any further processing MUST NOT be done.
4.
Process all header blocks targeted at the node and, in
the case of the ultimate SOAP recipient, the SOAP body. A SOAP node MUST
process all SOAP header blocks targeted at it. A SOAP node MAY choose to ignore
the processing implied by non-mandatory SOAP header blocks targeted at it.
5.
In the case of a SOAP intermediary, where the message is
to be forwarded further along the message path, remove all SOAP header blocks
targeted at the node, and possibly insert new SOAP header blocks.
In all cases where a
SOAP header block is processed, the SOAP node must understand the SOAP header
block and must do such processing in a manner fully conformant with the
specification for that block. The ultimate recipient MUST process the SOAP
body, in a manner consistent with 2.5
Structure and Interpretation of SOAP Bodies.
If processing is
unsuccessful, exactly one fault MUST be generated by the node. Header-related
faults other than mustUnderstand faults (see 4.4 SOAP
Fault) MUST be SOAP Sender or DataEncodingUnknown faults (see 4.4.5 SOAP Fault Codes) and MUST conform to the
specification for the corresponding SOAP header block. Faults relating to the
body MUST be SOAP Sender or DataEncodingUnknown faults (see 4.4.5 SOAP Fault Codes).
SOAP nodes can make
reference to any information in the SOAP envelope when processing a SOAP block.
For example, a caching function can cache the entire SOAP message, if desired.
The processing of
particular SOAP header block MAY control or determine the order of processing
for other SOAP header blocks and/or the SOAP body. For example, one could
create a SOAP header block to force processing of other SOAP header blocks in
lexical order. In the absence of such a controlling block, the order of header
and body processing is at the discretion of the SOAP node; header blocks MAY be
processed in arbitrary order, and such processing MAY precede, be interleaved
with, or MAY follow processing of the body. For example, a "begin
transaction" header block would typically precede, a "commit
transaction" would likely follow, and a "logging" function might
run concurrently with body processing.
If the SOAP node is
a SOAP intermediary, the SOAP message pattern and results of processing (e.g.
no fault generated) MAY require that the SOAP message be sent further along the
SOAP message path. Such relayed SOAP messages MUST contain all SOAP header
blocks and the SOAP body from the original SOAP message, in the original order,
except that SOAP header blocks targeted at the SOAP intermediary MUST be
removed (such SOAP blocks are removed regardless of whether they were processed
or ignored). Additional SOAP header blocks MAY be inserted at any point in the
SOAP message, and such inserted SOAP header blocks MAY be indistinguishable
from one or more just removed (effectively leaving them in place, but
emphasizing the need to reinterpret at each SOAP node along the SOAP message
path.)
Note:
The above rules
apply to processing at a single node. SOAP features MAY be designed to ensure
that mandatory (and other) headers are processed in an appropriate order, as
the message moves along the message path towards the ultimate recipient.
Specifically, such extensions might specify that a (Sender) fault is generated
if some SOAP header blocks have inadvertently survied past some intended point
in the message path. Such features MAY depend on the presence or value of the mustUnderstand attribute
information item in the surviving headers when determining whether an
error has occurred.