1SOAP::WSDL::Manual(3) User Contributed Perl DocumentationSOAP::WSDL::Manual(3)
2
3
4

NAME

6       SOAP::WSDL::Manual - Accessing WSDL based web services
7

Accessing a WSDL-based web service

9   Quick walk-through for the unpatient
10       ·   Create WSDL bindings
11
12             perl wsdl2perl.pl -b base_dir URL
13
14       ·   Look what has been generated
15
16           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
20       ·   Write script
21
22            use MyInterfaces::SERVICE_NAME::PORT_NAME;
23            my $service = MyInterfaces::SERVICE_NAME::PORT_NAME->new();
24
25            my $result = $service->SERVICE_METHOD();
26            die $result if not $result;
27
28            print $result;
29
30           "perldoc MyInterfaces::SERVICE_NAME::PORT_NAME" should give you
31           some overview about the service's interface structure.
32
33           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
36           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
40       ·   Run script
41
42   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
48       Moreover, the data types from the WSDL definitions are also wrapped
49       into classes and returned to the user as objects.
50
51       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
54   Interface class creation
55       To create interface classes, follow the steps above.
56
57       If this works fine for you, skip the next paragraphs. If not, read on.
58
59       The steps to instrument a web service with SOAP::WSDL perl bindings (in
60       detail) are as follows:
61
62       ·   Gather web service information
63
64           You'll need to know at least a URL pointing to the web service's
65           WSDL definition.
66
67           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
71       ·   Create WSDL bindings
72
73            perl wsdl2perl.pl -b base_dir URL
74
75           This will generate the perl bindings in the directory specified by
76           base_dir.
77
78           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
82       ·   Check the result
83
84           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
89           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
94           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
98       ·   Write a perl script (or module) accessing the web service.
99
100            use MyInterfaces::SERVICE_NAME::PORT_NAME;
101            my $service = MyInterfaces::SERVICE_NAME::PORT_NAME->new();
102
103            my $result = $service->SERVICE_METHOD();
104            die $result if not $result;
105            print $result;
106
107           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
112           These objects are false in boolean context, but serialize to their
113           XML structure on stringification.
114
115           You may, of course, access individual fault properties, too. To get
116           a list of fault properties, see SOAP::WSDL::SOAP::Typelib::Fault11
117
118   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
125       There are two steps you need to perform for adding additional
126       information.
127
128       ·   Provide required type classes
129
130           For each extra data type used in the XML messages, a type class has
131           to be created.
132
133           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
141           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
147           Using builtin types for simpleType definitions may greatly reduce
148           the number of additional classes you need to implement.
149
150           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
155       ·   Provide a typemap snippet to wsdl2perl.pl
156
157           SOAP::WSDL uses typemaps for finding out into which class' object a
158           XML node should be transformed.
159
160           Typemaps basically map the path of every XML element inside the
161           Body tag to a perl class.
162
163           Typemap snippets have to look like this (which is actually the
164           default Fault typemap included in every generated one):
165
166            (
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
174           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
178           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
182           One line for every XML node is required.
183
184           You may use all builtin, generated or custom type class names as
185           values.
186
187           Use wsdl2perl.pl -mi=FILE to include custom typemap snippets.
188
189           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
193           Your extra statements are included last, so they override potential
194           typemap statements with the same keys.
195

Accessing a web service without a WSDL definition

197       Accessing a web service without a WSDL definition is more cumbersome.
198       There are two ways to go:
199
200       ·   Write a WSDL definition and generate interface
201
202           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
209       ·   Write a typemap and class library from scratch
210
211           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
215           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
220           SOAP::WSDL::Manual::Parser will tell you how to create a typemap
221           class.
222

Creating a SOAP Server

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
227        perl wsdl2perl.pl -s -b BASE_DIR URL
228
229       SOAP::WSDL currently includes classes for building a basic CGI and a
230       mod_perl 2 based SOAP server.
231

SEE ALSO

233       SOAP::WSDL::Manual::Cookbook cooking recipes for accessing web
234       services, altering the XML Serializer and others.
235
236       SOAP::WSDL::Manual::XSD SOAP::WSDL's XML Schema implementation
237
238       SOAP::WSDL::Manual::Glossary The meaning of all these words
239
240       SOAP::WSDL::Client Basic client for SOAP::WSDL based interfaces
241
242       SOAP::WSDL an interpreting WSDL based SOAP client
243
245       Copyright 2007 Martin Kutter.
246
247       This file is part of SOAP-WSDL. You may distribute/modify it under the
248       same terms as perl itself
249

AUTHOR

251       Martin Kutter <martin.kutter fen-net.de>
252
253
254
255perl v5.32.0                      2020-07-28             SOAP::WSDL::Manual(3)
Impressum