Simple Object Access Protocol (SOAP)

An overview of the SOAP specification.

• Overview
• Message Processing
  • role
  • mustUnderstand
  • relay
• Terminology
  • Forwarding intermediaries versus active intermediaries

Overview

SOAP is an XML-based specification for web services. SOAP focusses on the “message specification” rather than a specific application protocol; the messages themselves may be carried by diverse application layer protocols; most commonly HTTP and SMTP.

The SOAP 1.2 specification has four dimensions:

1. Envelope: it divides a message into logical parts—mainly a header and a body. The envelope specifies the contents of the message, who should process it and whether its processing is optional or mandatory.
2. Encoding rules: the serialisation mechanism and the use of data types.
3. RPC representation: a convention to represent remote procedure calls and responses.
4. SOAP binding: the convention for envelope exchange between peers using a specific protocol.

Message Processing

SOAP defines a message structure in terms of an envelope. An envelope divides a message into logical parts: a header and a body. For example:

<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope"> 
 <env:Header>
  <h:userDetails xmlns:h="http://www.tesira.com/userDetails">
   <h:IP>192.168.1.34</h:IP>
   <h:username>john.smith</h:username>
  </h:userDetails>
 </env:Header>
 <env:Body>
  <e:exchangeRateRequest xmlns:e="http://www.tesira.com/ws/ExchangeRateServiceSchema">
   <e:quantity>5.20</e:quantity</e:quantity>
   <e:from>USD</e:from>
   <e:to>GBP</e:to>
  </e:exchangeRateRequest>
 </env:Body>
</env:Envelope>

The header declares application-specific metadata but it may also contain SOAP–defined attributes such as: role, mustUnderstand and relay. These attributes determine who should process the message and/or what must be done with it.

role

The optional header attribute defines whether a header block must be processed by a node that is identified by the role attribute. For example, the following declaration implies that the userDetails block is handled by a node that deals with black lists:

<env:Header>
 <h:userDetails xmlns:h="http://www.tesira.com/userDetails"
                env:role="http://www.tesira.com/blackListChecker">
  <h:IP>192.168.1.34</h:IP>
  <h:username>john.smith</h:username>
 </h:userDetails>
</env:Header>

The SOAP specification defines three roles as a convention:

• none: http://www.w3.org/2003/05/soap-envelope/role/none
• next: http://www.w3.org/2003/05/soap-envelope/role/next
• ultimateReceiver: http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver

The none, next, and ultimateReceiver roles apply in the context of nodes that play the roles of either intermediary or ultimate receiver. Under this convention, the following table tells whether each node type is expected to play the role of one of the provided constants:

mustUnderstand

This optional attribute defines whether a role-matching, receiver node must inexorably (necessarily) process the target header block or not:

    <env:Header>
     <h:userDetails xmlns:h="http://www.tesira.com/userDetails"
                    env:role="http://www.tesira.com/blackListChecker"
                    env:mustUnderstand="true">
      <h:IP>192.168.1.34</h:IP>
      <h:username>john.smith</h:username>
     </h:userDetails>
    </env:Header>

In this above example, the node happens to be blackListChecker. The expectation is that blackListChecker must execute whatever processing has been specified for the userDetails header block.

Instead, if the mustUnderstand attribute is absent (or set to false), the role-matching, receiver node is not formally required to do any processing. The following table explains the various possibilities:

Whenever the mustUnderstand attribute is set to true, the receiver node must either:

1. Process the header element (according to application-specific rules) or
2. Produce a fault

relay

This attribute defines whether an intermediary node must relay (e.g. copy unchanged) the identified header block. For example:

<env:Header>
 <h:userDetails xmlns:h="http://www.tesira.com/userDetails"
                env:role="http://www.w3.org/2003/05/soap-envelope/role/next"
                env:relay="true">
  <h:IP>192.168.1.34</h:IP>
  <h:username>john.smith</h:username>
 </h:userDetails>
</env:Header>

Unless the relay attribute is set to true; the convention—both under the presence or the absence of mustUnderstand—is that the target header block will be omitted in the subsequent invocation along a message path.

Terminology

• SOAP node: the entity that creates or processes SOAP messages.
• SOAP sender: the node that transmits a message.
• Initial SOAP sender: the node that creates a message for the first time.
• SOAP receiver: a node that receives a message.
• SOAP intermediary: a node that receives and retransmits a message. SOAP intermediaries are further classified as forwarding and active.
• Ultimate SOAP sender: the last SOAP node that receives a message.
• Message path: the route that a message traverses starting with the initial SOAP sender and culminating with the ultimate SOAP receiver.

Forwarding intermediaries versus active intermediaries

Forwarding intermediaries are mainly focussed on relaying a received message to the next node in the message chain. Such a process may involve altering header blocks.

Active intermediaries, instead, may incur further processing logic beyond that which is required to simply forward an incoming message.