Featured White Papers

• Measuring Risk to Improve Java Software Quality
• Do You Really Get Classloaders?
• Pragmatic Continuous Delivery with Jenkins, Nexus, and LiveRebel
• Your Next Java Web App: Less XML, No Long Restarts, Fewer Hassles
• Coding with JRebel, Java Forever Changed
• 2012 Developer Productivity Report: Java Tools, Tech, Devs, and Data

Sponsored Links

• Graph databases are 1000x faster than relational.

  Learn More!

• Career opportunities at Harman- Careers That'll Rock Your Socks Off.

  Learn More!

• Developer-friendly Java PDF libraries by Qoppa Software

  Live Demos

• Stop blaming your app! Diagnose Java performance issues.

  Free tool >

• UrbanCode: Go From Continuous Integration to
  Continuous Delivery

  Learn More!

Sponsored Links

Optimize with a SATA RAID Storage Solution
Range of capacities as low as $1250 per TB. Ideal if you currently rely on servers/disks/JBODs

Clean up your wire protocol with SOAP, Part 1

An introduction to SOAP basics

By Tarak Modi, JavaWorld.com, 03/30/01

Page 4 of 6

Let's return to our "Hello" example and add a silly constraint to it: "It is not valid to say hello to someone on Tuesday." So on Tuesdays, even though the request sent to the server is valid, the server will return an error response to the client. This response would be similar to the following:

Listing 7

<SOAP-ENV:Envelope xmlns:SOAP-ENV="
http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Body>
       <SOAP-ENV:Fault>
           <faultcode>SOAP-ENV:Server</faultcode>
           <faultstring>Server Error</faultstring>
           <detail>
               <e:myfaultdetails xmlns:e="Hello">
                 <message>
                   Sorry, my silly constraint says that I cannot say hello on Tuesday.
                 </message>
                 <errorcode>
                   1001
                 </errorcode>
               </e:myfaultdetails>
           </detail>
       </SOAP-ENV:Fault>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Let's focus on the Fault element defined in the http://schemas.xmlsoap.org/soap/envelope/namespace. All SOAP servers must always return any error condition in that element, which is always a direct child of the Body element. Without exception, the Fault element must have faultcode and faultstring elements. The faultcode is a code that can identify problems; client-side software uses faultcode for algorithmic processing as the SOAP specification calls it. The SOAP specification defines a small set of fault codes that you can use. The faultstring on the other hand is meant for human consumption.

The code snippet in Listing 7 also shows a detail element. Since the error occurred while processing the SOAP message's body section, the detail element must be present. As you'll see later, if the error occurs while processing the header, detail must not be present. In Listing 7, the application used that element to provide a more detailed explanation of the nature of the error, namely that it was not allowed to say hello on Tuesdays. An application-specific error code is also present as well: a semioptional element called faultfactor that I have not shown in the error message. I call it semioptional because it must be included if the error message was sent by a server that was not the request's end-processing point, i.e., an intermediate server. SOAP does not specify any situation in which the faultcode element must not be included.

In Listing 7, the fault resulted from the method invocation itself, and the application processing the method caused it. Now let's take a look at another type of fault; one that generates as a result of the server not being able to process the header information. As an example, assume that all hello messages must generate in the context of a transaction. That request would look similar to this:

Listing 8

<SOAP-ENV:Envelope 
                       xmlns:SOAP-ENV="
http://schemas.xmlsoap.org/soap/envelope/" 
                       xmlns:xsi="
http://www.w3.org/1999/XMLSchema-instance" 
                       xmlns:xsd="http://www.w3.org/1999/XMLSchema">
     <SOAP-ENV:Header>
         <t:Transaction xmlns:t="some-URI" 
SOAP-ENV:mustUnderstand="1">
              5
         </t:Transaction>
     </SOAP-ENV:Header>
    <SOAP-ENV:Body>
         <ns1:sayHelloTo 
                      xmlns:ns1="Hello" 
                     SOAP-ENV:encodingStyle="
http://schemas.xmlsoap.org/soap/encoding/">
             <name xsi:type="xsd:string">Tarak</name>
         </ns1:sayHelloTo>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The above message's header section has a transaction element; it specifies the transaction number that the method invocation must be part of. I say must because the transaction element uses the mustUnderstand attribute. As I mentioned before, the SOAP server must either honor that or fail to process the request. To make matters interesting, let's assume that the SOAP server cannot honor that and therefore fails the request. The response would be similar to this: