Header Attributes
A
DDING
A
TTRIBUTES
141
Header Attributes
Attributes that appear in a
SOAPHeaderElement
object determine how a recipient
processes a message. You can think of header attributes as offering a way to
extend a message, giving information about such things as authentication, trans-
action management, payment, and so on. A header attribute refines the meaning
of the header, whereas the header refines the meaning of the message contained
in the SOAP body.
The SOAP 1.1 specification defines two attributes that can appear only in
SOAP-
HeaderElement
objects:
actor
and
mustUnderstand
.
The SOAP 1.2 specification defines three such attributes:
role
(a new name for
actor
),
mustUnderstand
, and
relay
.
The next sections discuss these attributes.
The Actor Attribute
The
actor
attribute is optional, but if it is used, it must appear in a
SOAPHeader-
Element
object. Its purpose is to indicate the recipient of a header element. The
default actor is the message's ultimate recipient; that is, if no actor attribute is
supplied, the message goes directly to the ultimate recipient.
An actor is an application that can both receive SOAP messages and forward
them to the next actor. The ability to specify one or more actors as intermediate
recipients makes it possible to route a message to multiple recipients and to sup-
ply header information that applies specifically to each of the recipients.
For example, suppose that a message is an incoming purchase order. Its
SOAP-
Header
object might have
SOAPHeaderElement
objects with actor attributes that
route the message to applications that function as the order desk, the shipping
desk, the confirmation desk, and the billing department. Each of these applica-
tions will take the appropriate action, remove the
SOAPHeaderElement
objects
relevant to it, and send the message on to the next actor.
Note: Although the SAAJ API provides the API for adding these attributes, it does
not supply the API for processing them. For example, the actor attribute requires
that there be an implementation such as a messaging provider service to route the
message from one actor to the next.
