\chapter{The \module{Fault} module --- reporting errors}

SOAP defines a \emph{fault} message as the way for a recipient to
indicate it was unable to process a message.
The \ZSI{} \class{Fault} class encapsulates this.

\begin{classdesc}{Fault}{code, string\optional{, **keywords}}
The \var{code} parameter is a text string identifying the SOAP fault
code, a namespace-qualified name.
The class attribute \code{Fault.Client} can be used to indicate a problem with
an incoming message, \code{Fault.Server} can be used to
indicate a problem occurred while processing the request, or \code{Fault.MU}
can be used to indicate a problem with the SOAP \code{mustUnderstand}
attribute.
The \var{string} parameter is a human-readable text string describing the
fault.

The following keyword arguments may be used:

\begin{tableiii}{l|c|p{30em}}{textrm}{Keyword}{Default}{Description}
\lineiii{\var{actor}}{\code{None}}{A string identifying the \code{actor}
attribute that caused the problem (usually because it is unknown).}
\lineiii{\var{detail}}{\code{None}}{A sequence
of elements to output in the \code{detail} element; it may also
be a text string, in which case it is output as-is, and should
therefore be XML text.}
\lineiii{\var{headerdetail}}{\code{None}}{Data, treated the same as
the \code{detail} keyword, to be output in the SOAP header.  See
the following paragraph.}
\end{tableiii}

If the fault occurred in the SOAP \code{Header}, the specification
requires that the detail be sent back as an element within
the SOAP \code{Header} element.
Unfortunately, the SOAP specification does not describe how to encode
this; \ZSI{} defines and uses a
\code{ZSI:detail} element, which is analogous to the SOAP \code{detail}
element.
\end{classdesc}

The following attributes are read-only:

\begin{memberdesc}{actor}
A text string holding the value of the SOAP \code{faultactor} element.
\end{memberdesc}

\begin{memberdesc}{code}
A text string holding the value of the SOAP \code{faultcode} element.
\end{memberdesc}

\begin{memberdesc}{detail}
A text string or sequence of elements containing holding the value of the
SOAP \code{detail} element, when available.
\end{memberdesc}

\begin{memberdesc}{headerdetail}
A text string or sequence of elements containing holding the value of the
\ZSI{} header detail element, when available.
\end{memberdesc}

\begin{memberdesc}{string}
A text string holding the value of the SOAP \code{faultstring} element.
\end{memberdesc}

\begin{methoddesc}{AsSOAP}{\optional{, **kw}}
This method serializes the \class{Fault} object into a SOAP message.
The message is returned as a string.
Any keyword arguments are passed to the \class{SoapWriter} constructor.
\versionadded{1.1; the old \method{AsSoap()} method is still available}
\end{methoddesc}

If other data is going to be sent with the fault, the following
two methods can be used.
Because some data might need to be output in the SOAP \code{Header},
serializing a fault is a two-step process.

\begin{methoddesc}{DataForSOAPHeader}{}
This method returns a text string that can be included as the
\code{header} parameter for constructing a \class{SoapWriter} object.
\end{methoddesc}

\begin{methoddesc}{serialize}{sw}
This method outputs the fault object onto the \var{sw} object, which is a
\class{SoapWriter} instance.
\end{methoddesc}

Some convenience functions are available to create a \class{Fault}
from common conditions.

\begin{funcdesc}{FaultFromActor}{uri\optional{, actor}}
This function could be used when an application receives a message
that has a SOAP \code{Header} element directed to an actor that
cannot be processed.
The \var{uri} parameter identifies the actor.
The \var{actor} parameter can be used to specify a URI that identifies the
application, if it is not the ultimate recipient of the SOAP message.
\end{funcdesc}

\begin{funcdesc}{FaultFromException}{ex, inheader\optional{,
    tb\optional{, actor}}}
This function creates a \class{Fault} from a general Python exception.
A SOAP ``server'' fault is created.
The \var{ex} parameter should be the Python exception.
The \var{inheader} parameter should be true if the error was
found on a SOAP \code{Header} element.
The optional \var{tb} parameter may be a Python traceback
object, as returned by \samp{sys.exc_info()[2]}.
The \var{actor} parameter can be used to specify a URI that identifies the
application, if it is not the ultimate recipient of the SOAP message.
\end{funcdesc}

\begin{funcdesc}{FaultFromFaultMessage}{ps}
This function creates a \class{Fault} from a \class{ParsedSoap} object
passed in as \var{ps}.
It should only be used if the \method{IsAFault()} method returned true.
\end{funcdesc}

\begin{funcdesc}{FaultFromNotUnderstood}{uri, localname,\optional{, actor}}
This function could be used when an application receives a message with
the SOAP \code{mustUnderstand} attribute that it does not understand.
The \var{uri} and \var{localname} parameters should identify
the unknown element.
The \var{actor} parameter can be used to specify a URI that identifies the
application, if it is not the ultimate recipient of the SOAP message.
\end{funcdesc}

\begin{funcdesc}{FaultFromZSIException}{ex\optional{, actor}}
This function creates a \class{Fault} object from a \ZSI{} exception,
\exception{ParseException} or \exception{EvaluateException}, passed in
as \var{ex}.
A SOAP ``client'' fault is created.
The \var{actor} parameter can be used to specify a URI that identifies the
application, if it is not the ultimate recipient of the SOAP message.
\end{funcdesc}

