1. SOAP - Simple Object Access Protocol
2. SOAP Envelope
3. SOAP Header
4. SOAP Body
5. SOAP Fault
6. SOAP Roles
7. SOAP Message Exchange Patterns

• Predefined SOAP Roles
• Custom SOAP Roles
• SOAP Roles in Header Elements
• SOAP Roles in Fault Element

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:

The next role are assumed by both intermediary nodes, and the ultimate receiving node.

The 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.

The 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 Header elements.

Here is a Header example using the role attribute:

<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 Role element:

<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>