An Overview of the SOAP v1.1 Specification, Page 2
When a method call has been requested, the server has several options. It can return an HTTP error code or a SOAP fault containing a SOAP/application error, or it can return the results of the method execution. Both the fault and the method results use the standard SOAP payload syntax (that is, <Envelope>, <Body>, and so on).
A SOAP fault consists of four elements--a faultcode, faultstring, runcode, and an optional detail element, as shown in Listing 3.Listing 3 - SOAP Fault
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode>300</faultcode> <faultstring>Invalid Request</faultstring> <runcode>1</runcode> </SOAP-ENV:Fault> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Just as with the |
Any application fault details that need to be included with the fault must be properly typed and qualified using the <detail> element as shown in Listing 4.Listing 4 - Application Fault Details
<SOAP-ENV:Fault> <faultcode>300</faultcode> <faultstring>Invalid Request</faultstring> <runcode>1</runcode> <detail xmlns:e="GetTemperatureErr-URI" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xsi:type="e:GetTemperatureFault"> <number>5575910</number> <description>Sensor Failure</description> <file>GetTemperatureClass.cpp</file> <line>481</line> </detail> </SOAP-ENV:Fault>
Notice that the <detail> element uses the XML Schema instance xsi:type attribute to denote its content type, e:GetTemperatureFault, which is also namespace qualified.
Constructing detailed faults in this way allows the client to fully interpret the application fault when necessary.
Representation of Types in the Payload
One of the most difficult aspects of SOAP to understand is the way types are represented in the payload. It's hard to anticipate the many ways parameters can or should be serialized.
SOAP has the capability to serialize any combination of simple and compound types as supported in modern-day programming languages. This is mostly because of SOAP's inclusion of the XML Schema work that is underway to define a standard mechanism for constructing metadata.
SOAP uses the concept of an accessor as the means to acquire a named value in the payload. Named values include parameters as well as the named parts of a compound type.
There are two kinds of values in a SOAP payload. The first kind is called a single-reference value and can only be referenced by one accessor. Consider the following XML fragment:
In this case, both the <Car> element and the <Automobile> element contain their own unique Corvette values. This means that each Corvette value has only been referenced by its surrounding element (that is, accessor) and no other.
The second kind of value in a SOAP payload is called a multi-reference value and can be referenced by one or more accessors. Let's examine a similar XML fragment that uses multi-reference values:
<Car href="#somecar" /> <Automobile id="somecar">Corvette</Automobile>
In this example, Corvette is referenced by two accessors, the Car accessor and the Automobile accessor; thus, it is considered a multi-reference value.
The purpose for distinguishing between single-reference and multi-reference values helps to deal with identity issues of serializing (that is, marshaling) data across the wire. For instance, if two method parameters reference the same value, in some cases you will want the XML to reflect this identity and in other cases you won't. Our book, Understanding SOAP provides an in-depth look at identity and serialization techniques in chapter 6, "SOAP and Data: Data Types."
SOAP also distinguishes between elements that are independent and elements that are embedded. Independent elements are at the highest level of serialization, such as elements contained within SOAP-ENV:Body, and represent instances of types. The name of the independent element is typically the name of the type that it represents. Consider the following XML:
<SOAP-ENV:Envelope xmlns:SOAP= "http://schemas.xmlsoap.org/soap/envelope/" SOAP-ENV:encodingStyle= "http://schemas.xmlsoap.org/soap/encoding/"> <SOAP-ENV:Body> <m:MyMethod xmlns:m="Method-URI"> <Car href="#somecar" /> </m:MyMethod> <Automobile id="somecar">Corvette</Automobile> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
In this example, since by definition <SOAP-ENV:Body> is an element that can stand alone, any direct descendants of <SOAP-ENV:Body> are considered independent elements. In this case, <m:MyMethod> is an independent element that describes the method and <Automobile> is an independent element describing an Automobile type.
Embedded elements are anything that's not considered an independent element, and they represent accessors. The name of the embedded element is the same as the name of the accessor that it represents. Referring to the last example, the <Car> element is an embedded element and accessor since the <m:MyMethod> element is an independent element that is at the highest level of the serialization.
The SOAP specification provides a set of rules that define how the preceding constructs should be used to serialize data. It also addresses the more specific procedures that should be followed when serializing particular types such as arrays and strings.
About the Authors
Kennard Scribner is a principle software consultant specializing in COM and component development. He is also founder and president of EnduraSoft Corporation, a software company specializing in the creation of custom components.
Mark C. Stiver is a consulting software engineer with one of the world's largest supplies of information services for the legal and business industry. Currently he is involved in the design and development of XML-based interfaces for integrating large-scale systems.
© Copyright Sams Publishing, All Rights Reserved