WebReference.com - Part 1 of Chapter 3: Professional XML Web Services, from Wrox Press Ltd (6/7)
Professional XML Web Services
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
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
Faultelements in requests, do not expect existing server implementations to behave well in the face of such requests!
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
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 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
VersionMismatchÂ this value indicates that the namespace of the SOAP
Envelopeelement 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
faultcodeelement when the endpoint encounters a mandatory
Headerelement entry (one with a
mustUnderstandattribute set to
1) that it does not recognize.
ClientÂ this value should be used in the
faultcodeelement 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
faultcodeelement value states that the message that was received was to blame for the error.
ServerÂ in contrast to the
Serverindicates 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.
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
Server.OutOfMemory fault code.
Created: November 12, 2001
Revised: November 12, 2001