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.

8.2.2 The SOAP Section 5 Encoding Rules

Encoding rules define how a particular entity or data structure is represented in XML. Connecting different applications typically introduces the problem of interoperability: the data representation of one application is different from that of the other application. The reader may recall the example in Figure 6-1 that shows two different ways of representing a postal address. The applications may even be written in different programming languages. In order for the client and server to interoperate, it is essential that they agree on how the contents of a SOAP message are encoded. SOAP 1.2 defines a particular form of encoding called SOAP encoding. 2 This defines how data structures in the application’s local memory, including basic types such as integers and strings as well as complex types such as arrays and structures, can be serialized into XML. The serialized representation allows transfer of data represented in application-specific data types from one application to another. The encoding rules employed in a particular SOAP message are specified by the encodingStyle attribute, as discussed above. There is no notion of default encoding in a SOAP message. Encoding style must be explicitly specified if the receiving application is expected to validate the message. SOAP does not enforce any special form of coding—other encodings may be used as well. In other words, applications are free to ignore SOAP encoding and choose a different one instead. For instance, two applications can simply agree upon an XML Schema representation of a data structure as the serialization format for that data structure. This is commonly referred to as literal encoding see also Section 8.2.3 below. 2 There is no “official” name for SOAP encoding, but it is often referred to as SOAP Section 5 encoding, because the rules are presented in Section 5 of the SOAP specification. Chapter 8 • Web Services 273 A typical programming language data model consists of simple types and compound types. Compound types are based on simple types or other compound types. Dealing with simple data types would be easy, since all these types have direct representation in XML Schema some are shown in Table 6-1 above. However, the story with complex types, such as arrays and arbitrary software objects, is more complicated. XML Schema defines complex types, but these are very general, and some degree of specialization, e.g., for arrays, could make job easier for the Web services developer. SOAP does not define an independent data type system. Rather, it relies on the XML Schema type system. It adopts all XML Schema built-in primitive types and adds few extensions for compound types. The SOAP version 1.2 types extending the XML Schema types are defined in a separate namespace, namely http:www.w3.org200305soap-encoding . XML elements representing encoded values may hold the XML Schema type attribute for asserting the type of a value. For example, the sender of the SOAP encoded message in Listing 8-1 above in Line 14 explicitly asserts the type of the note element content to be a string: 14 a:note xsi:type=xsd:string 15 Reminder: meeting at 11AM in Rm.601 16 a:note The XML elements representing encoded values may also be untyped, i.e., not contain the type attribute: a:note Reminder: meeting at 11AM in Rm.601 a:note In this case, a receiver deserializing a value must be able to determine its type just by means of the element name a:note. If a sender and a receiver share the same data model, and both know that a note labeled value in an application-specific data graph is a string type, they are able to map the note element content to the appropriate data type without explicitly asserting the type through the XML Schema type attribute. However, in this case we cannot rely on XML Schema to explicitly validate the content of the message. SOAP Compound Data Types SOAP Section 5 encoding assumes that any application-specific data is represented as a directed graph. Consider the class diagram for an online auction site shown in Figure 2-21, Problem 2.14 in Chapter 2, which is simplified here in Figure 8-5. Suppose that the sender sends an instance of ItemInfo called item to the receiver in a SOAP message. A compound data type can be either a struct or an array. A struct is an element that contains different child elements. The SellerInfo in Figure 8-5 is an example of a struct. An array is a compound type that contains elements of the same name. The BidList in Figure 8-5 is an example of an array since it contains a group of individual Bid entries. When serialized to XML, the object graph of item in Figure 8-5 will be represented as follows: Listing 8-2: Example of SOAP encoding for the object graph in Figure 8-5. soap-env:Envelope xmlns:soap-env=http:www.w3.org200305soap-envelope xmlns:xsd=http:www.w3.org2001XMLSchema Ivan Marsic • Rutgers University 274 xmlns:xsi=http:www.w3.org2001XMLSchema-instance xmlns:soap-enc=http:www.w3.org200305soap-encoding xmlns:ns0=http:www.auctions.orgns soap-env:encodingStyle=http:www.w3.org200305soap-encoding soap-env:Body ns0:item ns0:name xsi:type=xsd:string old watch ns0:name ns0:startPrice xsi:type=xsd:float 34.99 ns0:startPrice ns0:reserved xsi:type=xsd:boolean false ns0:reserved ns0:seller ns0:name xsi:type=xsd:string John Doe ns0:name ns0:address xsi:type=xsd:string 13 Takeoff Lane, Talkeetna, AK 99676 ns0:address ns0:bids xsi:type=soap-enc:array soap-enc:arraySize= ns0:entry ns0:amount xsi:type=xsd:float 35.01 ns0:amount ns0:bidder . . . ns0:bidder ns0:entry ns0:entry ns0:amount xsi:type=xsd:float 34.50 ns0:amount ns0:bidder . . . ns0:bidder ns0:entry . . . ns0:bids ns0:seller ns0:item soap-env:Body soap-env:Envelope ItemInfo name : String startPrice : float reserved : boolean SellerInfo name : String address : String 1 1 bids seller Bid amount : float BidsList 1 bidder BuyerInfo name : String address : String entry item ItemInfo name : String startPrice : float reserved : boolean ItemInfo name : String startPrice : float reserved : boolean SellerInfo name : String address : String SellerInfo name : String address : String 1 1 bids seller Bid amount : float Bid amount : float BidsList BidsList 1 bidder BuyerInfo name : String address : String BuyerInfo name : String address : String entry item Sender Receiver Web service SOAP message item Sender Receiver Web service SOAP message item Figure 8-5: Example class diagram, extracted from Figure 2-21 above.