W3C home > Mailing lists > Public > xmlp-comments@w3.org > July 2002

SOAP 1.2 LC Issue: Clarification on Use of Multiple Fault Codes

From: Henrik Frystyk Nielsen <henrikn@microsoft.com>
Date: Fri, 19 Jul 2002 16:24:33 -0700
Message-ID: <79107D208BA38C45A4E45F62673A434D0851525F@red-msg-07.redmond.corp.microsoft.com>
To: <xmlp-comments@w3.org>


In [1], it is stated that:

"SOAP fault codes are intended for use by software to provide an
algorithmic mechanism for identifying the fault.

The values of the Value child element information item of the Code
element information item are restricted to those in Table 2. Additional
fault subcodes MAY be created for use by applications or features. Such
subcodes are carried in the Value child element information item of the
Subcode element information item."

However, the text says very little about what the semantics of multiple
fault codes are and how these may relate to the SOAP Detail EII.

For example, is the contents of the Detail EII entirely orthogonal to
the fault codes, or do I have to understand the fault codes in order to
properly understand the details? I think this should be stated in order
to provide unambiguous semantics for SOAP faults.

Something like this may work as clarifying text for [1]:

SOAP Fault Codes
----------------

SOAP fault codes are intended for use by software to provide an
algorithmic mechanism for identifying the fault. SOAP fault codes are
organized as a linked list of XML qualified names allowing a SOAP node
to identify the fault category at an increasing level of detail of the
SOAP fault. This is similar to the model used in other application layer
protocols like HTTP and SMTP. For example, in HTTP, there is a model of
three-digit status codes where the first digit indicates the overall
class of fault responses as described by RFC 2616. In SMTP, which also
uses a three-digit status code, the three digits of the reply each have
a special significance as described by RFC 2881:

"The first digit denotes whether the response is good, bad or
incomplete. An unsophisticated SMTP client, or one that receives an
unexpected code, will be able to determine its next action (proceed as
planned, redo, retrench, etc.) by examining this first digit. An SMTP
client that wants to know approximately what kind of error occurred
(e.g., mail system error, command syntax error) may examine the second
digit. The third digit and any supplemental information that may be
present is reserved for the finest gradation of information."

The top-level fault code is reserved by this specification using the
values defined by the faultCodeEnum type in the
"http://www.w3.org/2002/06/soap-envelope" namespace. Additional fault
subcodes MAY be created for use by applications or features. Such
subcodes are carried in the Value child element information item of the
Subcode element information item.

SOAP fault codes are to be interpreted as modifiers of contents of the
Detail EII in the sense that they provide the context for the contents
of Detail EII. A SOAP node MUST understand all SOAP fault codes in a
SOAP fault message in order to be able to interpret the Detail element
in a SOAP fault.

For example, if the Detail EII contains a timeout value, this value is
to be interpreted in the context of the SOAP fault codes. In the example
below, this means that the foo:MaxTime EII value is to be interpreted in
the context of the env:Sender, foo:Timeout fault code list.

<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope"
              xmlns:foo="http://www.example.org/timeouts">
 <env:Body>
  <env:Fault>
   <env:Code>
    <env:Value>env:Sender</env:Value>
    <env:Subcode>
     <env:Value>foo:MessageTimeout</env:Value>
    </env:Subcode>
   </env:Code>
   <env:Reason>Sender Timeout</env:Reason>
   <env:Detail>
    <foo:MaxTime>P5M</foo:MaxTime>
   </env:Detail>    
   </env:Fault>
 </env:Body>
</env:Envelope>

This specification does not define a limit for how many Subcode EII a
SOAP fault might contain. Implementations should always follow the
Robustness Principle [2] for interpreting SOAP fault codes. However,
while not a requirement of this specification, it is anticipated that
most practical examples can be supported by relatively few Subcode
EIIs."

Table 2: SOAP Fault Codes

...continue with table contents...

Henrik

[1] http://www.w3.org/TR/2002/WD-soap12-part1-20020626/#faultcodes
[2] http://www.w3.org/TR/2002/WD-soap12-part1-20020626/#robustnessprinc
Received on Friday, 19 July 2002 19:25:06 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 27 October 2009 08:42:27 GMT