SOAP Roles

A node processing / forwarding a SOAP message is said to act in one or more SOAP roles. Here is a simple diagram showing 3 nodes (computers) involved in the processing of a SOAP message:

soap-roles-1

The first node is the sender. This role is not mentioned in the SOAP specification though.
The second node is an intermediary node which forwards the SOAP message. Intermediary nodes may also alter the SOAP message. For instance, they may add, modify or remove header elements, or even change the body. Intermediary nodes are set to act in the next role.
The last node in the diagram is the “ultimateReceiver” of the SOAP message. The ultimate receiver is the node that actually processes the SOAP message.

Role :

A SOAP message travels from the originator to the ultimate destination, potentially by passing through a set of SOAP intermediaries along the message path. A header can be targeted for a specific node or for the final node (i.e. SOAP 1.1 actor attribute or SOAP 1.2 role attribute), and when that happens the node must do something with the header. This can be either to use it or to ignore it.

roles

Note no role attribute present, so this header block is to be processed by the ultimate receiver of the message and no other node.

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.
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 is only intended to be processed by the ultimate receiver of the SOAP message. Intermediary nodes should ignore this header element.
When a SOAP Header child element contains a role attribute, only nodes acting in that role must process that element. All other nodes should leave it be.

The mustUnderstand Attribute :

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.

The mustUnderstand attribute indicates whether processing of the header is optional or mandatory. This basically translates to the node trying to find an appropriate handler that matches the header and proceed with processing the message in a manner consistent with its specification. If it can’t find an appropriate handler it must return an error and stop further processing. If mustUnderstand is true/1 the node is not allowed to ignore it.

The mustUnderstand attribute should only appear on the root element of a SOAP header block. If it
appears elsewhere, it should be ignored.
The BP stipulates that the mustUnderstand attribute may only have the value “1” or “0”. The default
value is “0”.

Here is an example:

<env:Header>
  <jj:maxTime value="10000" xmlns:jj="http://jenkov.com"
               mustUnderstand="true"
    />
</env:Header>

It is not considered an error if the Ultimate Receiver receives a SOAP header block with the
mustUnderstand attribute set to “1” and the role attribute specifying some role that the ultimate
receiver does not take on.

For more info :

http://tutorials.jenkov.com/soap/roles.html

http://tutorials.jenkov.com/soap/header.html

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s