Overviewof SOAP Faults

<< Using SOAP Faults | Creating and Populating a SOAPFault Object >>

Overviewof SOAP Faults

Overview of SOAP Faults

If you send a message that was not successful for some reason, you may get back a response
containing a SOAP fault element, which gives you status information, error information, or
both. There can be only one SOAP fault element in a message, and it must be an entry in the
SOAP body. Furthermore, if there is a SOAP fault element in the SOAP body, there can be no
other elements in the SOAP body. This means that when you add a SOAP fault element, you
have effectively completed the construction of the SOAP body.

A SOAPFault object, the representation of a SOAP fault element in the SAAJ API, is similar to
an Exception object in that it conveys information about a problem. However, a SOAPFault
object is quite different in that it is an element in a message's SOAPBody object rather than part of
the try/catch mechanism used for Exception objects. Also, as part of the SOAPBody object,
which provides a simple means for sending mandatory information intended for the ultimate
recipient, a SOAPFault object only reports status or error information. It does not halt the
execution of an application, as an Exception object can.

If you are a client using the SAAJ API and are sending point-to-point messages, the recipient of
your message may add a SOAPFault object to the response to alert you to a problem. For
example, if you sent an order with an incomplete address for where to send the order, the
service receiving the order might put a SOAPFault object in the return message telling you that
part of the address was missing.

Another example of who might send a SOAP fault is an intermediate recipient, or actor. As
stated in the section

"Adding Attributes" on page 603

, an actor that cannot process a header that

has a mustUnderstand attribute with a value of true must return a SOAP fault to the sender.

A SOAPFault object contains the following elements:

Fault code

: Always required. The fault code must be a fully qualified name: it must contain a

prefix followed by a local name. The SOAP specifications define a set of fault code local
name values, which a developer can extend to cover other problems. (These are defined in
section 4.4.1 of the SOAP 1.1 specification and in section 5.4.6 of the SOAP 1.2
specification.)

Table 191

lists and describes the default fault code local names defined in the

specifications.

A SOAP 1.2 fault code can optionally have a hierarchy of one or more subcodes.

Fault string

: Always required. A human-readable explanation of the fault.

Fault actor

: Required if the SOAPHeader object contains one or more actor attributes;

optional if no actors are specified, meaning that the only actor is the ultimate destination.
The fault actor, which is specified as a URI, identifies who caused the fault. For an
explanation of what an actor is, see

"The actor Attribute" on page 605

Detail

object

: Required if the fault is an error related to the SOAPBody object. If, for

example, the fault code is Client, indicating that the message could not be processed
because of a problem in the SOAPBody object, the SOAPFault object must contain a Detail
object that gives details about the problem. If a SOAPFault object does not contain a Detail
object, it can be assumed that the SOAPBody object was processed successfully.

SAAJ Tutorial

Chapter 19 · SOAP with Attachments API for Java

609