The SOAP Message Format
Chapter 8 • Web
Services 269
Sender Service Requestor
Intermediary Intermediary
Receiver Service Provider
15 Reminder: meeting today at 11AM in Rm.601 16 a:note
17 a:notify 18
soap-env:Body
19 soap-env:Envelope
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, declared in Line 2, identifies SOAP-defined elements, namely Envelope
, Header, and Body, as well as the attribute mustUnderstand appears in Line 7.
Line 3: Prefix xsd refers to XML Schema elements, in particular the built-in type string appears in Line 14.
Line 4: Prefix xsi refers to XML Schema instance type attribute, asserting the type of the note
as an XML Schema string appears in Line 14. 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 name notify, the method parameter note, 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 shown in Figure 8-4—which is described below.
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. 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
Ivan Marsic • Rutgers University
270
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 more details on each are
provided below:
• 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.org200305soap-enveloperolenext
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 marshalling 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. More about SOAP encoding is given in Section 8.2.2 below.
Chapter 8 • Web
Services 271
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 shown in Figure 8-4:
• 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. As mentioned, SOAP predefines several generic fault codes. They must be namespace qualified
and appear in a Code element. These are:
Fault Code Explanation
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 message Envelope element is not identical to
http:www.w3.org200305soap-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
Ivan Marsic • Rutgers University
272
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: communication style and encoding rules. These are described next.