The SOAP header

The SOAP <Header> is an optional element in 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 It represents a logical grouping of data that 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. 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 what will 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. In this way, a SOAP message can 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. Note these important attributes:

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 operates 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 has 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 that performs logging. Header blocks that 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 the ones that are defined by the application:

http://www.w3.org/2003/05/soap-envelope/none: None of the SOAP nodes on the message path will 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 that are important to the overall purpose of the application. If a SOAP node determines, using the role or actor attribute, that it will process a header block, and the mustUnderstand attribute has a value of true, 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.

The mustUnderstand attribute has these values:

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.