Java Reference
In-Depth Information
Working with SOAP Actors
Problem
You want to specify the SOAP actor that should handle a certain aspect of your message.
Solution
Just create a regular SOAP header, add a header element to it, and call the
setActor
method
on the header element.
Discussion
Attributes that appear as
SOAPHeaderElement
s provide instructions on how a node should
process a message. They allow you to indicate whether a message must be processed by a giv-
en node, how transactions should be managed, what kinds of policies apply to the message,
and so forth.
NOTE
In SOAP 1.2, the term actorhas been replaced with role. The role, defined in section 5.2.2 of the spe-
cification, indicates a particular node to which a particular header block is assigned. The named node
should process a message once it is received by that node.
Most SOAP messages are processed by a single node, called the Ultimate Receiver. This is
the default actor if none is specified. A client sends a message to a service endpoint, which
processes the contents of the message, and perhaps returns a response. It is possible, however,
to create a series of nodes that process different parts of a received SOAP message, using a
pipe and filter design. In this scenario, every node along a chain of SOAP handlers examines
every header element to determine if any of the headers must be processed by a role that this
node supports. If there is only one processor, that is by definition acting in the Ultimate Re-
ceiver role, and it does all of the processing.
The actor attribute is optional, and if it is not specified, the message will route directly to the
Ultimate Receiver. SOAP actors and roles are identified by URIs. Each node in a processing
path can support multiple roles.
As an example, suppose that an incoming message represents an invoice. Its
SOAPHeader
might define a variety of
SOAPHeaderElement
s that each specify a different actor attribute
