SOAPFaultElement

   

---

SOAPFault

javax.xml.soap

---

SAAJ 1.1; JWSDP 1.0, J2EE 1.4

 public interface SOAPFault extends SOAPBodyElement {  // Public Instance Methods  public abstract Detail addDetail(  ) throws SOAPException;      public abstract Detail getDetail(  );      public abstract String getFaultActor(  );      public abstract String getFaultCode(  );      public abstract String getFaultString(  );      public abstract void setFaultActor(String   faultActor   ) throws SOAPException;      public abstract void setFaultCode(String   faultCode   ) throws SOAPException;      public abstract void setFaultString(String   faultString   ) throws SOAPException;  } 

SOAPFault is a subinterface of SOAPBodyElement that is used to report an error encountered while processing the body or headers of an earlier message. A SOAPFault element can be created and added to a message by calling the addFault( ) method of the SOAPBody element of the message. Only one SOAPFault element may be present in a SOAP message body; a SOAPException is thrown if an attempt is made to add a second SOAPFault .

When created, a SOAPFault element is empty. Application code should use SOAPFault methods to add the following nested elements, as appropriate:

Fault code

This mandatory element contains a value intended to be used by software to identify the cause of the error being reported . The SOAP specification defines a small number of standard fault codes that should be used where applicable . For further information on SOAP fault codes, refer to Chapter 6. The fault code is a string value that can be set using the setFaultCode( ) method and read by calling getFaultCode( ) .

Fault string

This mandatory element provides a human-readable description of the fault. It can be set using the setFaultString( ) method and read using getFaultString( ) .

Fault actor

This element contains the URI of the system that detected and is reporting the fault described by the containing SOAPFault element. It must be present if the error was detected by an intermediate system, and is optional if the fault is being reported by the intended message recipient. Use the setFaultActor( ) and getFaultActor( ) methods to set and read this value.

Details

A SOAPFault element may also contain additional information that describes the fault, the nature of which is application-specific but might, for example, include some or all of the failing message. This optional information is included within a Detail element, which can be created using the addDetail( ) method. Refer to the description of DetailEntry earlier in this chapter for an example that shows how to include detailed fault information in a SOAP message. Fault reports that relate to the content of a message header may not have an associated Detail element, whereas those that report errors in processing the body content may have no more than one nested Detail element. A SOAPException is thrown if an attempt is made to add a second Detail element to a SOAPFault .

Additionally, application-dependent elements may also be added to a SOAPFault by using the addChildElement( ) method inherited from SOAPElement . These elements, which must be namespace-qualified, will all be of type SOAPFaultElement .

Returned By

SOAPBody.{addFault( ) , getFault( )}

---