Putting the Vocabulary into Action | Cross-Platform Web Services Using C# & JAVA (Charles River Media Internet & Web Design)

The SOAP XML Document

SOAP uses XML to describe the data transmitted between nodes. The tags used are to describe the document, header, and body. The tags in the body are usually specific to a vendor’s implementation of SOAP because the standard doesn’t dictate the XML appearing there. The standard does, however, dictate the information that appears in the header and the how the envelope, body, and header elements look.

Basic SOAP Document

Start off with a headerless SOAP document such as the following.

<?xml version='1.0' ?>     <env:Envelope          xmlns:env="http://www.w3.org/2001/12/SOAP-envelope">       <env:Body>       </env:Body>  </env:Envelope>

This is a simple SOAP document that doesn’t say anything, but note the namespace definition and the fact that there is an envelope and a body. The document is just a container for an object to get data from, process, and then put back into the document to transmit it back to the client. Let’s consider the request for stock quote information again.

<?xml version='1.0' ?>     <env:Envelope       xmlns:env="http://www.w3.org/2001/12/SOAP-envelope">       <env:Body>       <stockquote:symbolist             xmlns:stockquote="http://advocatemedia.com/stocks">           <stockquote:symbol>C</stockquote:symbol>          <stockquote:symbol>GE</stockquote:symbol>          <stockquote:symbol>DJI</stockquote:symbol>         <stockquote:symbolist>      </env:Body>    </env:Envelope>

Now we have information specific to the object that returns stock quotes. Note that the stockquote tags are not defined by the SOAP standard; rather, they are defined by the developer responsible for the software in which the Stock Quote Web Service was created.

SOAP Header and an Intermediary

The header in a SOAP document is optional, but when it is present it can determine the next node of a SOAP request when sent through an intermediary. Back in Figure 3.2, a SOAP intermediary looks at the contents of the XML to determine where to route the file next.

Note

Remember that a SOAP intermediary can act or modify the data in the document and then pass it to the next node, or just simply act as a router and pass it to the next appropriate node.

For an intermediary to pass the information along, the document must contain the information to send it to the next node. The following SOAP example possesses this information within the env:Header element.

The header defines the namespace am along with providing the actor element, which tells the node that it should route the information somewhere else after it’s done processing it.

Then within the header there is information for the node that allows the intermediary to act on the data. In this case, a customer Id and a request Id are present to help the initial node do some processing of the data before passing it on. It may, for example, check the person’s customer Id to make sure they are still an active customer. The env:mustUnderstand attribute means that the node must act on the data in some matter and return an exception if the data is not processed.

<?xml version='1.0' ?>     <env:Envelope           xmlns:env="http://www.w3.org/2001/12/SOAP-envelope">       <env:Header>         <am:customer             xmlns:route="http://advocatemedia.com/authenticate"             env:actor="http://www.w3.org/2001/12/SOAP-envelope/
              actor/next"             env:mustUnderstand="true">           <am:custId>4557799</am:custId>           <am:requestId>12asd-34ccd-23cuden</am:requestId>         </am:customer>       </env:Header>       <env:Body>        <stockquote:symbolist          xmlns:stockquote="http://advocatemedia.com/stocks">          <stockquote:symbol>C</stockquote:symbol>         <stockquote:symbol>GE</stockquote:symbol>         <stockquote:symbol>DJI</stockquote:symbol>        <stockquote:symbolist>       </env:Body>     </env:Envelope>

At this point, the SOAP document does not contain information needed for it to bind with a transport protocol.

SOAP Data Types and Structures

Along with the header, body, and envelope, the SOAP standard allows for the representation of certain data types and structures.

Primitive Types

The SOAP standard does not create new data types for variables, but, rather, uses the data types defined in the XML Schema standard. This allows SOAP to represent data in a standard way. Table 3.3 shows the different standard types that a SOAP document may represent.

Table 3.3: The Different Primitive Types Available from XML Schema in the *SOAP* Standard^[1]
Schema Primitive Type	Description	Example
xsd:int	signed integer value	-9 or 9
xsd:boolean	boolean whose value is either 1 or 0	1 or 0
xsd:string	string of characters	Rocky Mountains
xsd:float or xsd:double	signed floating point number (+,-)	-9.1 or 9.1
xsd:timeInstant	date/time	1969-05-07-08:15
SOAP-ENC:base64	base64-encoded information used for passing binary data within SOAP documents	SW89IjhhibdOI111QWgdGE
^[1]Adapted from Dave Winer and Jake Savin, A Busy Developer’s Guide to SOAP 1.1, http://www.SOAPware.org/bdg (2001).

Structs

A struct is a data structure that you can think of like a container. It is a way of storing several, perhaps vastly different, values in one neat package. In fact, you saw a struct in one of the previous stockquote examples. Here is the snippet that represents a struct.

    <stockquote:symbolist       xmlns:stockquote="http://advocatemedia.com/stocks">       <stockquote:symbol>C</stockquote:symbol>       <stockquote:symbol>GE</stockquote:symbol>       <stockquote:symbol>DJI</stockquote:symbol>     <stockquote:symbolist>

Modifying this snippet to use the schema’s primitive types looks like the following example.

(Note that, in the header of the XML document the appropriate namespaces need to be included to use these types. Examples later in the chapter demonstrate this.)

    <stockquote:symbolist       xmlns:stockquote="http://advocatemedia.com/stocks">       <stockquote:symbol         xsi:type="string">C</stockquote:symbol>       <stockquote:symbol         xsi:type="string">GE</stockquote:symbol>       <stockquote:symbol          xsi:type="string">DJI</stockquote:symbol>     <stockquote:symbolist>

The information in a struct doesn’t have to be so similar. For example, the XML may contain information that describes the author, such as the following.

<CRM:AuthorInfo xmlns:CRM="http://www.charlesriver.com/authorinfo">        <CRM:FirstName xsi:type="string">Brian</CRM:FirstName>        <CRM:LastName         xsi:type="string">Hochgurtel</CRM:LastName>        <CRM:PhoneNumber         xsi:type="int">3035551212</CRM:PhoneNumber>        <CRM:BookTitle         xsi:type="string">Cross Platform Web Services</CRM:BookTitle>     </CRM:AuthorInfo>

Now moving all the information together may allow an application to handle the data more efficiently.

Arrays

The SOAP standard also supports the use of arrays. An array is similar to a struct but normally only stores data of the same type, like the following example.

    <SymbolList     SOAP-ENC:arrayType="xsd:string[3]">      <symbol>C</symbol>         <symbol>GE</symbol>         <symbol>DJI</symbol>     </SymbolList>

This is an alternate, and perhaps more convenient, way to represent data for the Stock Quote Example. Instead of having to define the type for each entry, the array definition allows you to group related data together so you don’t have to specify the type each time.

However, it is possible to group unlike values in an array as the following example illustrates.

    <AuthorInfo SOAP-ENC:arrayType="xsd:ur-type[4]" >        <FirstName xsi:type="string">Brian</FirstName>        <LastName         xsi:type="string">Hochgurtel</LastName>        <PhoneNumber         xsi:type="int">3035551212</PhoneNumber>        <BookTitle xsi:type="string">             Cross Platform Web Services        </BookTitle>     <AuthorInfo>

The definition for the array type, xsd:ur-type[4], indicates that there are four elements in the array of various types. This is much different than the struct type introduced earlier in the chapter.

For one final look at arrays, consider the following example that shows the entire Stock Quote Example using an array. Note that to use the schema type string in the document, the namespaces for schemas must be included in the header.

    <?xml version='1.0' ?>     <env:Envelope        xmlns:env="http://www.w3.org/2001/12/SOAP-envelope"       xmlns:xsd="http://www.w3.org/1999/XMLSchema"       xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"       xmlns:SOAP-ENC="http://schemas.xmlSOAP.org/SOAP/encoding/"       xmlns:stockquote="http://advocatemedia.com/examples">       <env:Body>                <SOAP-ENC:Array SOAP-ENC:arrayType="xsd:string[3]">             <stockquote:symbol>C</stockquote:symbol>             <stockquote:symbol>GE</stockquote:symbol>             <stockquote:symbol>DJI</stockquote:symbol>           </SOAP-ENC:Array>       </env:Body>     </env:Envelope>

Using the array, the format is slightly cleaner and easier to read, but if you look at the original Stock Quote Example that uses the struct, there really isn’t much difference.