The SOAP <Header> is an optional element within
a SOAP message. It is used to pass application-related information that is
to be 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 will process every header block. Rather, each node is typically
designed to process particular header blocks, and - conversely - each header
block is intended to be processed by particular nodes.
The SOAP header allows features to be added to a SOAP message in a decentralized
manner without prior agreement between the communicating parties. SOAP defines
a few attributes that can be used to indicate who should 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 allows 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 are to be processed by
the SOAP nodes. Some of the important attributes are:
- 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 very flexible encoding
that XML allows.
- role (SOAP 1.2)
- actor (SOAP 1.1)
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 which are
to be 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 (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, it removes it
from the SOAP message. By default, it 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 node retains the unprocessed header block in the message.