1SOAP::WSDL::Manual(3) User Contributed Perl DocumentationSOAP::WSDL::Manual(3)
2
6 SOAP::WSDL::Manual - Accessing WSDL based web services
7
9 Quick walk-through for the unpatient
10 • Create WSDL bindings
11 perl wsdl2perl.pl -b base_dir URL
13 • Look what has been generated
15 Check the results of the generator. There should be one
17 MyInterfaces/SERVICE_NAME/PORT_NAME.pm file per port (and one
18 directory per service).
19 • Write script
21 use MyInterfaces::SERVICE_NAME::PORT_NAME;
23 my $service = MyInterfaces::SERVICE_NAME::PORT_NAME->new();
24 my $result = $service->SERVICE_METHOD();
26 die $result if not $result;
27 print $result;
29 "perldoc MyInterfaces::SERVICE_NAME::PORT_NAME" should give you
31 some overview about the service's interface structure.
32 The results of all calls to your service object's methods (except
34 new) are objects based on SOAP::WSDL's XML schema implementation.
35 To access the object's properties use get_NAME / set_NAME
37 getter/setter methods with NAME corresponding to the XML tag name /
38 the hash structure as showed in the generated pod.
39 • Run script
41 Instrumenting web services with interface classes
43 SOAP::WSDL (starting from 2.00) instruments WSDL based web services
44 with interface classes. This means that SOAP::WSDL features a code
45 generator which creates one class for every web service you want to
46 access.
47 Moreover, the data types from the WSDL definitions are also wrapped
49 into classes and returned to the user as objects.
50 To find out which class a particular XML node should be, SOAP::WSDL
52 uses typemaps. For every Web service, there's also a typemap created.
53 Interface class creation
55 To create interface classes, follow the steps above.
56 If this works fine for you, skip the next paragraphs. If not, read on.
58 The steps to instrument a web service with SOAP::WSDL perl bindings (in
60 detail) are as follows:
61 • Gather web service information
63 You'll need to know at least a URL pointing to the web service's
65 WSDL definition.
66 If you already know more - like which methods the service provides,
68 or how the XML messages look like, that's fine. All these things
69 will help you later.
70 • Create WSDL bindings
72 perl wsdl2perl.pl -b base_dir URL
74 This will generate the perl bindings in the directory specified by
76 base_dir.
77 For more options, see wsdl2perl.pl - you may want to specify class
79 prefixes for XML type and element classes, type maps and interface
80 classes, and you may even want to add custom typemap elements.
81 • Check the result
83 There should be a bunch of classes for types (in the MyTypes::
85 namespace by default), elements (in MyElements::), and at least one
86 typemap (in MyTypemaps::) and one or more interface classes (in
87 MyInterfaces::).
88 If you don't already know the details of the web service you're
90 going to instrument, it's now time to read the perldoc of the
91 generated interface classes. It will tell you what methods each
92 service provides, and which parameters they take.
93 If the WSDL definition is informative about what these methods do,
95 the included perldoc will be, too - if not, blame the web service
96 author.
97 • Write a perl script (or module) accessing the web service.
99 use MyInterfaces::SERVICE_NAME::PORT_NAME;
101 my $service = MyInterfaces::SERVICE_NAME::PORT_NAME->new();
102 my $result = $service->SERVICE_METHOD();
104 die $result if not $result;
105 print $result;
106 The above handling of errors ("die $result if not $result") may
108 look a bit strange - it is due to the nature of the
109 SOAP::WSDL::SOAP::Typelib::Fault11 objects SOAP::WSDL uses for
110 signalling failure.
111 These objects are false in boolean context, but serialize to their
113 XML structure on stringification.
114 You may, of course, access individual fault properties, too. To get
116 a list of fault properties, see SOAP::WSDL::SOAP::Typelib::Fault11
117 Adding missing information
119 Sometimes, WSDL definitions are incomplete. In most of these cases,
120 proper fault definitions are missing. This means that though the
121 specification says nothing about it, Fault messages include extra
122 elements in the <detail> section, or errors are even indicated by non-
123 fault messages.
124 There are two steps you need to perform for adding additional
126 information.
127 • Provide required type classes
129 For each extra data type used in the XML messages, a type class has
131 to be created.
132 It is strongly discouraged to use the same namespace for hand-
134 written and generated classes - while generated classes may be
135 many, you probably will only implement a few by hand. These
136 (precious) few classes may get lost in the mass of (cheap)
137 generated ones. Just imagine one of your co-workers (or even
138 yourself) deleting the whole bunch and re-generating everything -
139 oops - almost everything. You get the point.
140 For simplicity, you probably just want to use builtin types
142 wherever possible - you are probably not interested in whether a
143 fault detail's error code is presented to you as a simpleType
144 ranging from 1 to 10 (which you have to write) or as an int (which
145 is a builtin type ready to use).
146 Using builtin types for simpleType definitions may greatly reduce
148 the number of additional classes you need to implement.
149 If the extra type classes you need include <complexType > or
151 <element /> definitions, see SOAP::WSDL::SOAP::Typelib::ComplexType
152 and SOAP::WSDL::SOAP::Typelib::Element on how to create ComplexType
153 and Element type classes.
154 • Provide a typemap snippet to wsdl2perl.pl
156 SOAP::WSDL uses typemaps for finding out into which class' object a
158 XML node should be transformed.
159 Typemaps basically map the path of every XML element inside the
161 Body tag to a perl class.
162 Typemap snippets have to look like this (which is actually the
164 default Fault typemap included in every generated one):
165 (
167 'Fault' => 'SOAP::WSDL::SOAP::Typelib::Fault11',
168 'Fault/faultcode' => 'SOAP::WSDL::XSD::Typelib::Builtin::anyURI',
169 'Fault/faultactor' => 'SOAP::WSDL::XSD::Typelib::Builtin::anyURI',
170 'Fault/faultstring' => 'SOAP::WSDL::XSD::Typelib::Builtin::string',
171 'Fault/detail' => 'SOAP::WSDL::XSD::Typelib::Builtin::anyType',
172 );
173 The lines are hash key - value pairs. The keys are the XPath
175 expressions without occurrence numbers (like [1]) relative to the
176 Body element. Namespaces are ignored.
177 If you don't know about XPath: They are just the names of the XML
179 tags, starting from the one inside <Body> up to the current one
180 joined by /.
181 One line for every XML node is required.
183 You may use all builtin, generated or custom type class names as
185 values.
186 Use wsdl2perl.pl -mi=FILE to include custom typemap snippets.
188 Note that typemap include files for wsdl2perl.pl must evaluate to a
190 valid perl hash - it will be imported via eval (OK, to be honest:
191 via do $file, but that's almost the same...).
192 Your extra statements are included last, so they override potential
194 typemap statements with the same keys.
195
197 Accessing a web service without a WSDL definition is more cumbersome.
198 There are two ways to go:
199 • Write a WSDL definition and generate interface
201 This is the way to go if you already are experienced in writing
203 WSDL files. If you are not, be warned: Writing a correct WSDL is
204 not an easy task, and writing correct WSDL files with only a text
205 editor is almost impossible. You should definitely use a WSDL
206 editor. The WSDL editor should support conformance checks for the
207 WS-I Basic Profile (1.0 is preferred by SOAP::WSDL)
208 • Write a typemap and class library from scratch
210 If the web service is relatively simple, this is probably easier
212 than first writing a WSDL definition. Besides, it can be done in
213 perl, a language you are probably more familiar with than WSDL.
214 SOAP::WSDL::XSD::Typelib::ComplexType,
216 SOAP::WSDL::XSD::Typelib::SimpleType and
217 SOAP::WSDL::XSD::Typelib::Element tell you how to create subclasses
218 of XML schema types.
219 SOAP::WSDL::Manual::Parser will tell you how to create a typemap
221 class.
222
224 Creating a SOAP server works just like creating a client - just add the
225 "--server" or "-s" option to the call to "wsdl2perl.pl".
226 perl wsdl2perl.pl -s -b BASE_DIR URL
228 SOAP::WSDL currently includes classes for building a basic CGI and a
230 mod_perl 2 based SOAP server.
231
233 SOAP::WSDL::Manual::Cookbook cooking recipes for accessing web
234 services, altering the XML Serializer and others.
235 SOAP::WSDL::Manual::XSD SOAP::WSDL's XML Schema implementation
237 SOAP::WSDL::Manual::Glossary The meaning of all these words
239 SOAP::WSDL::Client Basic client for SOAP::WSDL based interfaces
241 SOAP::WSDL an interpreting WSDL based SOAP client
243
245 Copyright 2007 Martin Kutter.
246 This file is part of SOAP-WSDL. You may distribute/modify it under the
248 same terms as perl itself
249
251 Martin Kutter <martin.kutter fen-net.de>
252perl v5.38.0 2023-07-21 SOAP::WSDL::Manual(3)