WebReference.com - Part 1 of Chapter 3: Professional XML Web Services, from Wrox Press Ltd (5/7)
Professional XML Web Services
The SOAP message structure of
elements is an open one that maps well to many messaging scenarios. The
element encapsulates the payload for the message, but in some instances, the payload data is
not enough. Perhaps a message is part of a set of messages that must be treated as a single
logical transaction, or the message should be executed on a persistent object that resides
at the server. Issues like transactions and object references are vital to the message, but
are separate from the payload.
It is unrealistic to think that we can predict every type of extension that will
be needed by a SOAP message. So, in a wise design choice, the authors created the
element. The purpose of the
Header element is to encapsulate extensions to the message
format without having to couple them to the payload or to modify the fundamental structure of SOAP.
This allows extensions like transactions, encryption, object references, billing, and countless
others to be added over time without breaking the specification. The text below illustrates our
original example message with an additional
Header entry. The entire
element is highlighted in the example below.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle="http://schemas.xmlsoap.org/soap /encoding/"> <soap:Header> <h:from xmlns:h="http://www.wrox.com/Header">SoapGuy@wrox.com</h:from> <h:report xmlns:h="http://www.wrox.com/Header">1</h:report> </soap:Header> <soap:Body> <w:GetSecretIdentity xmlns:w="http://www.wrox.com/heroes/"> <w:codename>XSLT-Man</w:codename> </w:GetSecretIdentity> </soap:Body> </soap:Envelope>
In this example, the header entry
h:from could be used to send a report via e-mail to the address that is indicated. By agreeing upon a set of extensions, a sender and receiver can build additional capabilities into a message exchange without requiring additional features from SOAP.
As this chapter is being written, there is still little detail out about SOAP 1.2, the very likely successor to SOAP 1.1. However, what information is available suggests that the XMLP working group will be leveraging the extensibility of the
Headerelement to build additional capabilities on top of SOAP 1.1. If SOAP 1.2 develops in this manner, it should help early adopters of SOAP significantly.
Just like the
Body element, the
Header element must appear as an
immediate child of the
Envelope element. It is optional, but if it does appear, it must appear
as the first child. The
Header element contains one or more child elements known as entries.
Header entries can be used to add any type of extension to a message, and by default, an endpoint will
ignore the extension unless it can understand it. This allows the extensions to be developed over time
without breaking existing endpoints. Some extensions have additional requirements, however, that are
dealt with using the
As the SOAP model allows for endpoints to be chained together, it is necessary to identify
what parts of a message are meant for what endpoint on the chain. In the case of the payload, it is not
necessary to do this: the final endpoint on the chain is the target of the payload. However, in the case
Header elements, the issue of addressing becomes important.
actor attribute can be used to address a
Header element to a
particular endpoint. The value of the
actor attribute is a URI that identifies the endpoint the
Header element entry is targeted for. SOAP attaches special significance to two values of the
actor attribute to address issues of message chaining. If the value is
"http://schemas.xmlsoap.org/soap/actor/next", then the entry is targeted for the first
endpoint that finds it. Omitting the
actor attribute indicates that the entry is intended
for the final endpoint, the same endpoint that will process the payload.
The issue of the
actor attribute becomes important when it comes to
intermediaries and the
Header element. There has been quite a bit of debate on the behavior
of intermediaries towards
Header elements. In the end, the consensus is that well-behaved
intermediaries know whether or not they are the last endpoint in the chain, and if they are not, they
should not modify
Header elements that have no
actor attribute. In addition,
intermediaries must remove the
Header elements they process.
In the example of a
Header element that represents a transaction, developers
will not be able to accept the endpoint ignoring the extension. If a message is part of a transaction,
it must be part of a transaction, and endpoints that cannot support transactions should not try to process
a message. This is where the
mustUnderstand attribute is useful.
mustUnderstand attribute can be used anywhere in a SOAP message, but it
commonly appears on a
Header element. The value of the attribute is either a
indicating that the element is mandatory, or a
0, indicating that it is optional. The absence
of the attribute is equivalent to the
Let's take another look at the example message, this time with a mandatory
element that is addressed to the final endpoint.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle="http://schemas.xmlsoap.org/soap /encoding/"> <soap:Header> <h:from xmlns:h="http://www.wrox.com/Header" soap:mustUnderstand="1"> SoapGuy@wrox.com </h:from> </soap:Header> <soap:Body> <w:GetSecretIdentity xmlns:w="http://www.wrox.com/heroes/"> <w:codename>XSLT-Man</w:codename> </w:GetSecretIdentity> </soap:Body> </soap:Envelope>
Created: November 12, 2001
Revised: November 12, 2001