1SOAP::WSDL::Manual::ParUsseerr(3C)ontributed Perl DocumeSnOtAaPt:i:oWnSDL::Manual::Parser(3)
2
6 SOAP::WSDL::Manual::Parser - How SOAP::WSDL parses XML messages
7
9 Naturally, there are two kinds of XML documents (or messages)
10 SOAP::WSDL has to parse:
11 • WSDL definitions
13 • SOAP messages
15 There are different parser implementations available for SOAP messages
17 and WSDL definitions.
18
20 SOAP::WSDL::Expat::WSDLParser
21 A parser for WSDL definitions based on XML::Parser::Expat.
22 my $parser = SOAP::WSDL::Expat::WSDLParser->new();
24 my $wsdl = $parser->parse_file( $filename );
25 The WSDL parser creates a tree of perl objects, whose root is a
27 SOAP::WSDL::Definitions element.
28
30 SOAP::WSDL::Expat::MessageParser
31 SOAP::WSDL::Expat::MessageParser converts SOAP messages to
32 SOAP::WSDL::XSD object trees.
33 It uses a class resolvers for finding out which class a particular XML
35 element should be of, and type libs containing these classes.
36 Creating a class resolver
38 The easiest way for creating a class resolver is to run SOAP::WSDL's
40 generator.
41 See wsdl2perl.pl.
43 The class resolver must implement a class method "get_class", which is
45 passed a list ref of the current element's XPath (relative to Body),
46 split by /.
47 This method must return a class name appropriate for a XML element.
49 A class resolver package might look like this:
51 package ClassResolver;
53 my %class_list = (
55 'EnqueueMessage' => 'Typelib::TEnqueueMessage',
56 'EnqueueMessage/MMessage' => 'Typelib::TMessage',
57 'EnqueueMessage/MMessage/MRecipientURI' => 'SOAP::WSDL::XSD::Builtin::anyURI',
58 'EnqueueMessage/MMessage/MMessageContent' => 'SOAP::WSDL::XSD::Builtin::string',
59 );
60 sub new { return bless {}, 'ClassResolver' };
62 sub get_class {
64 my $name = join('/', @{ $_[1] });
65 return ($class_list{ $name }) ? $class_list{ $name }
66 : warn "no class found for $name";
67 };
68 1;
69 Skipping unwanted items
71 Sometimes there's unnecessary information transported in SOAP messages.
73 To skip XML nodes (including all child nodes), just edit the type map
75 for the message and set the type map entry to '__SKIP__'.
76 In the example above, EnqueueMessage/StuffIDontNeed and all child
78 elements are skipped.
79 my %class_list = (
81 'EnqueueMessage' => 'Typelib::TEnqueueMessage',
82 'EnqueueMessage/MMessage' => 'Typelib::TMessage',
83 'EnqueueMessage/MMessage/MRecipientURI' => 'SOAP::WSDL::XSD::Builtin::anyURI',
84 'EnqueueMessage/MMessage/MMessageContent' => 'SOAP::WSDL::XSD::Builtin::string',
85 'EnqueueMessage/StuffIDontNeed' => '__SKIP__',
86 'EnqueueMessage/StuffIDontNeed/Foo' => 'SOAP::WSDL::XSD::Builtin::string',
87 'EnqueueMessage/StuffIDontNeed/Bar' => 'SOAP::WSDL::XSD::Builtin::string',
88 );
89 Note that only SOAP::WSDL::Expat::MessageParser implements skipping
91 elements at the time of writing.
92 Creating type lib classes
94 Every element must have a correspondent one in the type library.
96 Builtin types should be resolved as SOAP::WSDL::XSD::Builtin::* classes
98 Creating a type lib is easy: Just run SOAP::WSDL's generator - it will
100 create both a typemap and the type lib classes for a WSDL file.
101 Sometimes it is nessecary to create type lib classes by hand - not all
103 WSDL definitions are complete.
104 For writing your own lib classes, see
106 SOAP::WSDL::XSD::Typelib::Element,
107 SOAP::WSDL::XSD::Typelib::ComplexType and
108 SOAP::WSDL::XSD::Typelib::SimpleType.
109 SOAP::WSDL::Expat::Message2Hash
111 Transforms a SOAP message into a perl hash refs. Using this parser is
112 usually triggered by calling the "outputhash" method of SOAP::WSDL, or
113 by using SOAP::WSDL::Deserializer::Hash.
114 Acts somewhat like XML::Simple, but faster.
116 The following restrictions apply:
118 • Ignores all namespaces
120 • Ignores all attributes
122 • Does not handle mixed content
124 • The SOAP header is ignored
126
128 Historically, SOAP::WSDL used SAX for parsing XML. The SAX handlers
129 were implemented as XML::LibXML handlers, which also worked with
130 XML::SAX::ParserFactory.
131 Support for SAX and XML::LibXML in SOAP::WSDL is discontinued for the
133 following reasons:
134 • Speed
136 XML::Parser::Expat is faster than XML::LibXML - at least when
138 optimized for speed.
139 High parsing speed is one of the key requirements for a SOAP
141 toolkit - if XML serializing and (more important) deserializing are
142 not fast enough, the whole toolkit is unusable.
143 • Availability
145 XML::Parser is more popular than XML::LibXML.
147 • Stability
149 XML::LibXML is based on the libxml2 library. Several versions of
151 libxml2 are known to have specific bugs. As a workaround, there are
152 often several versions of libxml2 installed on one system. This may
153 lead to problems on operating systems which cannot load more than
154 one version of a shared library simultaneously.
155 XML::LibXML is also still under development, while XML::Parser has
157 had time to stabilize.
158 • SOAP::Lite uses XML::Parser
160 SOAP::Lite uses XML::Parser if available. SOAP::WSDL should not
162 require users to install both XML::Parser and XML::LibXML.
163 The old SAX handler historically used in SOAP::WSDL are not included in
165 the SOAP::WSDL package any more.
166 However, they may be obtained from the "attic" directory in
168 SOAP::WSDL's SVN repository at
169 https://soap-wsdl.svn.sourceforge.net/svnroot/soap-wsdl/SOAP-WSDL/trunk/attic
171 • SOAP::WSDL::SAX::WSDLHandler
173 This is a SAX handler for parsing WSDL files into object trees
175 SOAP::WSDL works with.
176 It's built as a native handler for XML::LibXML, but will also work
178 with XML::SAX::ParserFactory.
179 To parse a WSDL file, use one of the following variants:
181 my $parser = XML::LibXML->new();
183 my $handler = SOAP::WSDL::SAX::WSDLHandler->new();
184 $parser->set_handler( $handler );
185 $parser->parse( $xml );
186 my $data = $handler->get_data();
187 my $handler = SOAP::WSDL::SAX::WSDLHandler->new({
189 base => 'XML::SAX::Base'
190 });
191 my $parser = XML::SAX::ParserFactor->parser(
192 Handler => $handler
193 );
194 $parser->parse( $xml );
195 my $data = $handler->get_data();
196 • SOAP::WSDL::SAX::MessageHandler
198 This is a SAX handler for parsing WSDL files into object trees
200 SOAP::WSDL works with.
201 It's built as a native handler for XML::LibXML, but will also work
203 with XML::SAX::ParserFactory.
204 Can be used for parsing both streams (chunks) and documents.
206
208 Copyright 2007 Martin Kutter.
209 This file is part of SOAP-WSDL. You may distribute/modify it under the
211 same terms as perl itself.
212
214 Martin Kutter <martin.kutter fen-net.de>
215
217 $Rev: 391 $
218 $LastChangedBy: kutterma $
219 $Id: Parser.pod 391 2007-11-17 21:56:13Z kutterma $
220 $HeadURL: https://soap-wsdl.svn.sourceforge.net/svnroot/soap-wsdl/SOAP-WSDL/trunk/lib/SOAP/WSDL/Manual/Parser.pod $
221perl v5.36.0 2023-01-20 SOAP::WSDL::Manual::Parser(3)