Skonnard.book Page 356 Monday, October 1, 2001 8:57 AM 357 SOAP Chapter 10 SOAP 1.1 The Simple Object Access Protocol (SOAP) is an XML messaging specification that describes a message format along with a set of serialization rules for datatypes including structured types and arrays. In addition, it describes how to use the Hypertext Transfer Protocol (HTTP) as a transport for such messages. SOAP messages are effectively service requests sent to some end point on a net- work. That end point may be implemented in any number of ways—Remote Pro- tocol Call (RPC) server, Component Object Model (COM) object, Java servlet, Perl script—and may be running on any platform. Thus, SOAP is about interoperability between applications running on potentially disparate platforms using various implementation technologies in various programming languages. 10.1 Introduction to SOAP messages SOAP messages are transmitted between applications and may pass through a number of intermediaries as they travel from the initial sender to the ultimate recipient. SOAP messages are comprised of an Envelope element, with an optional Header and a mandatory Body child element. All three elements are in the namespace http://schemas.xmlsoap.org/soap/envelope/ . The Envelope identifies the XML as being a SOAP message and must be the root element of the message. The Body element contains the message payload. The Header element provides an extension hook that allows SOAP to be extended in arbitrary ways. The following sections describe these elements, attributes that SOAP defines, the data encoding rules SOAP specifies, and the HTTP binding. Example Skeleton SOAP message <soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' Skonnard.book Page 357 Monday, October 1, 2001 9:13 AM 358 Essential XML Quick Reference 10.2 Elements in SOAP messages SOAP defines four elements in the namespace http://schemas.xmlsoap.org/ soap/envelope/ . These elements are listed in the following sections in alpha- betical order, with a description and details of child elements. All four elements can be annotated with any number of namespace-qualified attributes. Example SOAP request and response messages are shown for reference. 10.2.1 Body <soap:Body xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' > <! message payload goes here > </soap:Body> The Body element contains the message payload. In the case of a request mes- sage the payload of the message is processed by the receiver of the message and is typically a request to perform some service and, optionally, to return some results. In the case of a response message the payload is typically the results of some previous request or a fault. Child elements One or more namespace-qualified elements that are not in the http:// schemas.xmlsoap.org/soap/envelope/ namespace or, if a fault occurred, a Fault element in the http://schemas.xmlsoap.org/soap/envelope/ namespace soap:encodingStyle='http://schemas.xmlsoap.org/soap/ encoding/'> <soap:Header> <! extensions go here > </soap:Header> <soap:Body> <! message payload goes here > </soap:Body> </soap:Envelope> Skonnard.book Page 358 Monday, October 1, 2001 9:13 AM SOAP 1.1 359 SOAP Examples A SOAP request An example request message showing the Envelope and Body elements A SOAP response A message generated in response to the request message in the request example <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle='http://schemas.xmlsoap.org/soap/ encoding/'> <soap:Body> <m:Subtract xmlns:m="http://example.org/Calculator/Points"> <pt1> <x>10</x> <y>20</y> </pt1> <pt2> <x>100</x> <y>200</y> </pt2> </m:Subtract> </soap:Body> </soap:Envelope> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle='http://schemas.xmlsoap.org/soap/ encoding/'> <soap:Body> <method:SubtractResponse xmlns:method="http://example.org/Calculator/Points"> <ptret> <x>-90</x> <y>-180</y> </ptret> </method:SubtractResponse> </soap:Body> </soap:Envelope> Skonnard.book Page 359 Monday, October 1, 2001 9:13 AM 360 Essential XML Quick Reference 10.2.2 Envelope <soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' > <! header and body go here > </soap:Envelope> The Envelope element is the root element for all SOAP messages, identifying the XML as a SOAP message. Child elements An optional Header element and a mandatory Body element. Both elements are in the http://schemas.xmlsoap.org/soap/envelope/ namespace. 10.2.3 Fault <soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' > <! detail goes here > </soap:Fault> The Fault element indicates that an error occurred while processing a SOAP request. This element only appears in response messages. Child elements A faultcode element followed by a faultstring element followed by an optional faultactor element and an optional detail element. Each of these children is described in the following: Skonnard.book Page 360 Monday, October 1, 2001 9:13 AM SOAP 1.1 361 SOAP Name Syntax Description faultcode <faultcode xmlns=''> QName</faultcode> The faultcode element is of type QName and indicates what fault occurred. Several existing categories of fault code are defined, all in the http://schemas.xmlsoap.org/ soap/envelope/ namespace. VersionMismatch indicates that the recipi- ent of a message did not recognize the namespace name of the Envelope element. MustUnderstand indicates that the recipient of an element child of the Header element had a soap:mustUnderstand attribute but that element was not understood by the recip- ient. Client indicates the SOAP message did not contain all the required information in order for the recipient to process it. This could mean that something was missing from inside the Body element. Equally, an expected extension inside the Header element could have been missing. In either case, the sender should not resend the message without cor- recting the problem. Server indicates that the recipient of the message was unable to process the message because of some server-side problem. The message contents were not at fault; rather, some resource was unavailable or some processing logic failed for a reason other than an error in the mes- sage. The sender may legitimately resend the message at a later time. All these fault codes may be followed by a period and a further string providing more detailed information about the error; for example, Client.InvalidParameter . faultstring <faultstring xmlns=''>string </faultstring> The faultstring element is of type string and provides a human-readable description of whatever fault occurred. Skonnard.book Page 361 Monday, October 1, 2001 9:13 AM 362 Essential XML Quick Reference Example A SOAP fault faultactor <faultactor xmlns=''> uriReference </faultactor> The faultactor element is of type uriReference and indicates the source of the fault. This may be the ultimate recipient of the request message, in which case the ele- ment is optional. Alternatively, the source of the fault may be an intermediary somewhere in the path the message took to get from the sender to the ultimate recipient. In this case the element must be present. detail <detail xmlns=''> any number of elements in any namespace </detail> The detail element is used to carry applica- tion-specific error information and may be annotated with any number of attributes from any namespace, and may have any number of namespace-qualified element children. The detail element must be present if the fault is the result of the recipient being unable to process the Body element. The detail ele- ment is not used to provide error information in the case of the recipient being unable to process an element child of the Header ele- ment. In such cases, error information is placed inside the Header element. Name Syntax Description <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle='http://schemas.xmlsoap.org/soap/ encoding/'> <soap:Body> <soap:Fault> <faultcode>soap:Client.InvalidRequest</faultcode> <faultstring>Invalid Request: Divide operation not supported</faultstring> <faultactor>http://marting.develop.com/soap/ calcxslt.asp</faultactor> <detail> <m:MethodError xmlns:m='uuid:361C5CDE-FC66-4B17-A2C1- EB221DEFFD66'> <request>Divide</request> Skonnard.book Page 362 Monday, October 1, 2001 9:13 AM SOAP 1.1 363 SOAP An example of a fault in which the request message contained an invalid operation request 10.2.4 Header <soap:Header xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' > <! extensions go here > </soap:Header> The Header element namespace serves as a container for extensions to SOAP. No extensions are defined by the specification, but user-defined extension ser- vices such as transaction support, locale information, authentication, digital sig- natures, and so forth could all be implemented by placing some information inside the Header element. Children of the Header element may be annotated with the mustUnderstand and/or actor attributes. Child elements Any number of namespace-qualified elements that are not in the http:// schemas.xmlsoap.org/soap/envelope/ namespace Example A SOAP Header <reason>Operation not supported</reason> </m:MethodError> </detail> </soap:Fault> </soap:Body> </soap:Envelope> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle='http://schemas.xmlsoap.org/soap/ encoding/'> <soap:Header> <x:Locale xmlns:x='http://example.org/Extensions/Locale'> <language>en</language> Skonnard.book Page 363 Monday, October 1, 2001 9:13 AM 364 Essential XML Quick Reference An example extension for locale information requesting that the recipient of the message send any responses localized for the specified locale; in this case, UK English. 10.3 Attributes in SOAP messages SOAP defines three attributes in the namespace http://schemas.xml- soap.org/soap/envelope/. These attributes are listed in the following sec- tions in alphabetical order with a description and examples. 10.3.1 actor soap:actor='anyURI' The actor attribute is used to annotate an extension element. It specifies a URI identifying the intermediary for which the annotated extension element is intended. If the value of the attribute is the URI http://schemas.xml- soap.org/soap/actor/next, then the extension is intended for the next intermediary in the chain, which in the case of the initial sender will be the first one. If the attribute is not present, then the extension element is intended for the ultimate recipient of the message. Examples Use of the actor attribute <sublang>uk</sublang> </x:Locale> </soap:Header> <soap:Body> <! message payload goes here > </soap:Body> </soap:Envelope> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle='http://schemas.xmlsoap.org/soap/ encoding/'> <soap:Header> Skonnard.book Page 364 Monday, October 1, 2001 9:13 AM SOAP 1.1 365 SOAP An extension element intended for a specific intermediary in the chain Use of the actor attribute to target the first intermediary An example extension intended for the first intermediary in the chain 10.3.2 encodingStyle soap:encodingStyle='list of anyURI' The encodingStyle attribute indicates to the recipient of a SOAP message which serialization format was used to encode a given element and its descendants. This attribute may appear on any element. Descendant elements may override <x:x xmlns:x='http://example.org/Extensions/' soap:actor='http://example.org/Nodes/Fireball/XL5'> <! extension detail goes here > </x:x> </soap:Header> <soap:Body> <! message payload goes here > </soap:Body> </soap:Envelope> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle='http://schemas.xmlsoap.org/soap/ encoding/'> <soap:Header> <x:x xmlns:x='http://example.org/Extensions/' soap:actor='http://schemas.xmlsoap.org/soap/actor/next'> <! extension detail goes here > </x:x> </soap:Header> <soap:Body> <! message payload goes here > </soap:Body> </soap:Envelope> Skonnard.book Page 365 Monday, October 1, 2001 9:13 AM [...]... annotated with attributes, 5–6 apply-imports, 97, 99 100 , 136 apply-templates, 97, 100 102 , 136 document used with, 151 associating with namespace, 3 attribute, 97, 102 104 continued Skonnard.book Page 390 Monday, October 1, 2001 9:00 AM 390 Essential XML Quick Reference attribute-set, 98, 104 106 attributes of See Attribute(s) call-template, 97, 106 107 child all, 312, 326, 338 annotation, 282, 283,... October 1, 2001 9:13 AM 378 Essential XML Quick Reference Example Partial array tranmission . <soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' Skonnard.book Page 357 Monday, October 1, 2001 9:13 AM 358 Essential XML Quick Reference 10. 2 Elements in. 359 Monday, October 1, 2001 9:13 AM 360 Essential XML Quick Reference 10. 2.2 Envelope <soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' > <!. Monday, October 1, 2001 9:13 AM 362 Essential XML Quick Reference Example A SOAP fault faultactor <faultactor xmlns=''> uriReference </faultactor> The