Let’s investigate how the stock quote example would likely be implemented in SOAP. Encoded as a SOAP document, the request document looks quite different, but the same information is present as demonstrated in Example 2.15.

<?xml version="1.0"?>
<SOAP-ENV:Envelope
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" >
  <SOAP-ENV:Body>
    <getQuote xmlns="http://namespaces.cafeconleche.org/xmljava/ch2/">
      <symbol>RHAT</symbol>
    </getQuote>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The most obvious difference between this document and the XML-RPC equivalent in Example 2.6 is the use of namespaces. Namespaces allow the method request to be an arbitrary XML element. This goes way beyond passing just a method name and some argument values. SOAP permits much more complex XML messages than does XML-RPC.

The server’s response is equally flexible. Example 2.16 demonstrates:

<?xml version="1.0"?>
<SOAP-ENV:Envelope
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Body>
    <Quote xmlns="http://namespaces.cafeconleche.org/xmljava/ch2/">
      <Price>4.12</Price>
    </Quote>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

These two examples are minimal SOAP documents. The root element of every SOAP document is Envelope which must be in the http://schemas.xmlsoap.org/soap/envelope/ namespace, at least in SOAP 1.1. (The URL will change in SOAP 1.2.) Normally a prefix is used, and as always you can pick any prefix as long as the URI stays the same. In this chapter, I always assume that the prefix SOAP-ENV is mapped to that namespace URI. (This is the prefix the SOAP 1.1 specification uses.)

Each SOAP-ENV:Envelope element contains exactly one SOAP-ENV:Body element. The content of this element is one or more XML elements specific to the service. These examples use Quote, getQuote, and Price elements in the http://namespaces.cafeconleche.org/xmljava/ch2/ namespace. Other services will use other elements from other namespaces. It’s also permissible to use elements from no namespace at all, though using namespaces is highly recommended.

Currently, most SOAP messages are passed over HTTP using POST, just like XML-RPC messages. Other transport protocols such as SMTP, BEEP, and Jabber can be supported as well. However, there are a couple of crucial differences in the HTTP headers used for SOAP:

The SOAPAction field alerts web servers and firewalls that they’re dealing with a SOAP message. This allows firewalls to more easily filter SOAP requests without looking at the request body. The value of the SOAPAction field is a double quoted URI that somehow indicates the intent of the message. For instance, if Example 2.15 were POSTed to a servlet running on www.ibiblio.org under the control of the user elharo, then you might use the SOAPAction http://www.ibiblio.org/#elharo to indicate to the server and firewall who was responsible for processing this request. This is shown in Example 2.17.

POST /xml/cgi-bin/SOAPHandler HTTP/1.1
Content-Type: text/xml; charset="utf-8"
Content-Length: 267
SOAPAction: "http://www.ibiblio.org/#elharo"

<?xml version="1.0"?>
<SOAP-ENV:Envelope
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" >
  <SOAP-ENV:Body>
    <getQuote xmlns="http://namespaces.cafeconleche.org/xmljava/ch2/">
      <symbol>RHAT</symbol>
    </getQuote>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Conceptually, SOAPAction URIs are very similar to namespace URIs because they aren’t meant to be resolved. They’re just a convenient way of assigning unique identifiers to certain classes of SOAP messages. There’s no particular standard for how they’re chosen. You might use the full absolute URL that receives the SOAP request or you might use some previously agreed upon URI. You can even use nothing at all. But the SOAPAction header must be present in order for the request to be identified as a SOAP request.

The server will normally send the response back to the client over the same socket the client used to send the request and then close the connection. Like any other HTTP response, a SOAP response begins with an HTTP return code, message, and header. Assuming the request was successful, then the response code is 200 OK. Unlike the request, the response does not use any special header fields beyond those used by regular web browsers and servers. Example 2.18 demonstrates:

HTTP/1.0 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: 260

<?xml version="1.0"?>
<SOAP-ENV:Envelope
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Body>
    <Quote xmlns="http://namespaces.cafeconleche.org/xmljava/ch2/">
      <Price>4.12</Price>
    </Quote>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

It’s a fact of life that requests fail. They may fail for reasons beyond control of the SOAP provider. For instance, you may launch your SOAP request into the ether just before the phone company severs the wire connecting you to the Internet while hooking up your neighbor’s new DSL line. That sort of failure would make it itself manifest at a lower layer, below XML and SOAP, probably as a SocketException if you’re working in Java.

It’s also possible that your request will successfully arrive at the server, only to find that the server doesn’t recognize the URL you’re posting to. In fact, the server might not even be configured to support SOAP requests. This sort of error would not throw an exception, but would return a 404 Not Found page rather than the expected SOAP response. Your code should be prepared to handle such events.

Finally, it’s also possible that the SOAP responder itself is able to be reached and correctly invoked, but that it cannot process the request. This may be because the request contained bad data (e.g. a symbol for a stock that doesn’t exist) or simply because the server code is buggy and encountered a problem. In these cases the SOAP server itself is responsible for producing the correct error message. This error message is a SOAP response with a SOAP-ENV:Envelope and a SOAP-ENV:Body, just like a normal response. However, the SOAP-ENV:Body must contain exactly one SOAP_ENV:Fault element and may not contain anything else.

The SOAP_ENV:Fault element contains up to four child elements:

SOAP defines four specific fault codes in the http://schemas.xmlsoap.org/soap/envelope/ namespace to indicate common conditions in a generic way. These are:

Example 2.19 is a fault that might be returned in response to a request for the non-existent stock ABCD. The faultcode element is set to SOAP-ENV:Client to indicate that the client's request was incorrect. The faultstring element just contains a brief string of unmarked up text that can be used to more fully describe the problem to a human reader. The faultdetail content includes elements in the same namespace as the successful response, http://namespaces.cafeconleche.org/xmljava/ch2/. Since this request was processed by a single node, no faultactor element is necessary.

HTTP/1.0 500 Internal Server Error
Content-Type: text/xml; charset="utf-8"
Content-Length: 498

<?xml version="1.0"?>
<SOAP-ENV:Envelope
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
 xmlns:stock="http://namespaces.cafeconleche.org/xmljava/ch2/">
  <SOAP-ENV:Body>
    <SOAP-ENV:Fault>
      <faultcode>SOAP-ENV:Client</faultcode>
      <faultstring>
        There is no stock with the symbol ABCD.
      </faultstring>
      <faultdetail>
        <stock:InvalidSymbol>ABCD</stock:InvalidSymbol>
      </faultdetail>
    </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The information encoded in the SOAP documents you’ve seen so far has all been nothing more than Unicode text strings. When you want to encode other types such as integers, arrays, and objects, you need to specify how the characters that make up the XML document should be deserialized into the local platform’s understanding of those types. For example, if a Java program encounters the element <Price>4.12</Price> should it convert this into a double? a float? a java.lang.String? a java.math.BigDecimal? a custom Price class? something else?

Any element in a SOAP document can have a SOAP-ENV:encodingStyle attribute whose value is a URI pointing to some kind of schema that says what types are assigned to which elements. The most common language to use for this schema is the W3C XML Schema Language. However, other schema languages such as RELAX NG are allowed too.

Example 2.20 uses the SOAP-ENV:encodingStyle attribute on the getQuote element to point to a schema at the relative URL trading.xsd. This schema defines the symbol element as having the custom type StockSymbol, and is shown in Example 2.21. This schema is just used for assigning types. It is not used for validation, though with a little extra work it could be.

<?xml version="1.0"?>
<SOAP-ENV:Envelope
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Body>
    <getQuote xmlns="http://namespaces.cafeconleche.org/xmljava/ch2/"
              SOAP-ENV:encodingStyle="trading.xsd">
      <symbol>RHAT</symbol>
    </getQuote>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://namespaces.cafeconleche.org/xmljava/ch2/"
xmlns="http://namespaces.cafeconleche.org/xmljava/ch2/"
elementFormDefault="qualified">

  <xsd:element name="getQuote">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="symbol" type="StockSymbol" 
                     maxOccurs="unbounded"/>
      </xsd:sequence>
    </xsd:complexType>  
  </xsd:element>

  <xsd:simpleType name="StockSymbol">
    <xsd:restriction base="xsd:string">
      <!-- two to six upper case letters -->
      <xsd:pattern value="[A-Z][A-Z][A-Z]?[A-Z]?[A-Z]?[A-Z]?"/>
    </xsd:restriction>
  </xsd:simpleType>

</xsd:schema>

The SOAP-ENV:encodingStyle attribute can be placed on any element in the document. It applies to that element and its descendants, and overrides the schemas declared on any ancestor. It is commonly placed on the root SOAP-ENV:Envelope element.

SOAP singles out one encoding style for special treatment. If the SOAP-ENV:encodingStyle attribute has the value http://schemas.xmlsoap.org/soap/encoding/, then a predefined set of types are available that includes one element for each simple type defined in the W3C XML Schema Language and listed in Table 2.1. For instance, assuming the SOAP-ENC prefix is bound to the http://schemas.xmlsoap.org/soap/encoding/ URI (Note that this is not the same as the namespace URI or prefix for the SOAP envelope) then an int can be placed in a SOAP-ENC:int element like this

<SOAP-ENC:int>12</SOAP-ENC:int>

The complete list of types and their normal Java semantics is given in Table 2.2, though this really just mirrors Table 2.1. In many cases, Java does not have a type that exactly matches one of the derived types. Thus it uses the broader base class. For example, Java does not have an unsigned integer type but all values of type xsd:unsignedInt can fit into a Java long. Java does not have a PositiveInteger class, but all xsd:positiveIntegers can be represented by a java.math.BigInteger. In some cases the mapping is obvious. In others, different programs may use different Java types and objects to deserialize the same values. For instance, an xsd:int is exactly a Java int, and an xsd:double is as close to a Java double as it’s possible for a base-10 string to be. However, an xsd:anyURI, could reasonably be converted to a java.net.URL, a java.lang.String, or some custom URI class.

These mappings are not written in stone. Some of the XMLish types like SOAP-ENC:ENTITY and SOAP-ENC:IDREFS are particularly uncertain, and may be implemented in different ways in different environments. However, this should give you a pretty good idea of the sorts of mappings that are possible between SOAP types and Java types.

Besides this list of simple types, the http://schemas.xmlsoap.org/soap/encoding/ encoding also defines concepts of structs, references, byte arrays, and arrays.

<Quote xmlns="http://namespaces.cafeconleche.org/xmljava/ch2/">
  <Symbol>RHAT</Symbol>
  <Price>4.12</Price>
</Quote>

public class Quote {

  public String getSymbol();
  public double getPrice();

}

<Bid xmlns="http://namespaces.cafeconleche.org/xmljava/ch2/">
  <Symbol>RHAT</Symbol>
  <Price>4.12</Price>
  <Account>777-7777</Account>
</Bid>
<Bid xmlns="http://namespaces.cafeconleche.org/xmljava/ch2/">
  <Symbol>YHOO</Symbol>
  <Price>4.12</Price>
  <Account>777-7777</Account>
</Bid>

<Bid xmlns="http://namespaces.cafeconleche.org/xmljava/ch2/">
  <Symbol>RHAT</Symbol>
  <Price>4.12</Price>
  <Account id="a1">777-7777</Account>
</Bid>
<Bid xmlns="http://namespaces.cafeconleche.org/xmljava/ch2/">
  <Symbol>YHOO</Symbol>
  <Price>4.12</Price>
  <Account href="#a1"/>
</Bid>

<Bid xsi:type="SOAP-ENC:Array">
   <Price>4.52</Price>
   <Price>0.35</Price>
   <Price>34.68</Price>   
 </Bid>

<SOAP-ENC:Array>
  <SOAP-ENC:double>4.52</SOAP-ENC:double>
  <SOAP-ENC:double>0.35</SOAP-ENC:double>
  <SOAP-ENC:double>34.68</SOAP-ENC:double>
</SOAP-ENC:Array>

<Bid xsi:type="SOAP-ENC:Array">
  <Symbol  xsi:type="xsd:token">RHAT</Symbol>
  <Price   xsi:type="xsd:double">4.12</Price>
  <Account xsi:type="xsd:string">777-7777</Account>
</Bid>

<Bid xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:double[3]">
   <Price>4.52</Price>
   <Price>0.35</Price>
   <Price>34.68</Price>   
 </Bid>

<SOAP-ENC:Array SOAP-ENC:arrayType="xsd:double[3,2]">
   <SOAP-ENC:double>1.1</SOAP-ENC:double>
   <SOAP-ENC:double>1.2</SOAP-ENC:double>
   <SOAP-ENC:double>2.1</SOAP-ENC:double>   
   <SOAP-ENC:double>2.2</SOAP-ENC:double>
   <SOAP-ENC:double>3.1</SOAP-ENC:double>
   <SOAP-ENC:double>3.2</SOAP-ENC:double>   
 </SOAP-ENC:Array>

double[][] array = {
  {1.1, 1.2},
  {2.1, 2.2},
  {3.1, 3.2}
}

<SOAP-ENC:Array SOAP-ENC:offset="[3]">
  <SOAP-ENC:string>Component 3</SOAP-ENC:string>   
  <SOAP-ENC:string>Component 4</SOAP-ENC:string>   
  <SOAP-ENC:string>Component 5</SOAP-ENC:string>   
  <SOAP-ENC:string>Component 6</SOAP-ENC:string>   
  <SOAP-ENC:string>Component 7</SOAP-ENC:string>   
  <SOAP-ENC:string>Component 8</SOAP-ENC:string>   
  <SOAP-ENC:string>...</SOAP-ENC:string>   
</SOAP-ENC:Array>

<SOAP-ENC:Array SOAP-ENC:arrayType="xsd:string[10]">
  <SOAP-ENC:string SOAP-ENC:position="[2]">
    2nd component
  </SOAP-ENC:string>
  <SOAP-ENC:string SOAP-ENC:position="[3]">
    3rd component
  </SOAP-ENC:string>
  <SOAP-ENC:string SOAP-ENC:position="[5]">
    5th component
  </SOAP-ENC:string>   
</SOAP-ENC:Array>

   String[] array = new String[10];
   array[2] = "\n     2nd component\n    ";
   array[3] = "\n     3rd component\n    ";
   array[5] = "\n     5th component\n    ";

<SignatureValue>
AgGOvkMdqdKT7QyMuXPsuomkOqqEhGukKkj4Em7OKKQxYzheuseS8Q==
</SignatureValue>

As well as the body of the request, each SOAP document can contain a header. This is not an HTTP header. Rather it is an additional child of the SOAP-ENV:Envelope element, specifically a SOAP-ENV:Header element. If a SOAP request is an envelope, then the body is the letter inside the envelope, and the header is the writing on the outside of the envelope that tells the Post Office where to deliver it to, where to send it back if they can’t deliver it, and how much you paid to get the letter delivered. In other words, a SOAP header provides meta-information about the request.

The sort of meta-information provided varies from request to request and SOAP application to SOAP application. Some things that can be exchanged in headers include:

For instance, Example 2.22 shows a bid document in which the header carries credit card information to pay for the request. In this case, the syntax used for the Payment element is specific to the XML application used in the body and even comes from the same namespace.

<?xml version="1.0"?>
<SOAP-ENV:Envelope
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" >
  <SOAP-ENV:Header>
    <Payment xmlns="http://namespaces.cafeconleche.org/xmljava/ch2/">
      <Name>Elliotte Harold</Name>
      <Issuer>VISA</Issuer>
      <Number>5125456787651230</Number>
      <Expires>2005-12</Expires>
    </Payment>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <buy id="buy1"
         xmlns="http://namespaces.cafeconleche.org/xmljava/ch2/">
      <symbol>MRBA</symbol> 
      <shares>100</shares> 
      <account>777-7777</account> 
    </buy>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Like the SOAP body, the SOAP header can use any XML application it cares to use to encode the data. It is not limited to a fixed vocabulary. Indeed it can use more than one such vocabulary. The SOAP-ENV:Header element can contain multiple child elements from a hodge-podge of different namespaces. Each one of these elements is called a header entry, and may be treated independently of the other header entries. For example, Example 2.23 adds an additional header containing a digital signature for the request body. The syntax used for the Signature element is defined by XML-Signature Syntax and Processing.

<?xml version="1.0"?>
<SOAP-ENV:Envelope
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" >
  <SOAP-ENV:Header>
    <Payment xmlns="http://namespaces.cafeconleche.org/xmljava/ch2/">
      <Name>Elliotte Harold</Name>
      <Issuer>VISA</Issuer>
      <Number>5125456787651230</Number>
      <Expires>2005-12</Expires>
    </Payment>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
  <SignedInfo>
    <CanonicalizationMethod 
    Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
    <SignatureMethod 
      Algorithm="http://www.w3.org/2000/09/xmldsig#dsa-sha1" />
    <Reference URI="file://J/xss4j/requestbody.xml">
    <DigestMethod 
      Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
      <DigestValue>3UxhLrdPpK3faRms5FOS6kAoeZI=</DigestValue>
    </Reference>
  </SignedInfo>
  <SignatureValue>
    ZeW/PYGT6A9iOqOrbMmeKOq1aQk+ars/QOC95Bj0xYrNAnLo/WK7+g==
  </SignatureValue>
</Signature>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <buy id="buy1"
         xmlns="http://namespaces.cafeconleche.org/xmljava/ch2/">
      <symbol>MRBA</symbol> 
      <shares>100</shares> 
      <account>777-7777</account> 
    </buy>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

<?xml version="1.0"?>
<SOAP-ENV:Envelope
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" >
  <SOAP-ENV:Header>
    <Payment xmlns="http://namespaces.cafeconleche.org/xmljava/ch2/"
             SOAP-ENV:mustUnderstand="1">
      <Name>Elliotte Harold</Name>
      <Issuer>VISA</Issuer>
      <Number>5125456787651230</Number>
      <Expires>2005-12</Expires>
    </Payment>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <buy xmlns="http://namespaces.cafeconleche.org/xmljava/ch2/">
      <symbol>MRBA</symbol> 
      <shares>100</shares> 
      <account>777-7777</account> 
    </buy>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Regrettably, in my opinion, SOAP does not allow developers to take full advantage of XML’s expressiveness and extensibility. First of all, According to the SOAP 1.1 specification, “A SOAP message MUST NOT contain a Document Type Declaration.” This allows non-validating parsers and parsers that cannot resolve external entities to be used to process SOAP messages without concern that they may be misinterpreting them because they don’t apply default namespaces or resolve external entities. However, it also means the document can’t be validated against a DTD.

Also according to the SOAP 1.1 specification, “A SOAP message MUST NOT contain Processing Instructions.” Honestly this makes no sense to me whatsoever. I see little reason for forbidding these. This does mean that all information in a SOAP request must be passed through the defined SOAP structure, but it also means that it’s difficult to include other useful features beyond the SOAP structure. The most obvious is that you can’t easily apply a style sheet to a SOAP document, though that’s not a huge loss since SOAP documents aren’t meant for humans to read in the first place. However, it also means it’s difficult to serve SOAP documents out of the Cocoon application server. There are probably many other environment specific instances where this becomes inconvenient.

SOAP is actively hostile to DTDs. The SOAP specification specifically forbids a SOAP request from containing a document type declaration. Thus you really have to use a schema to validate your documents, if you validate them at all.

Unlike XML-RPC, SOAP does have an official schema. In fact it has two, which you can download from the SOAP namespace URLs. The envelope schema at http://schemas.xmlsoap.org/soap/envelope/ describes the SOAP complex types: SOAP-ENV:Envelope, SOAP-ENV:header, SOAP-ENV:Body, etc. The encoding schema at http://schemas.xmlsoap.org/soap/encoding/ defines the SOAP data types shown in Table 2.2: SOAP-ENC:int, SOAP-ENC:NMTOKENS, SOAP-ENC:gYear, SOAP-ENC:Array, etc. These schemas are a little too long to reproduce here, but you can find them in Appendix B.

XML-RPC is a monolithic XML application not designed to be integrated with other XML applications. SOAP, by contrast, is incomplete without some other XML application to form the body of the SOAP request. Thus the SOAP schema cannot be monolithic. It must rely on some other XML application in its own namespace (or perhaps no namespace at all, though this is not recommended) so the SOAP schema cannot on its own validate any SOAP documents. You also need to provide a separate schema for the bodies of your documents, and then you need to merge the two together using xsd:import elements.

For example, Example 2.25 is a master schema for quote request documents such as Example 2.15. This schema declares no elements of its own but does import both SOAP schemas, as well as the schema for getQuote elements seen earlier in Example 2.21. This schema can be used to validate a complete SOAP request that has a getQuote body element. If you wanted to validate the other SOAP documents in this chapter that use other elements in the header and body, you’d just need to write declarations for those elements too. They could be placed in the master schema, trading.xsd, or their own schema documents, whichever seems most convenient.

<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  targetNamespace="http://schemas.xmlsoap.org/soap/envelope/">

  <!-- Standard SOAP schemas -->
  <xsd:include 
    schemaLocation="http://schemas.xmlsoap.org/soap/envelope/"
  />
  <xsd:import 
    schemaLocation="http://schemas.xmlsoap.org/soap/encoding/"
    namespace="http://schemas.xmlsoap.org/soap/encoding/" 
  />

  <!-- Local schema -->
  <xsd:import schemaLocation="trading.xsd"
    namespace="http://namespaces.cafeconleche.org/xmljava/ch2/"
  />  
  
</xsd:schema>