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

[previous] [next]

Professional XML Web Services

Envelope

The Envelope element, as its name would suggest, serves as a container for the other elements of the SOAP message. As it is the top element, the Envelope is the message. The example below shows the same message we saw earlier, but this time, the Envelope element has been highlighted to stress its position in the message.

<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>
   </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>

Envelope Namespace

SOAP messages indicate their version by the namespace of the Envelope element. The only version recognized by the 1.1 Note is the URI "https://schemas.xmlsoap.org/soap/envelope/". Messages that do not use this namespace are invalid, and endpoints that receive messages with another namespace must return a "fault". We will discuss Fault elements later in this section.

The use of the Envelope namespace to indicate message versions is a good example of how much the SOAP specification relies on XML Namespaces. Without XML Namespaces, it would be extremely difficult to define an open XML format for messages that did not result in name conflicts with the payload XML of the message.

encodingStyle attribute

The specification defines an attribute called encodingStyle that can be used to describe how data will be represented in the message. Encoding is the method used to represent data. The encodingStyle attribute can appear on any element in the message, but in the case of SOAP encoding, it often appears on the Envelope element. We will discuss the encodingStyle attribute and encoding in general in more detail later in the chapter.

Body

The Body element of a SOAP message is the location for application-specific data. It contains the payload of the message, carrying the data that represents the purpose of the message. It could be a remote procedure call, a purchase order, a stylesheet, or any XML that needs to be exchanged using a message. The Body element is highlighted in the message 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>
   </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>

The Body element must appear as an immediate child of the Envelope element. If there is no Header element, then the Body element is the first child; if a Header element does appear in the message, then the Body element immediately follows it. The payload of the message is represented as child elements of Body, and is serialized according to the chosen convention and encoding. Most of this chapter deals with the contents of the Body and how to build payloads.