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

[previous] [next]

Professional XML Web Services

Enumerations

SOAP encoding allows us to define enumerated types. It borrows once again from XML Schemas, which also has the concept of an enumeration. An enumeration is a named set of values, based on a basic type. For example, we could define an enumeration that represented geographical locations ("North, "South", etc). To define an enumeration, we must use XML Schemas.

Here is an example of an enumeration that defines a set of geographical regions.

<simpleType name="Region" base="xsd:string">
   <enumeration value="North"/>
   <enumeration value="South"/>
   <enumeration value="East"/>
   <enumeration value="West"/>
</simpleType>

If this enumeration appeared in a referenced schema, we could then use this type in a SOAP message just as we would any other type.

<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"
               soap:encodingStyle="https://schemas.xmlsoap.org/soap
                                   /encoding/"
               xmlns:xsi="https://www.w3.org/1999/XMLSchema-instance">
   <soap:Body>
      <m:GetSalesTotals xmlns:m="https://www.wrox.com/sales/">
         <m:reg xsi:type="m:Region">East</m:reg>
      </m:GetSalesTotals>
   </soap:Body>
</soap:Envelope>

Binary Data

As part of the simple types it supports, SOAP and XML Schemas provide a type for representing binary data. One approach for working with binary data is to use the base64 type. We can represent binary data, such as an image file, as an array of bytes in the message. The base64 type converts binary data to text using the base64-encoding algorithm of XML Schemas. There is no relationship between SOAP and base64-encoding; if we use it, our application (or implementation of SOAP for your platform) must be able to understand and work with base64-encoding.

Catch All

In addition to the simple types, many languages have a "universal" data type or placeholder, something that can represent a variety of types within that language. In COM, the variant serves this purpose, as does the any type in CORBA. SOAP accounts for this possibility with the polymorphic accessor. If we are serializing a value in the form of a polymorphic accessor, we must provide the type attribute.

The polymorphic accessor is more difficult to pronounce than to use! Let's assume we are passing in a value representing a person's age, and that type could vary depending on how the information was to be used. If the value of our data is a float, it would appear like this:

<age xsi:type="xsd:float">3.5</age>

If is a string, it would appear like this:

<age xsi:type="xsd:string">3 and a half years old</age>

Both examples are legal if the age element has been defined as being a polymorphic accessor, meaning that its data type will vary.

What About XML?

Those frequenting the SOAP discussion lists and newsgroups will notice the recurring question: "How do I send XML in a SOAP payload?" or something to that effect. This is a general problem related to XML, but there are a couple of approaches we can use to transmit XML inside SOAP. We can:

• Rely on our toolkit or XML parser to properly encode the XML when we pass it in as a string parameter. If our implementation is based on RPC and does not encode the XML we pass in as a string properly, that is a bug. Let the implementation's author know.

• Consider why we are passing XML. If we are using SOAP RPC to pass XML as a string parameter, check to see if the implementation supports passing arbitrary XML in the payload. A good implementation should. As we will discuss later, SOAP does not have to be RPC, and if we are passing XML in string parameters, our application probably doesn't need RPC.

[previous] [next]

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

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