\chapter{The \module{ParsedSoap} module --- basic message handling}

This class represents an input stream that has been parsed as a SOAP
message.

\begin{classdesc}{ParsedSoap}{input\optional{, **keywords}}
Creates a \class{ParsedSoap} object from the provided input source.
If \code{input} is not a string, then it must be an object with a
\method{read()} method that supports the standard Python ``file read''
semantics.

The following keyword arguments may be used:

\begin{tableiii}{l|c|p{30em}}{textrm}{Keyword}{Default}{Description}
\lineiii{\code{keepdom}}{\code{0}}{Do not release the DOM when this
object is destroyed.
\versionadded{1.2}}
\lineiii{\code{readerclass}}{\code{None}}{Class used to create DOM-creating
XML readers; described below.
\versionadded{1.2}}
\lineiii{\code{resolver}}{\code{None}}{Value for the \code{resolver}
attribute; see below.}
\lineiii{\code{trailers}}{\code{0}}{Allow trailing data elements
to appear after the \code{Body}.}
\end{tableiii}

\end{classdesc}

The following attributes of a \class{ParsedSoap} are read-only:

\begin{memberdesc}{body}
The root of the SOAP \code{Body} element.
Using the \method{GetElementNSdict()} method on this attribute can be useful
to get a dictionary to be used with the \class{SoapWriter} class.
\end{memberdesc}

\begin{memberdesc}{body_root}
The element that contains the SOAP serialization root; that is,
the element in the SOAP \code{Body} that ``starts off'' the data.
\end{memberdesc}

\begin{memberdesc}{data_elements}
A (possibly empty) list of all child elements of the \code{Body} other
than the root.
\end{memberdesc}

\begin{memberdesc}{header}
The root of the SOAP \code{Header} element.
Using the \method{GetElementNSdict()} method on this attribute can be useful
to get a dictionary to be used with the \class{SoapWriter} class.
\end{memberdesc}

\begin{memberdesc}{header_elements}
A (possibly empty) list of all elements in the SOAP \code{Header}.
\end{memberdesc}

\begin{memberdesc}{trailer_elements}
Returns a (possibly empty) list of all elements following the \code{Body}.
If the \code{trailers} keyword was not used when the object was
constructed, this attribute will not be instantiated and retrieving
it will raise an exception.
\end{memberdesc}

The following attribute may be modified:

\begin{memberdesc}{resolver}
If not \code{None},
this attribute can be invoked to handle absolute \code{href}'s in the SOAP data.
It will be invoked as follows:

\begin{methoddesc}{resolver}{uri, tc, ps, **keywords}
The \code{uri} parameter is the URI to resolve.
The \code{tc} parameter is the typecode that needs to resolve \code{href}; this
may be needed to properly interpret the content of a MIME bodypart, for example.
The \code{ps} parameter is the \class{ParsedSoap} object that is invoking
the resolution (this allows a single resolver instance to handle multiple
SOAP parsers).

Failure to resolve the URI should result in an exception being raised.
If there is no content, return \code{None}; this is not the same as an
empty string.
If there is content, the data returned should be in a form understandable
by the typecode.
\end{methoddesc}
\end{memberdesc}

The following methods are available:

\begin{methoddesc}{Backtrace}{elt}
Returns a human-readable ``trace'' from the document root to the
specified element.
\end{methoddesc}

\begin{methoddesc}{FindLocalHREF}{href, elt}
Returns the element that has an \code{id} attribute whose value is specified
by the \code{href} fragment identifier.
The \code{href} \emph{must} be a fragment reference --- that is, it must
start with a pound sign.
This method raises an \exception{EvaluateException} exception if the
element isn't found.
It is mainly for use by the parsing methods in the \module{TypeCode} module.
\end{methoddesc}

\begin{methoddesc}{GetElementNSdict}{elt}
Return a dictionary for all the namespace entries active at the
current element. Each dictionary key will be the prefix and the value will
be the namespace URI.
\end{methoddesc}

\begin{methoddesc}{GetMyHeaderElements}{\optional{actorlist=None}}
Returns a list of all elements in the \code{Header} that are intended for
\emph{this} SOAP processor.
This includes all elements that either have no SOAP \code{actor}
attribute, or whose value is either the special ``next actor'' value or
in the \code{actorlist} list of URI's.
\end{methoddesc}

\begin{methoddesc}{IsAFault}{}
Returns true if the message is a SOAP fault.
\end{methoddesc}

\begin{methoddesc}{Parse}{how}
Parses the SOAP \code{Body} according to the \code{how} parameter,
and returns a Python object.
If \code{how} is not a \class{TC.TypeCode} object, then it should be a
Python class object that has a \code{typecode} attribute.
\end{methoddesc}

\begin{methoddesc}{ResolveHREF}{uri, tc\optional{, **keywords}}
This method is invoked to resolve an absolute URI.
If the typecode \code{tc} has a \code{resolver} attribute, it will use it
to resolve the URI specified in the \code{uri} parameter,
otherwise it will use its own \code{resolver}, or raise an
\exception{EvaluateException} exception.

Any \code{keyword} parameters will be passed to the chosen resolver.
If no content is available, it will return \code{None}.
If unable to resolve the URI it will raise an
\exception{EvaluateException} exception.
Otherwise, the resolver should return data in a form acceptable to the
specified typecode, \code{tc}.
(This will almost always be a file-like object holding opaque data;
for XML, it may be a DOM tree.)
\end{methoddesc}

\begin{methoddesc}{WhatActorsArePresent}{}
Returns a list of the values of all the SOAP \code{actor} attributes
found in child elements of the SOAP \code{Header}.
\end{methoddesc}

\begin{methoddesc}{WhatMustIUnderstand}{}
Returns a list of \samp{(uri, localname)} tuples for all elements in the
SOAP \code{Header} that have the SOAP \code{mustUnderstand} attribute set
to a non-zero value.
\end{methoddesc}

\ZSI{} supports multiple DOM implementations.
The \code{readerclass} parameter specifies which one to use.
The default is to use the DOM provided with the PyXML package developed
by the Python XML SIG, provided through the \class{PyExpat.Reader} class
in the \module{xml.dom.ext.reader} module.
To use the \code{cDomlette} DOM provided by the 4Suite package, use the
\class{RawExpatReader} class in the \module{Ft.Lib.cDomlette} module.

The specified reader class must support the following methods:

\begin{methoddesc}{fromString}{string}
Return a DOM object from a string.
\end{methoddesc}

\begin{methoddesc}{fromStream}{stream}
Return a DOM object from a file-like stream.
\end{methoddesc}

\begin{methoddesc}{releaseNode}{dom}
Free the specified DOM object.
\end{methoddesc}

The DOM object must support the standard Python mapping of the DOM Level 2
specification.
While only a small subset of specification is used, the particular
methods and attributes used by \ZSI{} are available only
by inspecting the source.
