background image

Header Attributes

<< The SOAPElement Interface | SOAPHeaderElement >>
<< The SOAPElement Interface | SOAPHeaderElement >>

Header Attributes

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, transaction 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 SOAPHeaderElement
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.
See
"Header Example" on page 614
for an example that uses the code shown in this section.
The actor Attribute
The actor attribute is optional, but if it is used, it must appear in a SOAPHeaderElement 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 supply header information that applies specifically
to each of the recipients.
For example, suppose that a message is an incoming purchase order. Its SOAPHeader 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 applications 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.
An actor is identified by its URI. For example, the following line of code, in which orderHeader
is a SOAPHeaderElement object, sets the actor to the given URI.
orderHeader.setActor(
"http://gizmos.com/orders");
SAAJ Tutorial
Chapter 19 · SOAP with Attachments API for Java
605