The SOAP Encoding - Building Web Services with Java

When you want to take a SOAP data model and write it out as XML (typically in a SOAP message), you use the SOAP encoding

g

. Like most things in the Web services world, the SOAP encoding has a URI to identify it, which for SOAP 1.2 is

http://www.w3.org/2003/05/soap-encoding.When serializing XML using the encod-ing rules, it’s strongly recommended that processors use the special encodingStyle

attribute (in the SOAP envelope namespace) to indicate that SOAP encoding is in use, by using this URI as the value for the attribute.This attribute can appear on headers or their children, bodies or their children, and any child of the ^Detailelement in a fault.

When a processor sees this attribute on an element, it knows that the element and all its children follow the encoding rules.

SOAP 1.1 Difference: encodingStyle

In SOAP 1.1, the encodingStyle attribute could appear anywhere in the message, including on the SOAP envelope elements (Body, Header, Envelope). In SOAP 1.2, it may only appear in the three places mentioned in the text.

The encoding is straightforward: it says when writing out a data model, each outgoing edge becomes an XML element, which contains either a text value (if the edge points to a terminal node) or further subelements (if the edge points to a node which itself has outgoing edges).The earlier product example would look something like this:

<name>Titanium Glider</name>

<type>skateboard</type>

<desc>Street-style titanium skateboard.</desc>

</product>

If you want to encode a graph of objects that might contain multirefs, you can’t write the data in the straightforward way we’ve been using, since you’ll have one of two prob-lems: Either you’ll lose the information that two or more encoded nodes are identical, or (in the case of circular references) you’ll get into an infinite regress. Here’s an example: If the structure from Figure 3.7 included an edge called ^ownerback from the ^petto the

person, we might see a structure like the one in Figure 3.8.

If we tried to encode this with a naïve system that simply followed edges and turned them into elements, we might get something like this:

<pet>

<owner>

<pet>

--uh oh! stack overflow on the

way!--Figure 3.8 An object graph with a loop

Luckily the SOAP encoding has a way to deal with this situation: multiref encoding.When you encode an object that you want to refer to elsewhere, you use an ^IDattribute to give it an anchor.Then, instead of directly encoding the data for a second reference to that object, you can encode a reference to the already-serialized object using the ^ref attribute. Here’s the previous example using multirefs:

</pet>

</person>

Much nicer. Notice that in this example you see an ^idof 2 on Fido, even though noth-ing in this serialization refers to him.This is a common pattern that saves time on processors while they serialize object graphs. If they only put IDs on objects that were referred to multiple times, they would need to walk the entire graph of objects before writing any XML in order to figure that out. Instead, many serializers always put an ID on any object (any nonsimple value) that might potentially be referenced later. If there is no further reference, then you’ve serialized an extra few bytes—no big deal. If there is, you can notice that the object has been written before and write out a ^refattribute instead of reserializing it.

Fido

Joe name

name pet owner

145 Objects in XML: The SOAP Data Model

SOAP 1.1 Differences: Multirefs

The href attribute that was used to point to the data in SOAP 1.1 has changed to ref in SOAP 1.2.

Multirefs in SOAP 1.1 must be serialized as independent elements, which means as immediate children of the SOAP:Body element. This means that when you receive a SOAP body, it may have multiref serializa-tions either before or after the real body element (the one you care about). Here’s an example:

<soap:Envelope xmlns:soap=”http://schemas.xmlsoap.org/soap/envelope”

xmlns:soapenc=”http://schemas.xmlsoap.org/soap/encoding”>

<soap:Body>

<multiRef id=”obj0” soapenc:root=”0” xsi:type=”myNS:Part”

soapenv:encodingStyle=”http://www.w3.org/2003/05/soap-encoding”>

</multiRef>

<myMultirefMethod soapenc:root=”1”

soapenv:encodingStyle=

“http://www.w3.org/2003/05/soap-encoding”>

</myMultirefMethod>

</soap:Body>

</soap:Envelope>

This is the reason for the SOAP 1.1 root attribute (which you can see in the example). Multiref serializa-tions typically have the root attribute set to 0; the real body element has a root=”1” attribute, mean-ing it’s the root of the serialization tree of the SOAP data model. When serializmean-ing a SOAP message 1.1, most processors place the multiref serializations after the main body element; this makes it much easier for the serialization code to do its work. Each time they encounter a new object to serialize, they automati-cally encode a forward reference instead (keeping track of which IDs go with which objects), just in case the object was referred to again later in the serialization. Then, after the end of the main body element, they write out all the object serializations in a row. This means that all objects are written as multirefs whenever multirefs are enabled, which can be expensive (especially if there aren’t many multiple references). SOAP 1.2 fixes this problem by allowing inline multirefs. When serializing a data model, a SOAP 1.2 engine is allowed to put an ID attribute on an inline serialization, like this:

<SOAP:Body>

</method>

</SOAP:Body>

Now, making a serialized object available for multireferencing is as easy as dropping an id attribute on it.

Also, this approach removes the need for the root attribute, which is no longer present in SOAP 1.2.

Encoding Arrays

The XML encoding for an array in the SOAP object model looks like this:

<myArray soapenc:itemType=”xsd:string”

soapenc:arraySize=”3”>

<item>Louie</item>

</myArray>

This represents an array of three strings.The ^itemTypeattribute on the ^arrayelement tells us what kind of things are inside, and the ^arraySizeattribute tells us how many of them to expect.The name of the elements inside the array (^itemin this example) doesn’t matter to SOAP processors, since the items in an array are only distinguishable by position.This means that the ordering of items in the XML encoding is important.

The^arraySizeattribute defaults to “^*,” a special value indicating an unbounded array (just like ^[]in Java—an ^int[]is an unbounded array of ^ints).

Multidimensional arrays are supported by listing each dimension in the ^arraySize attribute, separated by spaces. So, a 2x2 array has an ^arraySizeof “^{2 x 2}.” You can use the special “^*” value to make one dimension of a multidimensional array unbounded, but it may only be the first dimension. In other words,^arraySize=”* 3 4”is OK, but

arraySize=”3 * 4”isn’t.

Multidimensional arrays are serialized as a single list of items, in row-major order (across each row and then down). For this two-dimensional array of size 2x2

0 1

Northwest Northeast

Southwest Southeast

the serialization would look like this:

<myArray soapenc:itemType=”xsd:string”

soapenc:arraySize=”2 2”>

<item>Northwest</item>

<item>Northeast</item>

<item>Southwest</item>

<item>Southeast</item>

</myArray>

SOAP 1.1 Differences: Arrays

One big difference between the SOAP 1.1 and SOAP 1.2 array encodings is that in SOAP 1.1, the dimension-ality and the type of the array are conflated into a single value (arrayType), which the processor needs to parse into component pieces. Here are some 1.1 examples:

147 Objects in XML: The SOAP Data Model

arrayTypeValue Description

xsd:int[5] An array of five integers xsd:int[][5] An array of five integer arrays

xsd:int[,][5] An array of five two-dimensional arrays of integers p:Person[5] An array of five people

xsd:string[2,3] A 2x3, two-dimensional array of strings

In SOAP 1.2, the itemType attribute contains only the types of the array elements. The dimensions are now in a separate arraySize attribute, and multidimensionality has been simplified.

SOAP 1.1 also supports sparse arrays (arrays with missing values, mostly used for certain kinds of database updates) and partially transmitted arrays (arrays that are encoded starting at an offset from the beginning of the array). To support sparse arrays, each item within an array encoding can optionally have a posi-tionattribute, which indicates the item’s position in the array, counting from zero. Here’s an example:

<item soapenc:position=”[1]”>I’m the second element</item>

</myArray>

This would represent an array that has no first value, the passed string as the second element, and no third element. The same value can be encoded as a partially transmitted array by using the offset attribute, which indicates the index at which the encoded array begins:

<item>I’m the second element</item>

</myArray>

Due to several factors, including not much uptake in usage and interoperability problems when they were used, these complex array encodings were removed from the SOAP 1.2 version.

Encoding-Specific Faults

SOAP 1.2 defines some fault codes specifically for encoding problems. If you use the encoding (which you probably will if you use the RPC conventions, described in the next section), you might run into the faults described in the following list.These all are subcodes to the code ^env:Sender, since they all relate to problems with the sender’s data serialization.These faults aren’t guaranteed to be sent—they’re recommended, rather than mandated. Since these faults typically indicate problems with the encoding system in a SOAP toolkit, rather than with user code, you likely won’t need to deal with them directly unless you’re building a SOAP implementation yourself:

n MissingID—Generated when a ^refattribute in the received message doesn’t cor-respond to any of the ^idattributes in the message

n DuplicateID—Generated when more than one element in the message has the same^idattribute value

n UntypedValue—Optional; indicates that the type of node in the received message couldn’t be determined by the receiver

在文檔中 Building Web Services with Java (頁 168-173)