WebReference.com - Part 1 of Chapter 3: Professional XML Web Services, from Wrox Press Ltd (5/7)

[previous] [next]

Professional XML Web Services

Header

The SOAP message structure of Envelope and Body elements is an open one that maps well to many messaging scenarios. The Body 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 Header 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 Header element is highlighted in the example below.

<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" 
               soap:encodingStyle="https://schemas.xmlsoap.org/soap
                                   /encoding/">
   <soap:Header>
      <h:from xmlns:h="https://www.wrox.com/Header">[email protected]</h:from>
      <h:report xmlns:h="https://www.wrox.com/Header">1</h:report>
   </soap:Header>
   <soap:Body>
      <w:GetSecretIdentity xmlns:w="https://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 Header element 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 mustUnderstand and actor attributes.

actor attribute

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 of Header elements, the issue of addressing becomes important.

The 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 "https://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.

mustUnderstand attribute

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.

The 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 1, indicating that the element is mandatory, or a 0, indicating that it is optional. The absence of the attribute is equivalent to the 0 value.

Let's take another look at the example message, this time with a mandatory Header element that is addressed to the final endpoint.

<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/" 
               soap:encodingStyle="https://schemas.xmlsoap.org/soap
                                   /encoding/">
   <soap:Header>
      <h:from xmlns:h="https://www.wrox.com/Header" soap:mustUnderstand="1">
         [email protected]
      </h:from>
   </soap:Header>
   <soap:Body>
      <w:GetSecretIdentity xmlns:w="https://www.wrox.com/heroes/">
         <w:codename>XSLT-Man</w:codename>
      </w:GetSecretIdentity>
   </soap:Body>
</soap:Envelope>

[previous] [next]

Created: November 12, 2001
Revised: November 12, 2001

URL: https://webreference.com/authoring/languages/xml/webservices/chap3/1/5.html