WebSphere Message Brokers
File: ac55790_
Writer: Michael Gibson

Concept topic

This build: July 31, 2007 21:21:14

The SOAP header

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.
Related concepts
The SOAP body
The SOAP fault
SOAP nodes
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:21:14

ac55790_ This topic's URL is: