import SOAP-WSDL 2.00_24 from CPAN
git-cpan-module: SOAP-WSDL git-cpan-version: 2.00_24 git-cpan-authorid: MKUTTER git-cpan-file: authors/id/M/MK/MKUTTER/SOAP-WSDL-2.00_24.tar.gz
This commit is contained in:
Martin Kutter
committed by
Michael G. Schwern
Michael G. Schwern
parent
b955c5ad79
commit
84b53d9261
+103
-120
@@ -6,7 +6,7 @@ SOAP::WSDL::Manual::Parser - How SOAP::WSDL parses XML messages
|
||||
|
||||
=head1 Which XML message does SOAP::WSDL parse ?
|
||||
|
||||
Naturally, there are two kinds of XML documents (or messages) SOAP::WSDL has
|
||||
Naturally, there are two kinds of XML documents (or messages) SOAP::WSDL has
|
||||
to parse:
|
||||
|
||||
=over
|
||||
@@ -17,77 +17,38 @@ to parse:
|
||||
|
||||
=back
|
||||
|
||||
=head1 Parser implementations
|
||||
|
||||
There are different parser implementations available for SOAP messages and
|
||||
There are different parser implementations available for SOAP messages and
|
||||
WSDL definitions.
|
||||
|
||||
Historically, SOAP::WSDL used SAX for parsing XML. The SAX handlers were
|
||||
implemented as L<XML::LibXML|XML::LibXML> handlers, which also worked with
|
||||
L<XML::SAX::ParserFactory|XML::SAX::ParserFactory>.
|
||||
=head1 WSDL definitions parser
|
||||
|
||||
Support for SAX and L<XML::LibXML|XML::LibXML> in SOAP::WSDL is discontinued
|
||||
for the following reasons:
|
||||
|
||||
=over
|
||||
|
||||
=item * Speed
|
||||
|
||||
L<XML::Parser::Expat|XML::Parser::Expat> is faster than
|
||||
L<XML::LibXML|XML::LibXML> - at least when optimized for speed.
|
||||
|
||||
High parsing speed is one of the key requirements for a SOAP toolkit - if XML
|
||||
serializing and (more important) deserializing are not fast enough, the whole
|
||||
toolkit is unusable.
|
||||
|
||||
=item * Availability
|
||||
|
||||
L<XML::Parser|XML::Parser> is more popular than L<XML::LibXML|XML::LibXML>.
|
||||
|
||||
=item * Stability
|
||||
|
||||
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.
|
||||
|
||||
XML::LibXML is also still under development, while XML::Parser has had time
|
||||
to stabilize.
|
||||
|
||||
=item * SOAP::Lite uses XML::Parser
|
||||
|
||||
L<SOAP::Lite|SOAP::Lite> uses L<XML::Parser|XML::Parser> if available.
|
||||
SOAP::WSDL should not require users to install both L<XML::Parser|XML::Parser>
|
||||
and L<XML::LibXML|XML::LibXML>.
|
||||
|
||||
=back
|
||||
|
||||
=head2 WSDL definitions parser
|
||||
|
||||
=over
|
||||
|
||||
=item * SOAP::WSDL::Expat::WSDLParser
|
||||
=head2 SOAP::WSDL::Expat::WSDLParser
|
||||
|
||||
A parser for WSDL definitions based on L<XML::Parser::Expat|XML::Parser::Expat>.
|
||||
|
||||
my $parser = SOAP::WSDL::Expat::WSDLParser->new();
|
||||
my $wsdl = $parser->parse_file( $filename );
|
||||
|
||||
=back
|
||||
The WSDL parser creates a tree of perl objects, whose root is a
|
||||
L<SOAP::WSDL::Definitions|SOAP::WSDL::Definitions> element.
|
||||
|
||||
=head2 SOAP messages parser
|
||||
=head1 SOAP messages parser
|
||||
|
||||
All SOAP message handler use class resolvers for finding out which class
|
||||
=head2 SOAP::WSDL::Expat::MessageParser
|
||||
|
||||
L<SOAP::WSDL::Expat::MessageParser|SOAP::WSDL::Expat::MessageParser> converts
|
||||
SOAP messages to SOAP::WSDL::XSD object trees.
|
||||
|
||||
It uses a class resolvers for finding out which class
|
||||
a particular XML element should be of, and type libs containing these classes.
|
||||
|
||||
=head3 Creating a class resolver
|
||||
|
||||
The easiest way for creating a class resolver is to run SOAP::WSDL's generator.
|
||||
|
||||
See wsdl2perl.pl
|
||||
See L<wsdl2perl.pl>.
|
||||
|
||||
The class resolver must implement a class method "get_class", which is passed
|
||||
The class resolver must implement a class method "get_class", which is passed
|
||||
a list ref of the current element's XPath (relative to Body), split by /.
|
||||
|
||||
This method must return a class name appropriate for a XML element.
|
||||
@@ -116,10 +77,10 @@ A class resolver package might look like this:
|
||||
|
||||
Sometimes there's unneccessary information transported in SOAP messages.
|
||||
|
||||
To skip XML nodes (including all child nodes), just edit the type map for
|
||||
the message and set the type map entry to '__SKIP__'.
|
||||
To skip XML nodes (including all child nodes), just edit the type map for
|
||||
the message and set the type map entry to '__SKIP__'.
|
||||
|
||||
In the example above, EnqueueMessage/StuffIDontNeed and all child elements
|
||||
In the example above, EnqueueMessage/StuffIDontNeed and all child elements
|
||||
are skipped.
|
||||
|
||||
my %class_list = (
|
||||
@@ -132,7 +93,7 @@ are skipped.
|
||||
'EnqueueMessage/StuffIDontNeed/Bar' => 'SOAP::WSDL::XSD::Builtin::string',
|
||||
);
|
||||
|
||||
Note that only SOAP::WSDL::Expat::MessageParser implements skipping elements
|
||||
Note that only SOAP::WSDL::Expat::MessageParser implements skipping elements
|
||||
at the time of writing.
|
||||
|
||||
=head3 Creating type lib classes
|
||||
@@ -141,81 +102,87 @@ Every element must have a correspondent one in the type library.
|
||||
|
||||
Builtin types should be resolved as SOAP::WSDL::XSD::Builtin::* classes
|
||||
|
||||
Creating a type lib is easy: Just run SOAP::WSDL's generator - it will
|
||||
Creating a type lib is easy: Just run SOAP::WSDL's generator - it will
|
||||
create both a typemap and the type lib classes for a WSDL file.
|
||||
|
||||
Sometimes it is nessecary to create type lib classes by hand - not all
|
||||
Sometimes it is nessecary to create type lib classes by hand - not all
|
||||
WSDL definitions are complete.
|
||||
|
||||
For writing your own lib classes, see L<SOAP::WSDL::XSD::Typelib::Element>,
|
||||
L<SOAP::WSDL::XSD::Typelib::ComplexType> and L<SOAP::WSDL::XSD::Typelib::SimpleType>.
|
||||
|
||||
=head3 Parser implementations
|
||||
=head2 SOAP::WSDL::Expat::Message2Hash
|
||||
|
||||
Transforms a SOAP message into a perl hash refs. Using this parser is usually
|
||||
triggered by calling the C<outputhash> method of SOAP::WSDL, or by using
|
||||
L<SOAP::WSDL::Deserializer::Hash|SOAP::WSDL::Deserializer::Hash>.
|
||||
|
||||
Acts somewhat like XML::Simple, but faster.
|
||||
|
||||
The following restrictions apply:
|
||||
|
||||
=over
|
||||
|
||||
=item * SOAP::WSDL::Expat::MessageParser
|
||||
=item * Ignores all namespaces
|
||||
|
||||
A L<XML::Parser::Expat|XML::Parser::Expat> based parser. This is the fastest
|
||||
parser for most SOAP messages and the default for SOAP::WSDL::Client.
|
||||
=item * Ignores all attributes
|
||||
|
||||
=item * SOAP::WSDL::Expat::MessageStreamParser
|
||||
=item * Does not handle mixed content
|
||||
|
||||
A XML::Parser::ExpatNB based parser. Useful for parsing huge HTTP responses,
|
||||
as you don't need to keep everything in memory.
|
||||
|
||||
See L<SOAP::WSDL::Expat::MessageStreamParser|SOAP::WSDL::Expat::MessageStreamParser>
|
||||
for details.
|
||||
=item * The SOAP header is ignored
|
||||
|
||||
=back
|
||||
|
||||
=head3 Performance
|
||||
|
||||
SOAP::WSDL::Expat::MessageParser is the fastest way of parsing SOAP messages
|
||||
into object trees and only slightly slower than converting them into hash
|
||||
data structures:
|
||||
|
||||
Parsing a SOAP message with a length of 5962 bytes:
|
||||
SOAP::WSDL::Expat::MessageParser:
|
||||
3 wallclock secs ( 3.28 usr + 0.05 sys = 3.33 CPU) @ 60.08/s (n=200)
|
||||
|
||||
SOAP::WSDL::SAX::MessageHandler (with raw XML::LibXML):
|
||||
5 wallclock secs ( 4.95 usr + 0.00 sys = 4.95 CPU) @ 40.38/s (n=200)
|
||||
|
||||
XML::Simple (XML::Parser):
|
||||
3 wallclock secs ( 2.36 usr + 0.03 sys = 2.39 CPU) @ 83.65/s (n=200)
|
||||
|
||||
XML::Simple (XML::SAX::Expat):
|
||||
7 wallclock secs ( 6.50 usr + 0.03 sys = 6.53 CPU) @ 30.62/s (n=200)
|
||||
|
||||
As the benchmark shows, all SOAP::WSDL parser variants are faster than
|
||||
XML::Simple with XML::SAX::Expat, and SOAP::WSDL::Expat::MessageParser almost
|
||||
reaches the performance of XML::Simple with XML::Parser as backend.
|
||||
|
||||
Parsing SOAP responses in chunks does not increase speed - at least not up
|
||||
to a response size of around 500k:
|
||||
|
||||
Benchmark: timing 5 iterations of SOAP::WSDL::SAX::MessageHandler,
|
||||
SOAP::WSDL::Expat::MessageParser, SOAP::WSDL::Expat::MessageStreamParser...
|
||||
|
||||
SOAP::WSDL::Expat::MessageStreamParser:
|
||||
13 wallclock secs ( 7.39 usr + 0.09 sys = 7.48 CPU) @ 0.67/s (n=5)
|
||||
|
||||
SOAP::WSDL::Expat::MessageParser:
|
||||
10 wallclock secs ( 5.81 usr + 0.06 sys = 5.88 CPU) @ 0.85/s (n=5)
|
||||
|
||||
SOAP::WSDL::SAX::MessageHandler:
|
||||
14 wallclock secs ( 8.78 usr + 0.03 sys = 8.81 CPU) @ 0.57/s (n=5)
|
||||
|
||||
Response size: 344330 bytes
|
||||
=cut
|
||||
|
||||
=head1 OLD SAX HANDLER
|
||||
|
||||
The old SAX handler historically used in SOAP::WSDL are not included in
|
||||
Historically, SOAP::WSDL used SAX for parsing XML. The SAX handlers were
|
||||
implemented as L<XML::LibXML|XML::LibXML> handlers, which also worked with
|
||||
L<XML::SAX::ParserFactory|XML::SAX::ParserFactory>.
|
||||
|
||||
Support for SAX and L<XML::LibXML|XML::LibXML> in SOAP::WSDL is discontinued
|
||||
for the following reasons:
|
||||
|
||||
=over
|
||||
|
||||
=item * Speed
|
||||
|
||||
L<XML::Parser::Expat|XML::Parser::Expat> is faster than
|
||||
L<XML::LibXML|XML::LibXML> - at least when optimized for speed.
|
||||
|
||||
High parsing speed is one of the key requirements for a SOAP toolkit - if XML
|
||||
serializing and (more important) deserializing are not fast enough, the whole
|
||||
toolkit is unusable.
|
||||
|
||||
=item * Availability
|
||||
|
||||
L<XML::Parser|XML::Parser> is more popular than L<XML::LibXML|XML::LibXML>.
|
||||
|
||||
=item * Stability
|
||||
|
||||
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.
|
||||
|
||||
XML::LibXML is also still under development, while XML::Parser has had time
|
||||
to stabilize.
|
||||
|
||||
=item * SOAP::Lite uses XML::Parser
|
||||
|
||||
L<SOAP::Lite|SOAP::Lite> uses L<XML::Parser|XML::Parser> if available.
|
||||
SOAP::WSDL should not require users to install both L<XML::Parser|XML::Parser>
|
||||
and L<XML::LibXML|XML::LibXML>.
|
||||
|
||||
=back
|
||||
|
||||
The old SAX handler historically used in SOAP::WSDL are not included in
|
||||
the SOAP::WSDL package any more.
|
||||
|
||||
However, they may be obtained from the "attic" directory in
|
||||
SOAP::WSDL's SVN repository at
|
||||
However, they may be obtained from the "attic" directory in
|
||||
SOAP::WSDL's SVN repository at
|
||||
|
||||
https://soap-wsdl.svn.sourceforge.net/svnroot/soap-wsdl/SOAP-WSDL/trunk/attic
|
||||
|
||||
@@ -223,10 +190,10 @@ https://soap-wsdl.svn.sourceforge.net/svnroot/soap-wsdl/SOAP-WSDL/trunk/attic
|
||||
|
||||
=item * SOAP::WSDL::SAX::WSDLHandler
|
||||
|
||||
This is a SAX handler for parsing WSDL files into object trees SOAP::WSDL
|
||||
This is a SAX handler for parsing WSDL files into object trees SOAP::WSDL
|
||||
works with.
|
||||
|
||||
It's built as a native handler for XML::LibXML, but will also work with
|
||||
It's built as a native handler for XML::LibXML, but will also work with
|
||||
XML::SAX::ParserFactory.
|
||||
|
||||
To parse a WSDL file, use one of the following variants:
|
||||
@@ -237,7 +204,6 @@ To parse a WSDL file, use one of the following variants:
|
||||
$parser->parse( $xml );
|
||||
my $data = $handler->get_data();
|
||||
|
||||
|
||||
my $handler = SOAP::WSDL::SAX::WSDLHandler->new({
|
||||
base => 'XML::SAX::Base'
|
||||
});
|
||||
@@ -247,18 +213,35 @@ To parse a WSDL file, use one of the following variants:
|
||||
$parser->parse( $xml );
|
||||
my $data = $handler->get_data();
|
||||
|
||||
|
||||
=item * SOAP::WSDL::SAX::MessageHandler
|
||||
|
||||
This is a SAX handler for parsing WSDL files into object trees SOAP::WSDL
|
||||
This is a SAX handler for parsing WSDL files into object trees SOAP::WSDL
|
||||
works with.
|
||||
|
||||
It's built as a native handler for XML::LibXML, but will also work with
|
||||
It's built as a native handler for XML::LibXML, but will also work with
|
||||
XML::SAX::ParserFactory.
|
||||
|
||||
Can be used for parsing both streams (chunks) and documents.
|
||||
Can be used for parsing both streams (chunks) and documents.
|
||||
|
||||
=back
|
||||
|
||||
=head1 LICENSE AND COPYRIGHT
|
||||
|
||||
Copyright 2007 Martin Kutter.
|
||||
|
||||
This file is part of SOAP-WSDL. You may distribute/modify it under
|
||||
the same terms as perl itself.
|
||||
|
||||
=head1 AUTHOR
|
||||
|
||||
Martin Kutter E<lt>martin.kutter fen-net.deE<gt>
|
||||
|
||||
=head1 REPOSITORY INFORMATION
|
||||
|
||||
$Rev: 391 $
|
||||
$LastChangedBy: kutterma $
|
||||
$Id: Parser.pod 391 2007-11-17 21:56:13Z kutterma $
|
||||
$HeadURL: http://soap-wsdl.svn.sourceforge.net/svnroot/soap-wsdl/SOAP-WSDL/trunk/lib/SOAP/WSDL/Manual/Parser.pod $
|
||||
|
||||
=cut
|
||||
|
||||
=cut
|
||||
Reference in New Issue
Block a user