Java Web Services in a Nutshell

SOAP Fault Handling

A SOAP fault is a specific type of XML element placed in the body of a reply message to convey status information or, more usually, to report a fault while processing the original request. SAAJ represents a fault using the SOAPFault interface that, since it must be a top-level element in the SOAP body, is derived from SOAPBodyElement (see Figure 3-4). The SOAP specification requires that there be no more than one SOAP fault in the message body. Faults can be mixed with other top-level elements if necessary.

SOAP faults have three attributes that can be set to provide information about the condition being reported. Each of these attributes has corresponding methods in the SOAPFault interface to allow its value to be set or retrieved:

Attribute	SOAPFault methods	Description
Fault code	getFaultCode( ) setFaultCode( )	A code that indicates the reason for reporting the fault. Applications may define their own private fault codes or use the set of standard values defined by the SOAP 1.1 specification (described later). All fault codes must be namespace-qualified.
Fault string	getFaultString( ) setFaultString( )	A human-readable description of the reason for the fault. The value of this attribute typically is written to a log file or displayed in a user interface.
Fault actor	getFaultActor( ) setFaultActor( )	The URI of the participant in the SOAP message path (referred to in the SOAP specification as an actor) that caused the fault element ...