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

• VersionMismatch – this value indicates that the namespace of the SOAP Envelope element was not http://schemas.xmlsoap.org/soap/envelope/. Currently that value is the only acceptable version of a SOAP message, and it indicates that the message conforms to the 1.1 Note.
• MustUnderstand – this value is returned in a faultcode element when the endpoint encounters a mandatory Header element entry (one with a mustUnderstand attribute set to 1) that it does not recognize.
• Client – this value should be used in the faultcode element when a problem is found in the message that was received. This could be anything from a missing element to an incorrect namespace in the body, but this faultcode element value states that the message that was received was to blame for the error.
• Server – in contrast to the Client fault code, Server indicates that a problem occurred during processing that was not directly related to the content of the message. An example of this type of fault would be that the database used by the endpoint to return information is down.

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.

[previous] [next]

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

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