Tech and Media Labs
This site uses cookies to improve the user experience.




SOAP Header

Jakob Jenkov
Last update: 2014-05-23

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:

  1. true
  2. 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.

Jakob Jenkov




Copyright  Jenkov Aps
Close TOC