SCDJWS Study Guide: SOAP


Printer-friendly version Printer-friendly version | Send this 
article to a friend Mail this to a friend


Previous Next vertical dots separating previous/next from contents/index/pdf Contents

SOAP Fault

The Fault element indicates that an error occurred while processing a SOAP request. This element is used to carry error and/or status information within a SOAP message and only appears in response messages. The SOAP Fault element must appear as a body entry under the Body element and must not appear more than once within a Body element.

Sub elements of the SOAP Fault element

A faultcode element followed by a faultstring element followed by an optional faultactor element and an optional detail element. Each of these children is described in the following:

Name

Syntax

Description

faultcode

<faultcode xmlns=''>
QName</faultcode>

The faultcode element is of type QName and indicates what fault occurred. Several existing categories of fault code are defined, all in the http://schemas.xmlsoap.org/soap/envelope/ namespace.

VersionMismatch indicates that the recipient of a message did not recognize the namespace name of the Envelope element. MustUnderstand indicates that the recipient of an element child of the Header element had a soap:mustUnderstand attribute but that element was not understood by the recipient. Client indicates the SOAP message did not contain all the required information in order for the recipient to process it. This could mean that something was missing from inside the Body element. Equally, an expected extension inside the Header element could have been missing. In either case, the sender should not resend the message without correcting the problem. Server indicates that the recipient of the message was unable to process the message because of some server-side problem. The message contents were not at fault; rather, some resource was unavailable or some processing logic failed for a reason other than an error in the message. The sender may legitimately resend the message at a later time. All these fault codes may be followed by a period and a further string providing more detailed information about the error; for example,

Client.InvalidParameter.

faultstring

<faultstring xmlns=''>
string </faultstring>

The faultstring element is of type string and provides a human-readable description of whatever fault occurred.

faultactor

<faultactor xmlns=''>
uriReference </faultactor>

The faultactor element is of type uriReference and indicates the source of the fault. This may be the ultimate recipient of the request message, in which case the element is optional. Alternatively, the source of the fault may be an intermediary somewhere in the path the message took to get from the sender to the ultimate recipient. In this case the element must be present.

detail

<detail xmlns=''> any number of elements in any namespace </detail>

The detail element is used to carry application-specific error information and may be annotated with any number of attributes from any namespace, and may have any number of namespace-qualified element children. The detail element must be present if the fault is the result of the recipient being unable to process the Body element. The detail element is not used to provide error information in the case of the recipient being unable to process an element child of the Header element. In such cases, error information is placed inside the Header element.

The detail element is intended for carrying application specific error information related to the Body element. It MUST be present if the contents of the Body element could not be successfully processed. It MUST NOT be used to carry information about error information belonging to header entries. Detailed error information belonging to header entries MUST be carried within header entries. The absence of the detail element in the Fault element indicates that the fault is not related to processing of the Body element. This can be used to distinguish whether the Body element was processed or not in case of a fault situation.

All immediate child elements of the detail element are called detail entries and each detail entry is encoded as an independent element within the detail element. The encoding rules for detail entries are as follows:

·          A detail entry is identified by its fully qualified element name, which consists of the namespace URI and the local name. Immediate child elements of the detail element MAY be namespace-qualified.

·          The SOAP encodingStyle attribute MAY be used to indicate the encoding style used for the detail entries


SOAP Fault Codes


The default SOAP faultcode values are defined in an extensible manner that allows for new SOAP faultcode values to be defined while maintaining backwards compatibility with existing faultcode values. The mechanism used is very similar to the 1xx, 2xx, 3xx etc basic status classes classes defined in HTTP. However, instead of integers, they are defined as XML qualified names. The character "." (dot) is used as a separator of faultcode values indicating that what is to the left of the dot is a more generic fault code value than the value to the right.

The set of faultcode values defined in SOAP 1.1 is:


Name

Meaning

VersionMismatch

The processing party found an invalid namespace for the SOAP Envelope element.

MustUnderstand

An immediate child element of the SOAP Header element that was either not understood or not obeyed by the processing party contained a SOAP mustUnderstand attribute with a value of "1".

Client

The Client class of errors indicate that the message was incorrectly formed or did not contain the appropriate information in order to succeed. For example, the message could lack the proper authentication or payment information. It is generally an indication that the message should not be resent without change.

Server

The Server class of errors indicate that the message could not be processed for reasons not directly attributable to the contents of the message itself but rather to the processing of the message. For example, processing could include communicating with an upstream processor, which didn't respond. The message may succeed at a later point in time.


SOAP 1.1 allows custom fault codes to appear inside the faultcode element, through the use of the "dot" notation. Use of this mechanism to extend the meaning of the SOAP 1.1-defined fault codes can lead to namespace collision. Therefore, its use should be avoided, as doing so may cause interoperability issues when the same names are used in the right-hand side of the "." (dot) to convey different meaning.

Instead, the WS-I Basic Profile 1.0 encourages the use of the fault codes defined in SOAP 1.1, along with additional information in the detail element to convey the nature of the Fault.

Alternatively, it is acceptable to define custom fault codes in a namespace controlled by the specifying authority.

A number of specifications have already defined custom fault codes using the "." (dot) notation. Despite this, their use in future specifications is discouraged.


R1004
When a MESSAGE contains a faultcode element the content of that element SHOULD be one of the fault codes defined in SOAP 1.1 or a namespace qualified fault code.

R1031
When a MESSAGE contains a faultcode element the content of that element SHOULD NOT use of the SOAP 1.1 "dot" notation to refine the meaning of the Fault.

It is recommended that applications that require custom fault codes either use the SOAP 1.1 defined fault codes and supply additional information in the detail element, or that they define these codes in a namespace that is controlled by the specifying authority.

For example,

INCORRECT:
<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'
            xmlns:c='http://example.org/faultcodes' >
  <faultcode>soap:Server.ProcessingError</faultcode>
  <faultstring>An error occurred while processing the message
  </faultstring>
</soap:Fault>

CORRECT:
<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'
            xmlns:c='http://example.org/faultcodes' >
  <faultcode>c:ProcessingError</faultcode>
  <faultstring>An error occured while processing the message
  </faultstring>
</soap:Fault>

CORRECT:
<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' >
  <faultcode>soap:Server</faultcode>
  <faultstring>An error occured while processing the message
  </faultstring>
</soap:Fault>

A SOAP Fault is a SOAP message that has a single child element of the soap:Body element, that element being a soap:Fault element. The Profile restricts the content of the soap:Fault element to those elements explicitly described in SOAP 1.1. [WS-I Basic Profile 1.0]


R1000
When a MESSAGE contains a soap:Fault element, that element MUST NOT have element children other than faultcode, faultstring, faultactor and detail.

INCORRECT:
<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'>
  <faultcode>soap:Client</faultcode>
  <faultstring>Invalid message format</faultstring>
  <faultactor>http://example.org/someactor</faultactor>
  <detail>There were <b>lots</b> of elements in the message
          that I did not understand
  </detail>
  <m:Exception xmlns:m='http://example.org/faults/exceptions'>
    <m:ExceptionType>Severe</m:ExceptionType>
  </m:Exception>
</soap:Fault>

CORRECT:
<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'>
  <faultcode>soap:Client</faultcode>
  <faultstring>Invalid message format</faultstring>
  <faultactor>http://example.org/someactor</faultactor>
  <detail>
     <m:msg xmlns:m='http://example.org/faults/exceptions'>
         There were <b>lots</b> of elements in the message that I did not understand
     </m:msg>
     <m:Exception xmlns:m='http://example.org/faults/exceptions'>
       <m:ExceptionType>Severe</m:ExceptionType>
     </m:Exception>
  </detail>
</soap:Fault>

The children of the soap:Fault element are local to that element, therefore namespace qualification is unnecessary.[WS-I Basic Profile 1.0]


R1001
When a MESSAGE contains a soap:Fault element its element children MUST be unqualified.

For example,

INCORRECT:
<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'>
 <soap:faultcode>soap:Client</soap:faultcode>
 <soap:faultstring>Invalid message format</soap:faultstring>  <soap:faultactor>http://example.org/someactor</soap:faultactor>
 <soap:detail>
     <m:msg xmlns:m='http://example.org/faults/exceptions'>
         There were <b>lots</b> of elements in the message that
         I did not understand
      </m:msg>
 </soap:detail>
</soap:Fault>

CORRECT:
<soap:Fault xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'
            xmlns=''>
 <faultcode>soap:Client</faultcode>
 <faultstring>Invalid message format</faultstring>
 <faultactor>http://example.org/someactor</faultactor>
 <detail>
      <m:msg xmlns:m='http://example.org/faults/exceptions'>
          There were <b>lots</b> of elements in the message that
          I did not understand
      </m:msg>
  </detail>
</soap:Fault>

 

SOAP Fault Processing


When a Fault is generated, no further processing should be performed. In request-response exchanges, a Fault message will be transmitted to the sender of the request message, and some application level error will be flagged to the user. [WS-I Basic Profile 1.0]


R1028

When a Fault is generated by a RECEIVER, further processing SHOULD NOT be performed on the SOAP message aside from that which is necessary to rollback, or compensate for, any effects of processing the message prior to the generation of the Fault.


R1029

Where the normal outcome of processing a SOAP message would have resulted in the transmission of a SOAP response, but rather a SOAP Fault is generated instead, a RECEIVER MUST transmit a SOAP Fault message in place of the response.


R1030

A RECEIVER that generates a SOAP Fault SHOULD notify the end user that a SOAP Fault has been generated when practical, by whatever means is deemed appropriate to the circumstance.

 



Previous Next vertical dots separating previous/next from contents/index/pdf Contents

  |   |