Server-side code must use a SOAP fault object to handle errors that occur on the server side when unmarshalling the request, processing the message, or marshalling the response. The SOAPFault interface extends the SOAPBodyElement interface.
SOAP messages have a specific element and format for error reporting on the server side: a SOAP message body can include a SOAP fault element to report errors that happen during the processing of a request. Created on the server side and sent from the server back to the client, the SOAP message containing the SOAPFault object reports any unexpected behavior to the originator of the message.
Within a SOAP message object, the SOAP fault object is a child of the SOAP body, as shown in the figure below. Detail and detail entry objects are only needed if one needs to report that the body of the received message was malformed or contained inappropriate data. In such a case, the detail entry object is used to describe the malformed data.
The SOAP Fault element defines the following four sub-elements:
faultcode
A code (qualified name) that identifies the error. The code is intended for use by software to provide an algorithmic mechanism for identifying the fault. Predefined fault codes are listed in Table 5–3. This element is required.
faultstring
A string that describes the fault identified by the fault code. This element is intended to provide an explanation of the error that is understandable to a human. This element is required.
faultactor
A URI specifying the source of the fault: the actor that caused the fault along the message path. This element is not required if the message is sent to its final destination without going through any intermediaries. If a fault occurs at an intermediary, then that fault must include a faultactor element.
detail
This element carries specific information related to the Body element. It must be present if the contents of the Body element could not be successfully processed. Thus, if this element is missing, the client should infer that the body element was processed. While this element is not required for any error except a malformed payload, you can use it in other cases to supply additional information to the client.
The SOAP specification lists four predefined faultcode values. The namespace identifier for these is http://schemas.xmlsoap.org/soap/envelope/.
Table 5–3 SOAP Faultcode Values
Faultcode Name |
Meaning |
|
---|---|---|
|
The processing party found an invalid namespace for the SOAP envelope element; that is, the namespace of the SOAP envelope element was not http://schemas.xmlsoap.org/soap/envelope/ . |
|
|
An immediate child element of the SOAP Header element was either not understood or not appropriately processed by the recipient. This element’s mustUnderstand attribute was set to 1 (true). |
|
|
The message was incorrectly formed or did not contain the appropriate information. For example, the message did not have the proper authentication or payment information. The client should interpret this code to mean that the message must be changed before it is sent again. If this is the code returned, the SOAPFault object should probably include a detailEntry object that provides additional information about the malformed message. |
|
|
The message could not be processed for reasons that are not connected with its content. For example, one of the message handlers could not communicate with another message handler that was upstream and did not respond. Or, the database that the server needed to access is down. The client should interpret this error to mean that the transmission could succeed at a later point in time. |
These standard fault codes represent classes of faults. You can extend these by appending a period to the code and adding an additional name. For example, you could define a Server.OutOfMemory code, a Server.Down code, and so forth.
Using SAAJ you can specify the value for faultcode, faultstring, and faultactor using methods of the SOAPFault object. The following code creates a SOAP fault object and sets the faultcode, faultstring, and faultactor attributes:
SOAPFault fault; reply = factory.createMessage(); envp = reply.getSOAPPart().getEnvelope(true); someBody = envp.getBody(); fault = someBody.addFault(): fault.setFaultCode("Server"); fault.setFaultString("Some Server Error"); fault.setFaultActor(http://xxx.me.com/list/endpoint.esp/) reply.saveChanges(); |
The server can return this object in its reply to an incoming SOAP message in case of a server error.
The next code sample shows how to define a detail and detail entry object. Note that you must create a name for the detail entry object.
SOAPFault fault = someBody.addFault(); fault.setFaultCode("Server"); fault.setFaultActor("http://foo.com/uri"); fault.setFaultString ("Unkown error"); Detail myDetail = fault.addDetail(); detail.addDetailEntry(envelope.createName("125detail", "m", "Someuri")).addTextNode("the message cannot contain the string //"); reply.saveChanges(); |