SOAP Header
Jakob Jenkov |
The SOAP Header element is an optional child element of the Envelope element.
Inside the Header element you can put information that is not part of the body of a SOAP
message. Whatever that information could be, is up to you. For instance, it could be information about
the maximum time the SOAP request may take to process, or something similar which is not directly related
to the message itself.
Here is a sample SOAP Header element (Header element marked in bold):
<?xml version="1.0"?>
<env:Envelope xmlns:env="http://www.w3.org/2001/12/soap-envelope" >
<env:Header>
<jj:maxTime value="10000" xmlns:jj="http://jenkov.com"/>
</env:Header>
<env:Body>
</env:Body>
</env:Envelope>
The example above shows a Header element with a single "SOAP header block"
(child element of Header element).
Notice how the Header element is using the same XML name space as the Envelope
element. This is required by the SOAP specification.
Header Child Element Attributes
The Header child elements has a list of standard attributes you can use inside them:
- mustUnderstand
- encodingStyle
- role
- relay
Each of these attributes are described in the following sections.
mustUnderstand
The mustUnderstand attribute means that any node (computer) processing the SOAP message
must understand the given header block. A "node" may not alway be the final receiver of the SOAP message.
The message might be routed via intermediate nodes before ending up at the receiving / processing node (the final web service).
In case an intermediate node does not understand the header block (element) containing the mustUnderstand
attribute, it must return a SOAP fault.
Here is an example:
<env:Header>
<jj:maxTime value="10000" xmlns:jj="http://jenkov.com"
mustUnderstand="true"
/>
</env:Header>
encodingStyle
The encodingStyle attribute is skipped here.
role
A node processing / forwarding a SOAP message is said to act in one or more SOAP roles. Header blocks (elements) can be targeted at nodes acting in specific roles. In other words, if a header block is targeted for nodes acting in the "ultimateReceiver" role, then only nodes acting as ultimate receivers must process that header block. All other nodes should leave it unprocessed.
SOAP roles are explained in more detail in the SOAP Roles text.
Here is an example using the role attribute:
<env:Header>
<jj:maxTime value="10000" xmlns:jj="http://jenkov.com"
role="http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver"
/>
</env:Header>
In this example the header element <maxTime ...> is only intended to
be processed by the ultimate receiver of the SOAP message. Intermediary nodes should
ignore this header element.
relay
The relay attribute determines if a header block is allowed to be relayed if not processed.
In other words, if an intermediary node forwards the SOAP message without processing the header element
in which the relay attribute is found, should that header element then be forwarded (relayed)
in the message, or taken out?
The relay attribute only has two valid values:
- true
- false
If the attribute is set to true then this header element can be forwarded even if not processed.
If the attribute is set to false then this header element should be removed if the message is forwarded.
Omitting the relay attribute is equivalent to setting it to false.
Here is an example header using a relay attribute:
<env:Header>
<jj:maxRelayTime value="10000" xmlns:jj="http://jenkov.com"
role="http://www.w3.org/2003/05/soap-envelope/role/next"
relay="true"
/>
</env:Header>
In this example the header element <maxRelayTime ...> must be relayed from node
to node, even if processed. In other words, the header element should not be taken out. As you can
see, the role attribute is set to "next", meaning all intermediary nodes should process
this header element.
| Tweet | |
Jakob Jenkov | |
