5.3 SOAP messages


5.3 SOAP messages

A SOAP message is the basic unit of communications between SOAP nodes. A SOAP message is made up entirely of a SOAP envelope, as shown in Figure 5.5. In other words, a SOAP message document starts off with a definition for an envelope, and you can only have one envelope definition per SOAP message. The envelope is thus the top (and thereby the outermost) element of any SOAP message. This can be clearly seen in all of the SOAP message examples shown in this chapter ”with the XML definition for the envelope occurring very near the top. In the case of SOAP, the envelope is the message.

click to expand
Figure 5.5: The overall structure of a SOAP message highlighting that the entire message is made up of a SOAP envelope that consists of an optional header and a mandatory body, which contains the actual payload.

A SOAP envelope may contain two subelements ”namely, an optional header and a mandatory body. The envelope thus defines an overall framework for expressing what is in a message. Figure 5.6 shows a relatively long travel reservation “ related SOAP message, as included in the SOAP 1.2 Primer, to highlight the composition of a real SOAP message, while Figure 5.7 takes the eOrder book ordering SOAP example used at the start of this chapter and demarcates it to show the various components of a SOAP message.

start figure
 <?xml version='1.0' ?>  <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">   <env:Header>    <m:reservation xmlns:m="http://travelcompany.example.org/reservation"            env:role="http://www.w3.org/2003/05/soap-envelope/role/next"             env:mustUnderstand="true">     <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference>     <m:dateAndTime>2001-11-29T13:20:00.000-05:00</m:dateAndTime>    </m:reservation>    <n:passenger xmlns:n="http://mycompany.example.com/employees"            env:role="http://www.w3.org/2003/05/soap-envelope/role/next"             env:mustUnderstand="true">     <n:name>ke Jgvan yvind</n:name>    </n:passenger>   </env:Header>   <env:Body>    <p:itinerary      xmlns:p="http://travelcompany.example.org/reservation/travel">     <p:departure>       <p:departing>New York</p:departing>       <p:arriving>Los Angeles</p:arriving>       <p:departureDate>2001-12-14</p:departureDate>       <p:departureTime>late afternoon</p:departureTime>       <p:seatPreference>aisle</p:seatPreference>     </p:departure>     <p:return>       <p:departing>Los Angeles</p:departing>       <p:arriving>New York</p:arriving>       <p:departureDate>2001-12-20</p:departureDate>       <p:departureTime>mid-morning</p:departureTime>       <p:seatPreference/>     </p:return>    </p:itinerary>    <q:lodging     xmlns:q="http://travelcompany.example.org/reservation/hotels">     <q:preference>none</q:preference>    </q:lodging>   </env:Body>  </env:Envelope> 
end figure

Figure 5.6: Example of a representative and complete SOAP message ”in this case a travel reservation example, as included in the SOAP 1.2 Primer.
click to expand
Figure 5.7: The composition of a real SOAP message ”in this case the eOrder message used at the start of this chapter.

It should be clear from all of the SOAP message examples included in this chapter that the envelope element is always qualified with a namespace of:

  • http://www.w3.org/2003/05/soap-envelope

where the 2003/05 is essentially a timestamp. The inclusion of this namespace is not an affectation. This namespace, whose contents are shown in Figure 5.8, contains a formal, unequivocal specification of all the elements and attributes that can occur within a valid SOAP message. SOAP messages that do not subscribe to this namespace are construed to be invalid and SOAP nodes are thus expected to reject them with a fault. (SOAP messages constructed before 1.2 would typically refer to the envelope namespace used with 1.1, which was http://schemas.xmlsoap.org/soap/envelope.)

start figure
    -  <!--      Schema defined in the SOAP Version 1.2 Part 1 specification         Proposed Recommendation:         http://www.w3.org/TR/2003/PR-soap12-part1-20030507/         $Id: soap-envelope.xsd,v 1.1 2003/04/17 14:23:23 ylafon Exp $         Copyright (C)2003 W3C(R) (MIT, ERCIM, Keio), All Rights Reserved.         W3C viability, trademark, document use and software licensing rules         apply.         http://www.w3.org/Consortium/Legal/         This document is governed by the W3C Software License [1] as         described in the FAQ [2].         [1] http://www.w3.org/Consortium/Legal/copyright-software-19980720         [2] http://www.w3.org/Consortium/Legal/IPR-FAQ-20000620.html#DTD      -->  -  <xs:schema xmlns:xs="  http://www.w3.org/2001/XMLSchema  "       xmlns:tns="  http://www.w3.org/2003/05/soap-envelope  "       targetNamespace="  http://www.w3.org/2003/05/soap-envelope  "       elementFormDefault="  qualified  ">    <xs:import namespace="  http://www.w3.org/XML/1998/namespace  " />     - <!--     Envelope, header and body      -->    <xs:element name="  Envelope  " type="  tns:Envelope  " />  -  <xs:complexType name="  Envelope  ">  -  <xs:sequence>    <xs:element ref="  tns:Header  " minOccurs="   " />    <xs:element ref="  tns:Body  " minOccurs="  1  " />      </xs:sequence>    <xs:anyAttribute namespace="  ##other  " processContents="  lax  " />      </xs:complexType>    <xs:element name="  Header  " type="  tns:Header  " />  -  <xs:complexType name="  Header  ">  -  <xs:annotation>    <xs:documentation>  Elements replacing the wildcard MUST be namespace qualified,   but can be in the targetNamespace  </xs:documentation>      </xs:annotation>  -  <xs:sequence>    <xs:any namespace="  ##any  " processContents="  lax  " minOccurs="   "        maxOccurs="  unbounded  " />      </xs:sequence>    <xs:anyAttribute namespace="  ##other  " processContents="  lax  " />      </xs:complexType>    <xs:element name="  Body  " type="  tns:Body  " />  -  <xs:complexType name="  Body  ">  -  <xs:sequence>    <xs:any namespace="  ##any  " processContents="  lax  " minOccurs="   "        maxOccurs="  unbounded  " />      </xs:sequence>    <xs:anyAttribute namespace="  ##other  " processContents="  lax  " />      </xs:complexType>  -  <!--       Global Attributes. The following attributes are intended to be         usable via qualified attribute names on any complex type referencing         them.      -->    <xs:attribute name="  mustUnderstand  " type="  xs:boolean  " default="   " />    <xs:attribute name="  encodingStyle  " type="  xs:anyURI  " />    <xs:element name="  Fault  " type="  tns:Fault  " />  -  <xs:complexType name="  Fault  " final="  extension  ">  -  <xs:annotation>    <xs:documentation>  Fault reporting structure  </xs:documentation>      </xs:annotation>  -  <xs:sequence>    <xs:element name="  Code  " type="  tns:faultcode  " />    <xs:element name="  Reason  " type="  tns:faultreason  " />    <xs:element name="  Node  " type="  xs:anyURI  " minOccurs="   " />    <xs:element name="  Role  " type="  xs:anyURI  " minOccurs="   " />    <xs:element name="  Detail  " type="  tns:detail  " minOccurs="   " />      </xs:sequence>      </xs:complexType>  -  <xs:complexType name="  faultreason  ">  -  <xs:sequence>    <xs:element name="  Text  " type="  tns:reasontext  " minOccurs="1"        maxOccurs="  unbounded  " />      </xs:sequence>      </xs:complexType>  -  <xs:complexType name="  reasontext  ">  -  <xs:simpleContent>  -  <xs:extension base="  xs:string  ">    <xs:attribute ref="  xml:lang  " use="  required  " />      </xs:extension>      </xs:simpleContent>      </xs:complexType>  -  <xs:complexType name="  faultcode  ">  -  <xs:sequence>    <xs:element name="  Value  " type="  tns:faultcodeEnum  " />    <xs:element name="  Subcode  " type="  tns:subcode  " minOccurs="   " />      </xs:sequence>      </xs:complexType>  -  <xs:simpleType name="  faultcodeEnum  ">  -  <xs:restriction base="  xs:QName  ">    <xs:enumeration value="  tns:DataEncodingUnknown  " />    <xs:enumeration value="  tns:MustUnderstand  " />    <xs:enumeration value="  tns:Receiver  " />    <xs:enumeration value="  tns:Sender  " />    <xs:enumeration value="  tns:VersionMismatch  " />      </xs:restriction>      </xs:simpleType>  -  <xs:complexType name="  subcode  ">  -  <xs:sequence>    <xs:element name="  Value  " type="  xs:QName  " />    <xs:element name="  Subcode  " type="  tns:subcode  " minOccurs="   " />      </xs:sequence>      </xs:complexType>  -  <xs:complexType name="  detail  ">  -  <xs:sequence>    <xs:any namespace=  "##any  " processContents="  lax  " minOccurs="   "        maxOccurs="  unbounded  " />      </xs:sequence>    <xs:anyAttribute namespace=  "##other  " processContents="  lax  " />      </xs:complexType>    - <!--    Global element declaration and complex type definition for header entry returned due to       a mustUnderstand fault      -->    <xs:attribute name="  qname  " type="  xs:QName  " use="  required  " />      </xs:complexType>    <xs:element name="  Upgrade  " type="  tns:UpgradeType  " />  -  <xs:complexType name="  UpgradeType  ">  -  <xs:sequence>    <xs:element name="  SupportedEnvelope  " type="  tns:SupportedEnvType  "       minOccurs="  1  " maxOccurs="  unbounded  " />      </xs:sequence>      </xs:complexType>      </xs:schema>   
end figure

Figure 5.8: The contents of http://www.w3.org/2003/05/soap-envelope showing the formal specification of all the elements and attributes that can occur within a valid SOAP message.

The consistent use of this envelope defining namespace within SOAP messages ensures that there will be no conflicts between the elements that make up a valid SOAP message and application-dependent elements included in the payload of a message. This is why SOAP puts so much stock in namespaces. Proper use of namespaces guarantees that there is no ambiguity anywhere along a chain of SOAP nodes, from the originator to the ultimate destination, as to what all the elements of a SOAP message are supposed to represent.

The set of rules used to represent the data included within a SOAP message is referred to as the encoding style for that message. SOAP provides an attribute called encodingStyle=, which can be used with the usual reference to a URI, to specify the data encoding rules in play at any given time. This attribute could be specified on the envelope level. It could also be specified against any element within the message. Since SOAP does not define a default encoding scheme, it is important that an appropriate encoding scheme is specified in each SOAP message to ensure that nodes are not forced to either reject the message or rely on capricious, implementation-specific assumptions.

SOAP 1.1 advocated as its encoding scheme a simple type system similar to that used by programming languages and databases. With this scheme, which was modeled on the XML schema, an encoding type is either a simple (scalar) type or a compound type constructed as a composite of several parts , each with its own type. The encoding rules thus defined a serialization mechanism that can be used to readily and unambiguously exchange instances of application-defined data types in a platform-independent manner.

The optional SOAP header serves in a message extension capacity. Since SOAP does not deal with message routing, SOAP headers should not be considered in the conventional networking sense of being there to convey addressing- and routing-specific details. SOAP headers enable auxiliary information to be conveyed outside the actual message payload ”particularly information of relevance to any intermediary nodes. Headers are thus typically used to pass application-specific control information that pertains to how a message should be processed . In this context what is important to note is that SOAP intermediaries can and are expected to inspect, modify, insert, reinsert, or delete SOAP headers. The use of headers thus permits intermediate nodes to provide value-added services to a message as it is being forwarded from its initial sender to the ultimate recipient.

The SOAP header, as shown in Figures 5.6 and 5.7, can consist of individual header blocks. A header block is a logical and discrete set of application-defined data ”with it being possible for each header block to be associated with a different namespace. Each such header block can be explicitly targeted at specific nodes, whether they are intermediaries or the ultimate receiver, via the role= attribute. This affords even greater application-level flexibility and extensibility, given that different header blocks can be used to convey different types of directives to different nodes. The SOAP specification does not specify the content or actual composition of a header block element.

The SOAP body is the mandatory element within a SOAP envelope ” and thus in a SOAP message. There is an implication that this is where the main information conveyed in a SOAP message should be included. However, the choice of what data are included in header blocks and what is included in the body of the message is left entirely to the actual application designers. The one distinction here, however, is that information in a header block can be inspected and processed by intermediary nodes as well as the ultimate receiver, while the information included in the body, which may include subelements, can be processed only by the node designated as being the ultimate receiver.




Web Services[c] Theory and Practice
Web Services[c] Theory and Practice
ISBN: 1555582826
EAN: N/A
Year: 2006
Pages: 113

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net