1SOAP::WSDL::Manual::ParUsseerr(3C)ontributed Perl DocumeSnOtAaPt:i:oWnSDL::Manual::Parser(3)
2
3
4

NAME

6       SOAP::WSDL::Manual::Parser - How SOAP::WSDL parses XML messages
7

Which XML message does SOAP::WSDL parse ?

9       Naturally, there are two kinds of XML documents (or messages)
10       SOAP::WSDL has to parse:
11
12       •   WSDL definitions
13
14       •   SOAP messages
15
16       There are different parser implementations available for SOAP messages
17       and WSDL definitions.
18

WSDL definitions parser

20   SOAP::WSDL::Expat::WSDLParser
21       A parser for WSDL definitions based on XML::Parser::Expat.
22
23        my $parser = SOAP::WSDL::Expat::WSDLParser->new();
24        my $wsdl = $parser->parse_file( $filename );
25
26       The WSDL parser creates a tree of perl objects, whose root is a
27       SOAP::WSDL::Definitions element.
28

SOAP messages parser

30   SOAP::WSDL::Expat::MessageParser
31       SOAP::WSDL::Expat::MessageParser converts SOAP messages to
32       SOAP::WSDL::XSD object trees.
33
34       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
37       Creating a class resolver
38
39       The easiest way for creating a class resolver is to run SOAP::WSDL's
40       generator.
41
42       See wsdl2perl.pl.
43
44       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
48       This method must return a class name appropriate for a XML element.
49
50       A class resolver package might look like this:
51
52        package ClassResolver;
53
54        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
61        sub new { return bless {}, 'ClassResolver' };
62
63        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
70       Skipping unwanted items
71
72       Sometimes there's unnecessary information transported in SOAP messages.
73
74       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
77       In the example above, EnqueueMessage/StuffIDontNeed and all child
78       elements are skipped.
79
80        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
90       Note that only SOAP::WSDL::Expat::MessageParser implements skipping
91       elements at the time of writing.
92
93       Creating type lib classes
94
95       Every element must have a correspondent one in the type library.
96
97       Builtin types should be resolved as SOAP::WSDL::XSD::Builtin::* classes
98
99       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
102       Sometimes it is nessecary to create type lib classes by hand - not all
103       WSDL definitions are complete.
104
105       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
110   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
115       Acts somewhat like XML::Simple, but faster.
116
117       The following restrictions apply:
118
119       •   Ignores all namespaces
120
121       •   Ignores all attributes
122
123       •   Does not handle mixed content
124
125       •   The SOAP header is ignored
126

OLD SAX HANDLER

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
132       Support for SAX and XML::LibXML in SOAP::WSDL is discontinued for the
133       following reasons:
134
135       •   Speed
136
137           XML::Parser::Expat is faster than XML::LibXML - at least when
138           optimized for speed.
139
140           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
144       •   Availability
145
146           XML::Parser is more popular than XML::LibXML.
147
148       •   Stability
149
150           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
156           XML::LibXML is also still under development, while XML::Parser has
157           had time to stabilize.
158
159       •   SOAP::Lite uses XML::Parser
160
161           SOAP::Lite uses XML::Parser if available.  SOAP::WSDL should not
162           require users to install both XML::Parser and XML::LibXML.
163
164       The old SAX handler historically used in SOAP::WSDL are not included in
165       the SOAP::WSDL package any more.
166
167       However, they may be obtained from the "attic" directory in
168       SOAP::WSDL's SVN repository at
169
170       https://soap-wsdl.svn.sourceforge.net/svnroot/soap-wsdl/SOAP-WSDL/trunk/attic
171
172       •   SOAP::WSDL::SAX::WSDLHandler
173
174           This is a SAX handler for parsing WSDL files into object trees
175           SOAP::WSDL works with.
176
177           It's built as a native handler for XML::LibXML, but will also work
178           with XML::SAX::ParserFactory.
179
180           To parse a WSDL file, use one of the following variants:
181
182            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
188            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
197       •   SOAP::WSDL::SAX::MessageHandler
198
199           This is a SAX handler for parsing WSDL files into object trees
200           SOAP::WSDL works with.
201
202           It's built as a native handler for XML::LibXML, but will also work
203           with XML::SAX::ParserFactory.
204
205           Can be used for parsing both streams (chunks) and documents.
206
208       Copyright 2007 Martin Kutter.
209
210       This file is part of SOAP-WSDL. You may distribute/modify it under the
211       same terms as perl itself.
212

AUTHOR

214       Martin Kutter <martin.kutter fen-net.de>
215

REPOSITORY INFORMATION

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 $
221
222
223
224perl v5.36.0                      2023-01-20     SOAP::WSDL::Manual::Parser(3)
Impressum