Overview of SOAP Faults

<< The relay Attribute | Creating and Populating a SOAPFault Object >>

146

SOAP

WITH

TTACHMENTS

API

FOR

AVA

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 mes-
sage, 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.

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 pro-

vides a simple means for sending mandatory information intended for the ulti-
mate 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 (page 139), an actor that can-
not process a header that has a

mustUnderstand

attribute with a value of

true

must return a SOAP fault to the sender.

SOAPFault

object contains the following elements:

· A 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 spec-
ifications 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 specifica-