Describe how SOAP message header blocks are used and processed.
SOAP provides a flexible mechanism for extending a message in a decentralized and modular way without prior knowledge between the
communicating parties. Typical examples of extensions that can be implemented as header entries are authentication, transaction management,
payment etc.
The Header element is encoded as the first immediate child element of the SOAP Envelope XML element.
NOTE: The Header element is OPTIONAL.
All immediate child elements of the Header element are called header entries
(Header element may contain multiple child elements - header entries).
Header entries can have following attributes: actor, encodingStyle,
mustUnderstand.
The encoding rules for header entries are as follows:
A header entry is identified by its fully qualified element name, which consists of the namespace URI and the
local name. All immediate child elements of the SOAP Header element MUST be namespace-qualified.
The SOAP encodingStyle attribute MAY be used to indicate the encoding style used for the header
entries.
The SOAP mustUnderstand attribute and SOAP actor attribute MAY be used to
indicate how to process the entry and by whom.
The SOAP Header attributes defined in this section determine how a recipient of a SOAP message should process
the message. A SOAP application generating a SOAP message SHOULD only use the SOAP Header attributes on immediate
child elements of the SOAP Header element. The recipient of a SOAP message MUST ignore all SOAP
Header attributes that are not applied to an immediate child element of the SOAP Header element.
An example is a header with an element identifier of "Transaction", a "mustUnderstand" value of
"1", and a value of 12345. This would be encoded as follows:
<SOAP-ENV:Header>
<t:Transaction xmlns:t="some-URI" SOAP-ENV:mustUnderstand="1">
12345
</t:Transaction>
</SOAP-ENV:Header>
or
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">
<soap:Header>
<t:Transaction xmlns:t="some-URI" soap:mustUnderstand="1">
12345
</t:Transaction>
</soap:Header>
...
...
</soap:Envelope>
A SOAP message travels from the originator to the ultimate destination, potentially by passing through a set of SOAP intermediaries along
the message path. A SOAP intermediary is an application that is capable of both receiving and forwarding SOAP messages. Both intermediaries
as well as the ultimate destination are identified by a URI. Not all parts of a SOAP message may be intended for the ultimate
destination of the SOAP message but, instead, may be intended for one or more of the intermediaries on the message path. The role of a
recipient of a header element is similar to that of accepting a contract in that it cannot be extended beyond the recipient. That is,
a recipient receiving a header element MUST NOT forward that header element to the next application in the SOAP message path. The
recipient MAY insert a similar header element but in that case, the contract is between that application and the recipient of that
header element. The SOAP actor global attribute can be used to indicate the recipient of a header element.
The value of the SOAP actor attribute is a URI:
SOAP-ENV:actor="some-URI"
or
soap:actor="some-URI"
The special URI
"http://schemas.xmlsoap.org/soap/actor/next" indicates that the header element is intended for the very first
SOAP application that processes the message. This is similar to the hop-by-hop scope model represented by the
Connection header field in HTTP. NOTE: Omitting the SOAP actor attribute indicates that the
recipient is the ultimate destination of the SOAP message. This attribute MUST appear in the SOAP message instance in order
to be effective.
An example:
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">
<soap:Header>
<t:Transaction xmlns:t="some-URI"
soap:actor="http://myserver.com/myactor">
12345
</t:Transaction>
</soap:Header>
...
...
</soap:Envelope>
In this example header will be processed by first application:
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">
<soap:Header>
<t:Transaction xmlns:t="some-URI"
soap:actor="http://schemas.xmlsoap.org/soap/actor/next">
12345
</t:Transaction>
</soap:Header>
...
...
</soap:Envelope>
The SOAP mustUnderstand global attribute can be used to indicate whether a header entry is mandatory or
optional for the recipient to process. The recipient of a header entry is defined by the SOAP actor attribute.
The value of the mustUnderstand attribute is either "1" or "0".
SOAP-ENV:mustUnderstand="0|1"
or
soap:mustUnderstand="0|1"
The absence of the SOAP mustUnderstand attribute is semantically equivalent to its presence
with the value "0". If a header element is tagged with a SOAP mustUnderstand attribute with
a value of "1", the recipient of that header entry either MUST obey the semantics (as conveyed by the fully
qualified name of the element) and process correctly to those semantics, or MUST fail processing the message. The SOAP
mustUnderstand attribute allows for robust evolution. Elements tagged with the SOAP mustUnderstand
attribute with a value of "1" MUST be presumed to somehow modify the semantics of their parent or peer
elements. Tagging elements in this manner assures that this change in semantics will not be silently (and, presumably, erroneously)
ignored by those who may not fully understand it. This attribute MUST appear in the instance in order to be effective.
An example:
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">
<soap:Header>
<t:Transaction xmlns:t="some-URI"
soap:actor="http://myserver.com/myactor"
soap:mustUnderstand="1">
12345
</t:Transaction>
</soap:Header>
...
...
</soap:Envelope>
