Books / SOAP Web Services / Chapter 2
The SOAP Message Format
What is SOAP message?
A unit of communication in SOAP is a message. A SOAP message is an ordinary XML document containing the following elements shown in the figure below.
- A required Envelope element that identifies the XML document as a SOAP message
- An optional Header element that contains the message header information; can include any number of header blocks (simply referred to as headers); used to pass additional processing or control information (e.g., authentication, information related to transaction control, quality of service, and service billing and accounting-related data)
- A required Body element that contains the remote method call or response information; all immediate children of the Body element are body blocks (typically referred to simply as bodies)
- An optional Fault element that provides information about errors that occurred while processing the message
SOAP messages are encoded using XML and must not contain DTD references or XML
processing instructions. If a header is present in the message, it must be the first
immediate child of the Envelope
element. The Body
element either directly follows the
Header
element or must be the first immediate child of the Envelope
element if no header is
present.
Because the root element Envelope
is uniquely identified by its namespace, it allows
processing tools to immediately determine whether a given XML document is a SOAP message.
The main information the sender wants to transmit to the receiver should be in the body of the
message. Any additional information needed for intermediate processing or added-value services
(e.g., authentication, security, transaction control, or tracing and auditing) goes into the header.
This is the common approach for communication protocols. The header contains information that can be used by intermediate nodes along the SOAP message path. The payload or body is the
actual message being conveyed. This is the reason why the header is optional.
Each of the SOAP elements Envelope
, Header
, or Body
can include arbitrary number of
<any>
elements. Recall that the <any>
element enables us to extend the XML document with
elements not specified by the schema.
SOAP Message Example
An example SOAP message containing a SOAP header block and a SOAP body is given as:
<soap-env:Envelope
xmlns:soap-env="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soap-env:Header>
<ac:alertcontrol
xmlns:ac="http://example.org/alertcontrol" soap-env:mustUnderstand="1">
<ac:priority>high</ac:priority>
<ac:expires>2006-22-00T14:00:00-05:00</ac:expires>
</ac:alertcontrol>
</soap-env:Header>
<soap-env:Body>
<a:notify
xmlns:a="http://example.org/alert">
<a:note xsi:type="xsd:string"> 15 Reminder: meeting today at 11AM in Rm.601
</a:note>
</a:notify>
</soap-env:Body>
</soap-env:Envelope>
Listing 2-1: Example of a SOAP message.
The above SOAP message is a request for alert to a Web service. The request contains a text note
(in the Body
) and is marked (in the Header
) to indicate that the message is high priority, but
will become obsolete after the given time. The details are as follows:
-
Lines 1–2: Prefix
soap-env
, identifies SOAP-defined elements, namelyEnvelope
,Header
, andBody
, as well as the attributemustUnderstand
(appears in Line 7). -
Line 3: Prefix
xsd
refers to XML Schema elements, in particular the built-in typestring
(appears in Line 15). -
Line 4: Prefix
xsi
refers to XML Schema instance type attribute, asserting the type of the note as an XML Schemastring
(appears in Line 15). -
Line 7: The
mustUnderstand
attribute value “1” tells the Web service provider that it must understand the semantics of the header block and that it must process the header. The Web service requestor demands express service delivery. -
Lines 12–18: The
Body
element encapsulates the service method invocation information, namely the method namenotify
, the method parameternote
, its associated data type and its value.
SOAP message body blocks carry the information needed for the end recipient of a message. The
recipient must understand the semantics of all body blocks and must process them all. SOAP does
not define the schema for body blocks since they are application specific. There is only one
SOAP-defined body block—the Fault
element.
A SOAP message can pass through multiple nodes on its path. This includes the initial SOAP sender, zero or more SOAP intermediaries, and an ultimate SOAP receiver. SOAP intermediaries are applications that can process parts of a SOAP message as it travels from the sender to the receiver.
SOAP Intermediaries and Use cases
Intermediaries can both accept and forward (or relay, or route) SOAP messages. Three key use cases define the need for SOAP intermediaries:
- crossing trust domains,
- ensuring scalability, and
- providing value-added services along the SOAP message path.
Crossing trust domains is a common issue faced when implementing security in distributed systems. Corporate firewalls and virtual private network (VPN) gateways let some requests cross the trust domain boundary and deny access to others.
Similarly, ensuring scalability is an important requirement in distributed systems. We rarely have a simplistic scenario where the sender and receiver are directly connected by a dedicated link. In reality, there will be several network nodes on the communication path that will be crossed by many other concurrent communication flows. Due to the limited computing resources, the performance of these nodes may not scale well with the increasing traffic load. To ensure scalability, the intermediate nodes need to provide flexible buffering of messages and routing based not only on message parameters, such as origin, destination, and priority, but also on the state of the network measured by parameters such as the availability and load of its nodes as well as network traffic information.
Lastly, we need intermediaries to provide value-added services in a distributed system. Example services include authentication and authorization, security encryption, transaction management, message tracing and auditing, as well as billing and payment processing.
SOAP Message Global Attributes
SOAP defines three global attributes that are intended to be usable via qualified attribute names on any complex type referencing them. The attributes are as follows:
- The
mustUnderstand
attribute specifies whether it is mandatory or optional that a message receiver understands and processes the content of a SOAP header block. The message receiver to which this attribute refers to is named by the role attribute. - The
role
attribute is exclusively related to header blocks. It names the application that should process the given header block. - The
encodingStyle
attribute indicates the encoding rules used to serialize parts of a SOAP message. Although the SOAP specification allows this attribute to appear on any element of the message (including header blocks), it mostly applies to body blocks. - The
relay
attribute is used to indicate whether a SOAP header block targeted at a SOAP receiver must be relayed if not processed.
The mustUnderstand
attribute can have values ‘1
’ or ‘0
’ (or, ‘true
’ or ‘false
’).
Value ‘1
’ indicates that the target role of this SOAP message must understand the semantics of
the header block and process it. If this attribute is missing, this is equivalent to having value ‘0
’.
This value indicates that the target role may, but does not have to, process the header block.
The role
attribute carries an URI value that names the recipient of a header block. This can be
the ultimate receiver or an intermediary node that should provide a value-added service to this
message. The SOAP specification defines three roles: none, next, and ultimateReceiver. An
attribute value of http://www.w3.org/2003/05/soap-envelope/role/next
identifies the next SOAP application on the message path as the role for the header block. A
header without a role
attribute is intended for the ultimate recipient of this message.
The encodingStyle
attribute declares the mapping from an application-specific data
representation to the wire format. An encoding generally defines a data type and data mapping
between two parties that have different data representation. The decoding converts the wire
representation of the data back to the application-specific data format. The translation step from
one data representation to another, and back to the original format, is called serialization and
deserialization. The terms marshaling and unmarshalling may be used as alternatives. The scope
of the encodingStyle
attribute is that of its owner element and that element’s descendants,
excluding the scope of the encodingStyle
attribute on a nested element.
The relay
attribute indicates whether a header block should be relayed in the forwarded
message if the header block is targeted at a role played by the SOAP intermediary, but not
otherwise processed by the intermediary. This attribute type is Boolean and, if omitted, it is
equivalent as if included with a value of “false.”
Error Handling in SOAP: The Fault
Body Block
If a network node encounters problems while processing a SOAP message, it generates a fault
message and sends it back to the message sender, i.e., in the direction opposite to the original
message flow. The fault message contains a Fault
element which identifies the source and
cause of the error and allows error-diagnostic information to be exchanged between participants
in an interaction. Fault
is optional and can appear at most once within the Body element. The
fault message originator can be an end host or an intermediary network node which was supposed
to relay the original message. The content of the Fault
element is slightly different in these two
cases, as will be seen below.
A Fault
element consists of the following nested elements
- The Code element specifies the failure type. Fault codes are identified via namespace-qualified names. SOAP predefines several generic fault codes and allows custom-defined fault codes, as described below.
- The Reason element carries a human-readable explanation of the message-processing failure. It is a plain text of type string along with the attribute specifying the language the text is written in.
- The Node element names the SOAP node (end host or intermediary) on the SOAP message path that caused the fault to happen. This node is the originator of the fault message.
- The Role element identifies the role the originating node was operating in at the point the fault occurred. Similar to the role attribute (described above), but instead of identifying the role of the recipient of a header block, it gives the role of the fault originator.
- The Detail element carries application-specific error information related to the Body element and its sub-elements
SOAP Generic Fault Codes
As mentioned, SOAP predefines several generic fault codes. They must be namespace qualified and appear in a Code element. These are:
-
VersionMismatch: The SOAP node received a message whose version is not supported, which is determined by the
Envelope
namespace. For example, the node supports SOAP version 1.2, but the namespace qualification of the SOAP messageEnvelope
element is not identical tohttp://www.w3.org/2003/05/soap-envelope
. -
DataEncodingUnknown: A SOAP node to which a SOAP header block or SOAP body child element information item was targeted was targeted does not support the data encoding indicated by the
encodingStyle
attribute. -
MustUnderstand: A SOAP node to which a header block was targeted could not process the header block, and the block contained a
mustUnderstand
attribute value “true
”. -
Sender: A SOAP message was not appropriately formed or did not contain all required information. For example, the message could lack the proper authentication or payment information. Resending this identical message will again cause a failure.
-
Receiver: A SOAP message could not be processed due to reasons not related to the message format or content. For example, processing could include communicating with an upstream SOAP node, which did not respond. Resending this identical message might succeed at some later point in time.
SOAP allows custom extensions of fault codes through dot separators so that the right side of a
dot separator refines the more general information given on the left side. For example, the Code
element conveying a sender authentication error would contain Sender.Authentication
.
SOAP does not require any further structure within the content placed in header or body blocks.
Nonetheless, there are two aspects that influence how the header and body of a SOAP message
are constructed: encoding rules and communication styles . These are described in Chapter 3 and 4.