what does it mean to "understand" a soap header tagged "mustunderstand"

Question

I am learning about SOAP. I see that some header elements have a "mustunderstand" attribute that can be set to true or false. But what does it mean to "understand" a soap message? To parse it without errors? I have found a few sites that don't really explain it.

Can somebody give me a rundown of what's going on?

Answer 1

In order to call a web service you need to respect it's contract. If a web service has <operationA> and <operationB> but you send <operationC> to it you will get an error (a fault in SOAP parlance).

The web service has operations <operationA> and <operationB> and knows what to do with the message when the message contains <operationA> or <operationB>. But it doesn't have <operationC> and doesn't know what to do with a message that contains <operationC> so it just returns an error. An incorrect body can't be ignored but headers on the other hand have no restrictions on what they are so you need a different mechanism in order to handle them properly.

Headers are used to extend the message by adding transaction support, authentication, routing, and so on and so forth. But these extensions are not defined in the SOAP specification, they are user defined. The specification just says that headers are used for that and also specifies how the message must be processed when headers are present. The mustUnderstand attribute is part of the "how the message should be processed".

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.

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.

For example, imagine the header is for transaction semantics (i.e. the call must be performed within a transaction so that operations are performed in an atomic way, either all succeeding or all failing). If the processing node sees the transaction header it should start that transaction. Imagine what would happen if the node sees the header but does not know what it is so it decides to just ignore it and no transaction is started. Later, some operations fail while other succeed and there is no transaction to rollback. So now your application is in an inconsistent state.

The SOAP mustUnderstand attribute allows for robust evolution. Elements tagged with the SOAP mustUnderstand attribute with a value of "1" MUST be presumed to somehow modify the semantics of their parent or peer elements. Tagging elements in this manner assures that this change in semantics will not be silently (and, presumably, erroneously) ignored by those who may not fully understand it.

• http://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383500