WebReference.com - Part 2 of Chapter 3: Professional XML Web Services, from Wrox Press Ltd (4/5)

[previous] [next]

Professional XML Web Services

Compound Data Types

Sometimes, simple types are not enough. Just like the programming languages it must support, SOAP encoding provides structures for representing compound types. SOAP encoding handles two compound types: structs (records), and arrays. Complex types are serialized as payload elements, just like simple types, but they have child elements. The child elements are the fields or elements of the type. SOAP had to invent its own rules for structs and arrays because, as of this writing, XML Schemas does not pay special attention to these compound types.

Structs

Let's start with a struct (or structure, or record, whichever you prefer). Structs are easy to represent as XML because they have unique named members. Consider this C++ struct definition of a super-hero:

struct SuperHero
{
   string sCodename;
   string sFirstName;
   string sLastName;
   int nAge;	
};
SuperHero hero = { "Hulk", "Bruce", "Banner", 32 };

We've chosen a simple struct to illustrate the basics of compound types. If we serialize the variable "hero" into a SOAP message payload using SOAP encoding, it would look like this:

<hero xsi:type="x:SuperHero">
   <sCodeName xsi:type="xsd:string">Hulk</sCodeName>
   <sFirstName xsi:type="xsd:string">Bruce</sFirstName>
   <sLastName xsi:type="xsd:string">Banner</sLastName>
   <nAge xsi:type="xsd:integer">32</nAge>
</hero>

As can be seen in this example, the xsi:type attribute is used on compound data types as well as simple types. In this case, the type is x:SuperHero, and the x namespace would point to a schema that represents our SuperHero struct.

Arrays

Arrays are compound types as well, and they are represented in much the same way that structs are. As we might expect, the difference between arrays and structs is in how we refer to their members. Structs have data that is identifiable by name, and array members are identified by position. The names of array elements are insignificant, so they cannot be used to look up a value.

In SOAP encoding, arrays are considered a special type. This type is indicated by their xsi:type attribute, which is SOAP-ENC:Array. As with all SOAP encoding, the namespace associated with the Array type is https://schemas.xmlsoap.org/soap/encoding. Elements with this xsi:type are declared as SOAP encoding arrays. The type of the array members is declared using another attribute, SOAP-ENC:arrayType. This attribute indicates the type and size of the array. Arrays in SOAP encoding can be confusing, so let's take a look at a simple array of five integers to see how these attributes are used to define an array:

<numbers xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:integer[5]">
   <item>10</item>
   <item>20</item>
   <item>30</item>
   <item>40</item>
   <item>50</item>
</numbers>

The numbers element is declared as a SOAP array, and the arrayType attribute states that it contains five elements of the integer type. This is accomplished by combining the values we used earlier in the type attribute (values from XML Schemas) and the square brackets [] with a size value. As can be seen, each of the array elements has the name item. This could have been any name as the member values are determined solely by the order of the elements.

Before we look at the more complex features of arrays, let's see another simple array. This array contains four names, each as a string. The differences occur in the arrayType attribute, and in the names of the members (which are irrelevant).

<names xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:string[4]">
   <e>John Doe</e>
   <e>John Q. Public</e>
   <e>John Smith</e>
   <e>John Elway</e>
</names>

By setting the arrayType attribute on a SOAP array, we are able to define the type of members that will appear. The arrayType attribute is the only restriction on member types; SOAP arrays do not place restrictions on member types by default, so we can mix types inside of an array. We can accomplish this by using an arrayType attribute value of SOAP-ENC:ur-type[]. The ur-type[] is a universal data type for the SOAP encoding data types, so arrays that use this can have mixed members. The only catch to using ur-type[] is that like the polymorphic accessor for simple types, we must use the xsi:type attribute on the accessors to indicate each element's type. Below is an example of a SOAP array that contains a mixed set of types as members. Notice that each member uses the xsi:type attribute to specify its type.

<mix xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="SOAP-ENC:ur-type[4]">
   <e xsi:type="xsd:string">John Elway</e>
   <e xsi:type="xsd:integer">7</e>
   <e xsi:type="xsd:string">Denver Broncos</e>
   <e xsi:type="xsd:date">1999</e>
</names>

Besides using mixed types, arrays have some other sophisticated features that we can take advantage of if our application needs them. Because arrays can be costly as parameters in remote procedure calls, SOAP defines two attributes that give us the flexibility to pass the portion of the array that we need to work with in our application. These attributes are the offset and position attributes.

The SOAP-ENC:offset attribute lets us specify where in the array we are beginning, so transmitting only part of the array. All elements before the offset are assumed to contain the default value, or NULL, depending on the application's behavior. The offset attribute appears on the array element, as shown below. In that case, the elements are the third and fourth of the array.

<names xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:string[4]" 
                 SOAP-ENC:offset="[2]" >
   <e>John Smith</e>
   <e>John Elway</e>
</names>

The SOAP-ENC:position attribute specifies the position in the array of a particular member (like offset, the position attribute is zero based). As might be expected, that means that the position attribute must appear on the member itself rather than the array element. If the position attribute appears on one member, it must appear on all the members. This example shows how the position attribute can be used to pass a large array that is almost empty (this is referred to in the Specification as sparse arrays):

<names xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:string[100]">
   <e SOAP-ENC:position="[11]">John Smith</e>
   <e SOAP-ENC:position="[45]">John Elway</e>
</names>

These two attributes (offset and position) are to some extent interchangeable in that the offset attribute implies position for all the elements that appear. That means that it is possible to describe an array in minimal fashion using either technique.

[previous] [next]

Created: November 19, 2001
Revised: November 19, 2001

URL: https://webreference.com/authoring/languages/xml/webservices/chap3/2/4.html