SOAP

Because distributed applications are becoming so popular, SOAP, which lets such applications communicate, is becoming popular, too. Plenty of SOAP resources can be found on the Internet; here's a starter list, including W3C's documentation on it:

• http://www.w3.org/TR/SOAP/ The W3C SOAP 1.1 documentation. This is a W3C Note.

• http://www.w3.org/TR/SOAP-attachments The W3C SOAP Messages with Attachments documentation. This is also a W3C Note.

• http://www.zvon.org/xxl/soapReference/Output/index.html A SOAP 1.1 reference.

• http://www.xml.com/pub/a/2001/04/04/soap.html A history of SOAP.

• http://www.develop.com/soap/soapfaq.htm The SOAP Frequently Asked Questions (FAQ).

• http://xml.apache.org/soap/faq/index.html The Apache project's SOAP FAQ.

• http://www.xml.com/pub/a/2000/02/09/feature/index.html An article on SOAP.

• http://www.soapware.org/bdg A "Busy Developer's Guide" to SOAP 1.1.

• http://www.w3schools.com/SOAP/default.asp A SOAP tutorial.

• http://www.javaworld.com/ javaworld /jw-03-2001/jw-0330-soap.html Part 1 of a SOAP tutorial.

• http://www.javaworld.com/javaworld/jw-04-2001/jw-0427-soap.html Part 2 of a SOAP tutorial.

• http://www.javaworld.com/javaworld/jw-06-2001/jw-0601-soap.html Part 3 of a SOAP tutorial.

• http://www.javaworld.com/javaworld/jw-07-2001/jw-0706-soap.html Part 4 of a SOAP tutorial.

• http://www.javaworld.com/javaworld/jw-03-2001/jw-0302-xmlmessaging.html "XML Messaging with SOAP, Part 1."

• http://www.javaworld.com/jw-06-2001/jw-0622-xmlmessaging2.html "XML Messaging with SOAP, Part 2."

Here are some SOAP resources for Microsoft's SOAP support:

• http://msdn.microsoft.com/library/default.asp?url=/nhp/Default.asp?contentid=28000523 Microsoft SOAP overview and toolkit. Also http://msdn.microsoft.com/soap/.

• http://msdn.microsoft.com/msdnmag/issues/0900/WebPlatform/WebPlatform.asp "The Programmable Web: Web Services Provide Building Blocks for the Microsoft .NET Framework."

• http://msdn.microsoft.com/library/default.asp?url=/nhp/Default.asp?contentid=28000523 Microsoft SOAP overview and toolkit. Also http://msdn.microsoft.com/soap/.

• http://msdn.microsoft.com/msdnmag/issues/0800/webservice/webservice.asp "Develop a Web Service: Up and Running with the SOAP Toolkit for Visual Studio."

• http://msdn.microsoft.com/xml/general/toolkit_intro.asp "Web Services and the SOAP Toolkit for Visual Studio 6.0."

• http://msdn.microsoft.com/xml/general/soapspec.asp SOAP Specification, Version 1.1.

• http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnsoap/html/soapsecurity.asp "Building Secure Web Services with Microsoft SOAP Toolkit 2.0."

Let's start digging into this topic now, beginning with the syntax that makes SOAP work.

SOAP Syntax

A SOAP message is simply an XML document that adheres to the SOAP syntax rules. There are three parts to a SOAP message:

• A SOAP envelope. The envelope indicates the content of the SOAP message.

• An optional SOAP header. The header holds information about the message.

• A SOAP body. The body contains the actual information in the message.

Here's a simple SOAP message, with an envelope and a body. This SOAP message is requesting the number of pens in stock at the warehouse ( soap-env is the name the W3C uses for the envelope namespace in its documentation):

 <soap-env:Envelope      xmlns:soap-env="http://www.w3.org/2001/12/soap-envelope"     soap:soap-enc="http://www.w3.org/2001/12/soap-encoding">     <soap-env:Header>         <m:Name xmlns:m="http://www.starpowder.com">             ReallyReallyBigCo         </m:Name>     </soap-env:Header>     <soap-env:Body>         <m:NumberInStock xmlns:m="http://www.starpowder.com">             <m:Item>Pens</m:Item>         </m:NumberInStock>     </soap-env:Body> </soap-env:Envelope> 

Note that although SOAP messages are XML documents, they must not contain references to DTDs, and they must not contain XML processing instructions.

Default namespaces already have been defined for the SOAP envelope and for SOAP encoding and data types. The default namespace for the envelope is http://schemas.xmlsoap.org/soap/envelope/ . The default namespace for the document encoding and data types is http://schemas.xmlsoap.org/soap/encoding/ .

So what elements are already defined for SOAP? That's coming up next .

SOAP Elements

SOAP messages are XML documents, and the root element is the <Envelope> element. There are three possible child elements: <Header> , <Body> , and <Fault> . All of these elements must use these names, although they can have child elements with different names . Here's what a SOAP envelope might look like:

 <soap-env:Envelope      xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"     soap-env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">     .     .     . </soap-env:Envelope> 

The <Header> element is optional and contains application-specific information about the SOAP message. In this example, the locale-specific language is being set to U.S. Englishhere, <m:locale> and <m:language> are user -defined elements:

 <soap-env:Envelope      xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"     soap-env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">  <soap-env:Header>   <m:locale xmlns:m="http://www.starpowder.com">   <m:language>EN-US</m:language>   </m:locale>  </soap-env:Header>     .     .     . </soap-env:Envelope> 

The <Body> element contains the SOAP message itself:

 <soap-env:Envelope      xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"     soap-env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">     <soap-env:Header>         <m:locale xmlns:m="http://www.starpowder.com">             <m:language>EN-US</m:language>         </m:locale>     </soap-env:Header>  <soap-env:Body>   <m:NumberInStock xmlns:m="http://www.starpowder.com">   <m:Item>Pens</m:Item>   </m:NumberInStock>   </soap-env:Body>  </soap-env:Envelope> 

The <Body> element may also contain a <Fault> element, which you use to hold errors that occurred while working with a message. This element can appear only in response messages, which you get in response to a SOAP message:

 <soap-env:Envelope      xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"     soap-env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">     <soap-env:Header>         <m:locale xmlns:m="http://www.starpowder.com">             <m:language>EN-US</m:language>         </m:locale>     </soap-env:Header>     <soap-env:Body>         <m:NumberInStock xmlns:m="http://www.starpowder.com">             <m:Item>Pens</m:Item>         </m:NumberInStock>  <soap-env:Fault>   <faultcode>soap:Server</faultcode>   <faultstring>Server Error</faultstring>   </soap-env:Fault>  </soap-env:Body> </soap-env:Envelope> 

There can only be one <Fault> element in a SOAP message, and it can have these subelements:

• <faultcode> Holds the error code

• <faultstring> Holds an error string

• <faultactor> Indicates where the error came from

• <detail> Holds error details

Here are the possible fault codes:

• VersionMismatch The namespace for the SOAP Envelope element was not right.

• MustUnderstand An element with the mustUnderstand attribute set to "1" could not be interpreted.

• Client A general problem occurred with the message as sent from the client.

• Server A general problem with the server occurred.

These SOAP elements can also support various attributes, which are coming up next.

SOAP Attributes

You can use these attributes in SOAP elements: actor , encodingStyle , and mustUnderstand . The actor attribute gives the URI for which the header elements are targeted . Here's an example showing how to use the actor attribute:

 <soap-env:Header>      <m:data xmlns:m="http://www.starpowder.com"  soap-env:actor="http://www.starpowder.com/accounting" />  <m:language>EN-US</m:language>     </m:data> </soap-env:Header> 

You can use the encodingStyle attribute to specify the data types used in the document. http://schemas.xmlsoap.org/soap/encoding/ is the URI of a schema that the W3C provides for SOAP data types:

 <soap-env:Envelope      xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"  soap-env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">  .     .     . </soap-env:Envelope> 

The encodingStyle attribute is optionalyou don't have to use a schema at all to specify the data types that you use in your SOAP message. SOAP schemas can use any of the data types defined for use in XML schemas (see http://www.w3.org/TR/xmlschema-2/) or combinations of them. For all the details on constructing SOAP schemas, see Section 5 of the W3C SOAP Note (http://www.w3.org/TR/SOAP/).

You use the mustUnderstand attribute in the <Header> element. It's used to specify whether the target of a message must interpret and process a header element. You set it to a Boolean value, "0" for false and "1" for true:

 <soap-env:Header>      <m:data xmlns:m="http://www.starpowder.com"  soap-env:mustUnderstand="1" />  <m:language>EN-US</m:language>     </m:data> </soap-env:Header> 

That gives us an overview of how SOAP works. What about putting SOAP to work? How about using SOAP in codecreating a message, sending it, receiving it, and interpreting it to see how this all works in practice? That's coming up next.