.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SOAP::WSDL::Manual::Parser 3pm"
.TH SOAP::WSDL::Manual::Parser 3pm "2020-01-20" "perl v5.30.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
SOAP::WSDL::Manual::Parser \- How SOAP::WSDL parses XML messages
.SH "Which XML message does SOAP::WSDL parse ?"
.IX Header "Which XML message does SOAP::WSDL parse ?"
Naturally, there are two kinds of \s-1XML\s0 documents (or messages) \s-1SOAP::WSDL\s0 has
to parse:
.IP "\(bu" 4
\&\s-1WSDL\s0 definitions
.IP "\(bu" 4
\&\s-1SOAP\s0 messages
.PP
There are different parser implementations available for \s-1SOAP\s0 messages and
\&\s-1WSDL\s0 definitions.
.SH "WSDL definitions parser"
.IX Header "WSDL definitions parser"
.SS "SOAP::WSDL::Expat::WSDLParser"
.IX Subsection "SOAP::WSDL::Expat::WSDLParser"
A parser for \s-1WSDL\s0 definitions based on XML::Parser::Expat.
.PP
.Vb 2
\& my $parser = SOAP::WSDL::Expat::WSDLParser\->new();
\& my $wsdl = $parser\->parse_file( $filename );
.Ve
.PP
The \s-1WSDL\s0 parser creates a tree of perl objects, whose root is a
SOAP::WSDL::Definitions element.
.SH "SOAP messages parser"
.IX Header "SOAP messages parser"
.SS "SOAP::WSDL::Expat::MessageParser"
.IX Subsection "SOAP::WSDL::Expat::MessageParser"
SOAP::WSDL::Expat::MessageParser converts
\&\s-1SOAP\s0 messages to \s-1SOAP::WSDL::XSD\s0 object trees.
.PP
It uses a class resolvers for finding out which class
a particular \s-1XML\s0 element should be of, and type libs containing these classes.
.PP
\fICreating a class resolver\fR
.IX Subsection "Creating a class resolver"
.PP
The easiest way for creating a class resolver is to run \s-1SOAP::WSDL\s0's generator.
.PP
See wsdl2perl.
.PP
The class resolver must implement a class method \*(L"get_class\*(R", which is passed
a list ref of the current element's XPath (relative to Body), split by /.
.PP
This method must return a class name appropriate for a \s-1XML\s0 element.
.PP
A class resolver package might look like this:
.PP
.Vb 1
\& package ClassResolver;
\&
\& my %class_list = (
\&    \*(AqEnqueueMessage\*(Aq => \*(AqTypelib::TEnqueueMessage\*(Aq,
\&    \*(AqEnqueueMessage/MMessage\*(Aq => \*(AqTypelib::TMessage\*(Aq,
\&    \*(AqEnqueueMessage/MMessage/MRecipientURI\*(Aq => \*(AqSOAP::WSDL::XSD::Builtin::anyURI\*(Aq,
\&    \*(AqEnqueueMessage/MMessage/MMessageContent\*(Aq => \*(AqSOAP::WSDL::XSD::Builtin::string\*(Aq,
\& );
\&
\& sub new { return bless {}, \*(AqClassResolver\*(Aq };
\&
\& sub get_class {
\&    my $name = join(\*(Aq/\*(Aq, @{ $_[1] });
\&    return ($class_list{ $name }) ? $class_list{ $name }
\&        : warn "no class found for $name";
\& };
\& 1;
.Ve
.PP
\fISkipping unwanted items\fR
.IX Subsection "Skipping unwanted items"
.PP
Sometimes there's unnecessary information transported in \s-1SOAP\s0 messages.
.PP
To skip \s-1XML\s0 nodes (including all child nodes), just edit the type map for
the message and set the type map entry to '_\|_SKIP_\|_'.
.PP
In the example above, EnqueueMessage/StuffIDontNeed and all child elements
are skipped.
.PP
.Vb 9
\& my %class_list = (
\&    \*(AqEnqueueMessage\*(Aq => \*(AqTypelib::TEnqueueMessage\*(Aq,
\&    \*(AqEnqueueMessage/MMessage\*(Aq => \*(AqTypelib::TMessage\*(Aq,
\&    \*(AqEnqueueMessage/MMessage/MRecipientURI\*(Aq => \*(AqSOAP::WSDL::XSD::Builtin::anyURI\*(Aq,
\&    \*(AqEnqueueMessage/MMessage/MMessageContent\*(Aq => \*(AqSOAP::WSDL::XSD::Builtin::string\*(Aq,
\&    \*(AqEnqueueMessage/StuffIDontNeed\*(Aq => \*(Aq_\|_SKIP_\|_\*(Aq,
\&    \*(AqEnqueueMessage/StuffIDontNeed/Foo\*(Aq => \*(AqSOAP::WSDL::XSD::Builtin::string\*(Aq,
\&    \*(AqEnqueueMessage/StuffIDontNeed/Bar\*(Aq => \*(AqSOAP::WSDL::XSD::Builtin::string\*(Aq,
\& );
.Ve
.PP
Note that only SOAP::WSDL::Expat::MessageParser implements skipping elements
at the time of writing.
.PP
\fICreating type lib classes\fR
.IX Subsection "Creating type lib classes"
.PP
Every element must have a correspondent one in the type library.
.PP
Builtin types should be resolved as SOAP::WSDL::XSD::Builtin::* classes
.PP
Creating a type lib is easy: Just run \s-1SOAP::WSDL\s0's generator \- it will
create both a typemap and the type lib classes for a \s-1WSDL\s0 file.
.PP
Sometimes it is nessecary to create type lib classes by hand \- not all
\&\s-1WSDL\s0 definitions are complete.
.PP
For writing your own lib classes, see SOAP::WSDL::XSD::Typelib::Element,
SOAP::WSDL::XSD::Typelib::ComplexType and SOAP::WSDL::XSD::Typelib::SimpleType.
.SS "SOAP::WSDL::Expat::Message2Hash"
.IX Subsection "SOAP::WSDL::Expat::Message2Hash"
Transforms a \s-1SOAP\s0 message into a perl hash refs. Using this parser is usually
triggered by calling the \f(CW\*(C`outputhash\*(C'\fR method of \s-1SOAP::WSDL,\s0 or by using
SOAP::WSDL::Deserializer::Hash.
.PP
Acts somewhat like XML::Simple, but faster.
.PP
The following restrictions apply:
.IP "\(bu" 4
Ignores all namespaces
.IP "\(bu" 4
Ignores all attributes
.IP "\(bu" 4
Does not handle mixed content
.IP "\(bu" 4
The \s-1SOAP\s0 header is ignored
.SH "OLD SAX HANDLER"
.IX Header "OLD SAX HANDLER"
Historically, \s-1SOAP::WSDL\s0 used \s-1SAX\s0 for parsing \s-1XML.\s0 The \s-1SAX\s0 handlers were
implemented as XML::LibXML handlers, which also worked with
XML::SAX::ParserFactory.
.PP
Support for \s-1SAX\s0 and XML::LibXML in \s-1SOAP::WSDL\s0 is discontinued
for the following reasons:
.IP "\(bu" 4
Speed
.Sp
XML::Parser::Expat is faster than
XML::LibXML \- at least when optimized for speed.
.Sp
High parsing speed is one of the key requirements for a \s-1SOAP\s0 toolkit \- if \s-1XML\s0
serializing and (more important) deserializing are not fast enough, the whole
toolkit is unusable.
.IP "\(bu" 4
Availability
.Sp
XML::Parser is more popular than XML::LibXML.
.IP "\(bu" 4
Stability
.Sp
XML::LibXML is based on the libxml2 library. Several versions of
libxml2 are known to have specific bugs. As a workaround, there are
often several versions of libxml2 installed on one system. This may
lead to problems on operating systems which cannot load more than
one version of a shared library simultaneously.
.Sp
XML::LibXML is also still under development, while XML::Parser has had time
to stabilize.
.IP "\(bu" 4
SOAP::Lite uses XML::Parser
.Sp
SOAP::Lite uses XML::Parser if available.
\&\s-1SOAP::WSDL\s0 should not require users to install both XML::Parser
and XML::LibXML.
.PP
The old \s-1SAX\s0 handler historically used in \s-1SOAP::WSDL\s0 are not included in
the \s-1SOAP::WSDL\s0 package any more.
.PP
However, they may be obtained from the \*(L"attic\*(R" directory in
\&\s-1SOAP::WSDL\s0's \s-1SVN\s0 repository at
.PP
https://soap\-wsdl.svn.sourceforge.net/svnroot/soap\-wsdl/SOAP\-WSDL/trunk/attic
.IP "\(bu" 4
SOAP::WSDL::SAX::WSDLHandler
.Sp
This is a \s-1SAX\s0 handler for parsing \s-1WSDL\s0 files into object trees \s-1SOAP::WSDL\s0
works with.
.Sp
It's built as a native handler for XML::LibXML, but will also work with
XML::SAX::ParserFactory.
.Sp
To parse a \s-1WSDL\s0 file, use one of the following variants:
.Sp
.Vb 5
\& my $parser = XML::LibXML\->new();
\& my $handler = SOAP::WSDL::SAX::WSDLHandler\->new();
\& $parser\->set_handler( $handler );
\& $parser\->parse( $xml );
\& my $data = $handler\->get_data();
\& 
\& my $handler = SOAP::WSDL::SAX::WSDLHandler\->new({
\&        base => \*(AqXML::SAX::Base\*(Aq
\& });
\& my $parser = XML::SAX::ParserFactor\->parser(
\&    Handler => $handler
\& );
\& $parser\->parse( $xml );
\& my $data = $handler\->get_data();
.Ve
.IP "\(bu" 4
SOAP::WSDL::SAX::MessageHandler
.Sp
This is a \s-1SAX\s0 handler for parsing \s-1WSDL\s0 files into object trees \s-1SOAP::WSDL\s0
works with.
.Sp
It's built as a native handler for XML::LibXML, but will also work with
XML::SAX::ParserFactory.
.Sp
Can be used for parsing both streams (chunks) and documents.
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright 2007 Martin Kutter.
.PP
This file is part of SOAP-WSDL. You may distribute/modify it under
the same terms as perl itself.
.SH "AUTHOR"
.IX Header "AUTHOR"
Martin Kutter <martin.kutter fen\-net.de>
.SH "REPOSITORY INFORMATION"
.IX Header "REPOSITORY INFORMATION"
.Vb 4
\& $Rev: 391 $
\& $LastChangedBy: kutterma $
\& $Id: Parser.pod 391 2007\-11\-17 21:56:13Z kutterma $
\& $HeadURL: https://soap\-wsdl.svn.sourceforge.net/svnroot/soap\-wsdl/SOAP\-WSDL/trunk/lib/SOAP/WSDL/Manual/Parser.pod $
.Ve