WebReference.com - Part 1 of Chapter 3: Professional XML Web Services, from Wrox Press Ltd (6/7) | WebReference

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

To page 1To page 2To page 3To page 4To page 5current pageTo page 7
[previous] [next]

Professional XML Web Services

Fault

Everything we have discussed about the SOAP message format so far covers how to build good clean messages that are successfully sent to and processed by the receiver every time. Of course, that is not a realistic view of how a real application will behave. Just as SOAP messages have a specified location and format for versioning, encoding style, payload, and extensions, they also have a location and format for errors. The element in a SOAP message that represents an error is the Fault element. You can think of the Fault element as exceptions for Web Services, a standard way to throw back a report on unexpected behavior to the originator of the message.

Faults are typically associated with a response message. Although the specification does not rule out Fault elements in requests, do not expect existing server implementations to behave well in the face of such requests!

If the Fault element appears, it must be in the payload of the SOAP message, which means that it must appear as a child element of the Body.

The example message below is a response that contains a Fault element.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
               soap:encodingStyle="http://schemas.xmlsoap.org/soap/
                                   encoding/">
   <soap:Body>
      <soap:Fault>
         <faultcode>soap:MustUnderstand</faultcode>
         <faultstring>Mandatory Header error.</faultstring>
         <faultactor>http://www.wrox.com/heroes/endpoint.asp</faultactor>
         <detail>
            <w:source xmlns:w="http://www.wrox.com/">
               <module>endpoint.asp</module>
               <line>203</line>
            </w:source>
         </detail>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

faultcode element

The faultcode element contains a value that identifies the error condition to the application. This means this value is for machine use and is not intended for display to potential users. The faultcode element value must be a qualified name, as if it were an element in the message itself. In the above example, the faultcode element's value is soap:MustUnderstand, indicating that the MustUnderstand fault is a SOAP standard fault. This allows us to define our own values for the faultcode element and identify them by their namespace.

The following standard faultcode element values are defined in the SOAP 1.1 specification:

The standard faultcode element values listed here represent classes of faults rather than a single error. They are extensible in that more specific codes that fit into these classes can be defined. This is done by appending a period to the code and adding an additional name to the code. For example, if the machine the endpoint is running on were to run out of memory, the endpoint could potentially return a Server.OutOfMemory fault code.


To page 1To page 2To page 3To page 4To page 5current pageTo page 7
[previous] [next]

Created: November 12, 2001
Revised: November 12, 2001


URL: http://webreference.com/authoring/languages/xml/webservices/chap3/1/6.html