A node processing / forwarding a SOAP message is said to act in one or more SOAP roles. Here is a simple diagram showing 3 nodes (computers) involved in the processing of a SOAP message:
|Nodes acting in different SOAP roles during SOAP message processing.|
The first node is the sender. This role is not mentioned in the SOAP specification though.
The second node is an intermediary node which forwards the SOAP message. Intermediary nodes may also alter the SOAP message. For instance, they may add, modify or remove header elements, or even change the body. Intermediary nodes are set to act in the next role.
The last node in the diagram is the "ultimateReceiver" of the SOAP message. The ultimate receiver is the node that actually processes the SOAP message. It is the "web service" in other words. Clever minds may claim though, that the "web service" actually consists of the whole chain of SOAP message processing nodes, and not just the ultimate receiver.
Predefined SOAP Roles
The SOAP specification predefines three roles:
|Role Name||Role URI|
next role are assumed by both intermediary nodes, and the ultimate receiving node.
none role is special. No node should act in the "none" role. Header blocks
targeted at this role should usually either be left unprocessed, or is used when processing some
other header block.
ultimateReceiver role is reserved for the ultimate receiver of the SOAP message.
Header blocks without this role attribute value should not process that header block.
Custom SOAP Roles
SOAP roles are not limited to the three predefined roles listed in the previous section. SOAP roles can be any role you define yourself. If you define your own roles, you will also have to define the semantics of those roles yourself. In other words, you will have to decide what it means to act in these roles you make up yourself.
SOAP Roles in Header Elements
SOAP roles can be used in SOAP
Here is a
Header example using the
<env:Header> <jj:maxTime value="10000" xmlns:jj="http://jenkov.com" role="http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver" /> </env:Header>
When a SOAP Header child element contains a
role attribute, only nodes
acting in that role must process that element. All other nodes should leave it be.
SOAP Roles in Fault Element
SOAP roles can also be used in SOAP
Fault elements. When used in a
Fault element the role tells which role the faulting node was acting in,
when the fault occurred.
Here is a
Fault element example using a
<env:Fault> <env:Code> <env:Value>env:Sender</env:Value> </env:Code> <env:Reason> <env:Text xml:lang="en-US">Error in Input Data</env:Text> </env:Reason> <env:Node>http://jenkov.com/theNodeThatFailed</env:Node> <env:Role> http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver </env:Role> </env:Fault>