The role Attribute
The role Attribute
Two additional SOAPHeader methods, examineAllHeaderElements and
extractAllHeaderElements
, allow you to examine or extract all the header elements, whether
or not they have an actor attribute. For example, you could use the following code to display the
values of all the header elements:
Iterator allHeaders = header.examineAllHeaderElements();
while (allHeaders.hasNext()) {
SOAPHeaderElement headerElement = (SOAPHeaderElement)allHeaders.next();
QName headerName = headerElement.getElementQName();
System.out.println(
"\nHeader name is " + headerName.toString());
System.out.println(
"Actor is " + headerElement.getActor());
}
The role Attribute
The role attribute is the name used by the SOAP 1.2 specification for the SOAP 1.2 actor
attribute. The SOAPHeaderElement methods setRole and getRole perform the same functions
as the setActor and getActor methods.
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 semantics 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
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 confirmationHeader
in the code fragment in
QName confirmation = new QName(nameSpaceURI,
"confirmationDesk", nameSpace);
SOAPHeaderElement confirmationHeader = header.addHeaderElement(confirmation);
confirmationHeader.setActor(
"http://gizmos.com/confirmations");
confirmationHeader.setMustUnderstand(true);
SAAJ Tutorial
Chapter 19 · SOAP with Attachments API for Java
607
