.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SOAP::WSDL::Manual::Parser 3pm"
.TH SOAP::WSDL::Manual::Parser 3pm "2014-01-15" "perl v5.18.1" "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