The SOAP <Header> is an optional sub-element
of the SOAP envelope, and is used to pass application-related information
that is processed by SOAP nodes along the message path.
The immediate child elements of the <Header> element
are called header blocks. A header block is an application-defined XML element,
and represents a logical grouping of data which can be targeted at SOAP nodes
that might be encountered in the path of a message from a sender to an ultimate
receiver.
SOAP header blocks can be processed by SOAP intermediary nodes, and by
the ultimate SOAP receiver node. However, in a real application, not every
node processes every header block. Each node is typically designed to process
particular header blocks, and each header block is processed by particular
nodes.
The SOAP header enables you to add features to a SOAP message
in a decentralized manner without prior agreement between the communicating
parties. SOAP defines some attributes that can be used to indicate who can
deal with a feature and whether it is optional or mandatory. Such control
information includes, for example, passing directives or contextual information
related to the processing of the message. This control information enables
a SOAP message to be extended in an application-specific manner.
Although the header blocks are application-defined, SOAP-defined attributes
on the header blocks indicate how the header blocks must be processed by the
SOAP nodes. Important attributes include:
- encodingStyle
- Indicates the rules used to encode the parts of a SOAP message. SOAP defines
a narrower set of rules for encoding data than the flexible encoding that
XML enables.
- actor (SOAP 1.1) or role (SOAP 1.2)
- In SOAP 1.2, the role attribute specifies whether a particular
node will operate on a message. If the role specified for the node matches
the role attribute of the header block, the node processes the header. If
the roles do not match, the node does not process the header block. In SOAP
1.1, the actor attribute performs the same function.
Roles can be
defined by the application, and are designated by a URI. For example, http://example.com/Log might
designate the role of a node which performs logging. Header blocks that are
processed by this node specify env:role="http://example.com/Log" (where
the namespace prefix env is associated with the SOAP namespace
name of http://www.w3.org/2003/05/soap-envelope).
The
SOAP 1.2 specification defines three standard roles in addition to those which
are defined by the application:
- http://www.w3.org/2003/05/soap-envelope/none
- None of the SOAP nodes on the message path should process the header block
directly. Header blocks with this role can be used to carry data that is required
for processing of other SOAP header blocks.
- http://www.w3.org/2003/05/soap-envelope/next
- All SOAP nodes on the message path are expected to examine the header
block (provided that the header has not been removed by a node earlier in
the message path).
- http://www.w3.org/2003/05/soap-envelope/ultimateReceiver
- Only the ultimate receiver node is expected to examine the header block.
- mustUnderstand
- This attribute is used to ensure that SOAP nodes do not ignore header
blocks which are important to the overall purpose of the application. If a
SOAP node determines, by using the role or actor attribute,
that it should process a header block, and the mustUnderstand attribute
has a value of "true", then the node must either process
the header block in a manner consistent with its specification, or not at
all (and throw a fault). But if the attribute has a value of "false",
the node is not obliged to process the header block.
In effect, the mustUnderstand attribute
indicates whether processing of the header block is mandatory or optional.
Values
of the
mustUnderstand attribute are:
- true (SOAP 1.2).
- 1 (SOAP 1.1). The node must either process the header
block in a manner consistent with its specification, or not at all (and throw
a fault).
- false (SOAP 1.2).
- 0 (SOAP 1.1). The node is not obliged to process the
header block.
- relay (SOAP 1.2 only)
- When a SOAP intermediary node processes a header block, the SOAP intermediary
node removes the header block from the SOAP message. By default, the SOAP
intermediary node also removes any header blocks that it ignored (because
the mustUnderstand attribute had a value of "false").
However, when the relay attribute is specified with a value of "true",
the SOAP intermediary node retains the unprocessed header block in the message.