The mustUnderstand Attribute

<< The role Attribute | The relay Attribute >>

144

SOAP

WITH

TTACHMENTS

API

FOR

AVA

The mustUnderstand Attribute

The other attribute that must be added only to a

SOAPHeaderElement

object is

mustUnderstand

. This attribute says whether or not the recipient (indicated by

the

actor

attribute) is required to process a header entry. When the value of the

mustUnderstand

attribute is

true

, the actor must understand the semantics of

the header entry and must process it correctly to those semantics. If the value is

false

, processing the header entry is optional. A

SOAPHeaderElement

object

with no

mustUnderstand

attribute is equivalent to one with a

mustUnderstand

attribute whose value is

false

The

mustUnderstand

attribute is used to call attention to the fact that the seman-

tics in an element are different from the semantics in its parent or peer elements.
This allows for robust evolution, ensuring that a change in semantics will not be
silently ignored by those who may not fully understand it.

If the actor for a header that has a

mustUnderstand

attribute set to

true

cannot

process the header, it must send a SOAP fault back to the sender. (See Using
SOAP Faults, page 145.) The actor must not change state or cause any side
effects, so that, to an outside observer, it appears that the fault was sent before
any header processing was done.

For example, you could set the

mustUnderstand

attribute to

true

for the

con-

firmationHeader

in the code fragment in The Actor Attribute (page 141):

QName confirmation =

new QName(nameSpaceURI, "confirmationDesk", nameSpace);

SOAPHeaderElement confirmationHeader =

header.addHeaderElement(confirmation);

confirmationHeader.setActor(

"http://gizmos.com/confirmations");

confirmationHeader.setMustUnderstand(true);

This fragment produces the following XML:

<ns:confirmationDesk

xmlns:ns="http://gizmos.com/NSURI"
SOAP-ENV:actor="http://gizmos.com/confirmations"
SOAP-ENV:mustUnderstand="1"/>