| home / authoring / languages / xml / webservices / chap3 / 1 |   
[previous] [next] |
|
|
|
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
Faultelements 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>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.
| home / authoring / languages / xml / webservices / chap3 / 1 |
[previous] [next] |
Legal Notices, Licensing, Permissions, Privacy Policy.
Advertise | Newsletters | Shopping | E-mail Offers | Freelance Jobs 
Created: November 12, 2001
Revised: November 12, 2001
URL: http://webreference.com/authoring/languages/xml/webservices/chap3/1/6.html
