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

NAME

6       SOAP::WSDL - SOAP with WSDL support
7

NOTICE

9       This module is not recommended for new application development.  Please
10       use XML::Compile::SOAP or SOAP::Lite instead if possible.
11
12       This module has a large number of known bugs and is not being actively
13       developed.  This 3.0 release is intended to update the module to pass
14       tests on newer Perls.  This is a service to existing applications
15       already dependent on this module.
16

SYNOPSIS

18        my $soap = SOAP::WSDL->new(
19           wsdl => 'file://bla.wsdl',
20        );
21
22        my $result = $soap->call('MyMethod', %data);
23

DESCRIPTION

25       For creating Perl classes instrumenting a web service with a WSDL
26       definition, read SOAP::WSDL::Manual.
27
28       For using an interpreting (thus slow and somewhat troublesome) WSDL
29       based SOAP client, which mimics SOAP::Lite's API, read on.
30
31       Creating Interface classes is the recommended usage.
32
33       Did I say you should create interface classes following the steps in
34       SOAP::WSDL::Manual?
35
36       If you're migrating from earlier versions of SOAP::WSDL, you should
37       read the MIGRATING documentation.
38
39       The stuff below is for users of the 1.2x SOAP::WSDL series. All others,
40       please refer to SOAP::WSDL::Manual
41
42       SOAP::WSDL provides easy access to Web Services with WSDL descriptions.
43
44       The WSDL is parsed and stored in memory.
45
46       Your data is serialized according to the rules in the WSDL.
47
48       The only transport mechanisms currently supported are http and https.
49

METHODS

51   new
52       Constructor. All parameters passed are passed to the corresponding
53       methods.
54
55   call
56       Performs a SOAP call. The result is either an object tree (with
57       outputtree), a hash reference (with outputhash), plain XML (with
58       outputxml) or a SOAP::SOM object (with neither of the above set).
59
60       call() can be called in different ways:
61
62       ·   Old-style idiom
63
64            my $result = $soap->call('method', %data);
65
66           Does not support SOAP header data.
67
68       ·   New-style idiom
69
70            my $result = $soap->call('method', $body_ref, $header_ref );
71
72           Does support SOAP header data. $body_ref and $header ref may either
73           be hash refs or SOAP::WSDL::XSD::Typelib::* derived objects.
74
75           Result headers are accessible via the result SOAP::SOM object.
76
77           If outputtree or outputhash are set, you may also use the following
78           to access response header data:
79
80            my ($body, $header) = $soap->call('method', $body_ref, $header_ref );
81
82   wsdlinit
83       Reads the WSDL file and initializes SOAP::WSDL for working with it.
84
85       Is called automatically from call() if not called directly before.
86
87        servicename
88        portname
89        call
90
91       You may set servicename and portname by passing them as attributes to
92       wsdlinit:
93
94        $soap->wsdlinit(
95           servicename => 'MyService',
96           portname => 'MyPort',
97        );
98

CONFIGURATION METHODS

100   outputtree
101       When outputtree is set, SOAP::WSDL will return an object tree instead
102       of a SOAP::SOM object.
103
104       You have to specify a class_resolver for this to work. See
105       class_resolver
106
107   class_resolver
108       Set the class resolver class (or object).
109
110       Class resolvers must implement the method get_class which has to return
111       the name of the class name for deserializing a XML node at the current
112       XPath location.
113
114       Class resolvers are typically generated by using the generate_typemap
115       method of a SOAP::WSDL::Generator subclass.
116
117       Example:
118
119       XML structure (SOAP body content):
120
121        <Person>
122           <Name>Smith</Name>
123           <FirstName>John</FirstName>
124        </Person>
125
126       Class resolver
127
128        package MyResolver;
129        my %typemap = (
130           'Person' => 'MyPersonClass',
131           'Person/Name' => 'SOAP::WSDL::XSD::Typelib::Builtin::string',
132           'Person/FirstName' => 'SOAP::WSDL::XSD::Typelib::Builtin::string',
133        );
134
135        sub get_class { return $typemap{ $_[1] } };
136        1;
137
138       You'll need a MyPersonClass module in your search path for this to work
139       - see SOAP::WSDL::XSD::ComplexType on how to build / generate one.
140
141   servicename
142        $soap->servicename('Name');
143
144       Sets the service to operate on. If no service is set via servicename,
145       the first service found is used.
146
147       Returns the soap object, so you can chain calls like
148
149        $soap->servicename->('Name')->portname('Port');
150
151   portname
152        $soap->portname('Name');
153
154       Sets the port to operate on. If no port is set via portname, the first
155       port found is used.
156
157       Returns the soap object, so you can chain calls like
158
159        $soap->portname('Port')->call('MyMethod', %data);
160
161   no_dispatch
162       When set, call() returns the plain request XML instead of dispatching
163       the SOAP call to the SOAP service. Handy for testing/debugging.
164

ACCESS TO SOAP::WSDL's internals

166   get_client / set_client
167       Returns the SOAP client implementation used (normally a
168       SOAP::WSDL::Client object).
169

EXAMPLES

171       See the examples/ directory.
172

Differences to previous versions

174       ·   WSDL handling
175
176           SOAP::WSDL 2 is a complete rewrite. While SOAP::WSDL 1.x attempted
177           to process the WSDL file on the fly by using XPath queries,
178           SOAP:WSDL 2 uses a Expat handler for parsing the WSDL and building
179           up a object tree representing it's content.
180
181           The object tree has two main functions: It knows how to serialize
182           data passed as hash ref, and how to render the WSDL elements found
183           into perl classes.
184
185           Yup you're right; there's a builtin code generation facility. Read
186           SOAP::WSDL::Manual for using it.
187
188       ·   no_dispatch
189
190           call() with no_dispatch set to true now returns the complete SOAP
191           request envelope, not only the body's content.
192
193       ·   outputxml
194
195           call() with outputxml set to true now returns the complete SOAP
196           response envelope, not only the body's content.
197
198       ·   servicename/portname
199
200           Both servicename and portname can only be called after calling
201           wsdlinit().
202
203           You may pass the servicename and portname as attributes to
204           wsdlinit, though.
205

Differences to previous versions

207       The following functionality is no longer supported:
208
209   Operation overloading
210       The SOAP standard allows operation overloading - that is, you may
211       specify SOAP operations with more than one message. The client/server
212       than can choose which message to send. This SOAP feature is usually
213       used similar to the use of methods with different argument lists in
214       C++.
215
216       Operation overloading is no longer supported. The WS-I Basic profile
217       does not operation overloading. The same functionality as operation
218       overloading can be obtained by using a choice declaration in the XML
219       Schema.
220
221   readable
222       Readable has no effect any more. If you need readable debug output,
223       copy the SOAP message to your favorite XML editor and run the source
224       format command.  Outputting readable XML requires lots of programming
225       for little use: The resulting XMl is still quite unreadable.
226
227   on_action
228       Setting on_action is not required any more, the appropriate value is
229       automatically taken from the WSDL. on_action is a no-op, and is just
230       here for compatibility issues.
231

Differences to SOAP::Lite

233   readable
234       readable is a no-op in SOAP::WSDL. Actually, the XML output from
235       SOAP::Lite is hardly readable, either with readable switched on.
236
237       If you need readable XML messages, I suggest using your favorite XML
238       editor for displaying and formatting.
239
240   Message style/encoding
241       While SOAP::Lite supports rpc/encoded style/encoding only, SOAP::WSDL
242       currently supports document/literal style/encoding.
243
244   autotype / type information
245       SOAP::Lite defaults to transmitting XML type information by default,
246       where SOAP::WSDL defaults to leaving it out.
247
248       autotype(1) might even be broken in SOAP::WSDL - it's not well-tested,
249       yet.
250
251   Output formats
252       In contrast to SOAP::Lite, SOAP::WSDL supports the following output
253       formats:
254
255       ·   SOAP::SOM objects.
256
257           This is the default. SOAP::Lite is required for outputting
258           SOAP::SOM objects.
259
260       ·   Object trees.
261
262           This is the recommended output format.  You need a class resolver
263           (typemap) for outputting object trees.  See class_resolver above.
264
265       ·   Hash refs
266
267           This is for convenience: A single hash ref containing the content
268           of the SOAP body.
269
270       ·   xml
271
272           See below.
273
274   outputxml
275       SOAP::Lite returns only the content of the SOAP body when outputxml is
276       set to true. SOAP::WSDL returns the complete XML response.
277
278   Auto-Dispatching
279       SOAP::WSDL does does not support auto-dispatching.
280
281       This is on purpose: You may easily create interface classes by using
282       SOAP::WSDL::Client and implementing something like
283
284        sub mySoapMethod {
285            my $self = shift;
286            $soap_wsdl_client->call( mySoapMethod, @_);
287        }
288
289       You may even do this in a class factory - see wsdl2perl.pl for creating
290       such interfaces.
291
292   Debugging / Tracing
293       While SOAP::Lite features a global tracing facility, SOAP::WSDL allows
294       one to switch tracing on/of on a per-object base.
295
296       This has to be done in the SOAP client used by SOAP::WSDL - see
297       get_client for an example and SOAP::WSDL::Client for details.
298

BUGS AND LIMITATIONS

300       The bug tracker is at
301       <https://rt.cpan.org/Dist/Display.html?Queue=SOAP-WSDL>.
302
303       This module is in legacy maintenance mode.  Only show stopper bugs are
304       being fixed, until/unless someone wishes to resume active development
305       on it.  Scott Walters, "scott@slowass.net" has obtained co-mainter from
306       the CPAN admins for the purpose of applying existing fixes people have
307       submit to the RT tracker, and to apply other fixes as needed to get the
308       module to install and run on newer Perls.  Non show-stopper bugs
309       reports without fixes will be added to this list of limitations.  Of
310       course, fixes for these and other bugs are welcome.  Scott does not get
311       email from rt.cpan.org, so please drop an email to him at
312       "scott@slowass.net" if you open a ticket there.
313
314       ·   Breaks the idiom "$package->can("SUPER::method")" in your code
315
316           If you redefine "UNIVERSAL::can()", and someone tries to do
317           "$package->can("SUPER::method")", it'll look at your packages @ISA,
318           not theirs.  This module does precicely that, by way of its
319           dependency on "Class::Std::Fast".
320
321       ·   $obj == undef does not work in perl 5.8.6 and perl 5.8.7
322
323           Due to some strange behaviour in perl 5.8.6 and perl 5.8.7,
324           stringification overloading is not triggered during comparison with
325           undef.
326
327           While this is probably harmless in most cases, it's important to
328           know that you need to do
329
330            defined( $obj->get_value() )
331
332           to check for undef values in simpleType objects.
333
334       ·   perl 5.8.0 or higher required
335
336           SOAP::WSDL needs perl 5.8.0 or higher. This is due to a bug in
337           perls before - see
338           http://aspn.activestate.com/ASPN/Mail/Message/perl5-porters/929746
339           for details.
340
341       ·   Apache SOAP datatypes are not supported
342
343           You can't use SOAP::WSDL with Apache SOAP datatypes like map.
344
345       ·   Incomplete XML Schema definitions support
346
347           This section describes the limitations of SOAP::WSDL, that is the
348           interpreting SOAP client. For limitations of wsdl2perl.pl generated
349           SOAP clients, see SOAP::WSDL::Manual::XSD.
350
351           XML Schema attribute definitions are not supported in interpreting
352           mode.
353
354           The following XML Schema definitions varieties are not supported in
355           interpreting mod:
356
357            group
358            simpleContent
359
360           The following XML Schema definition content model is only partially
361           supported in interpreting mode:
362
363            complexContent - only restriction variety supported
364
365           See SOAP::WSDL::Manual::XSD for details.
366
367       ·   Serialization of hash refs does not work for ambiguous values
368
369           If you have list elements with multiple occurrences allowed,
370           SOAP::WSDL has no means of finding out which variant you meant.
371
372           Passing in item => [1,2,3] could serialize to
373
374            <item>1 2</item><item>3</item>
375            <item>1</item><item>2 3</item>
376
377           Ambiguous data can be avoided by providing data as objects.
378
379       ·   XML Schema facets
380
381           Almost no XML schema facets are implemented. The only facets
382           currently implemented are:
383
384            fixed
385            default
386
387           The following facets have no influence:
388
389            minLength
390            maxLength
391            minInclusive
392            maxInclusive
393            minExclusive
394            maxExclusive
395            pattern
396            enumeration
397

SEE ALSO

399   Related projects
400       ·   SOAP::Lite
401
402           Full featured SOAP-library, little WSDL support. Supports rpc-
403           encoded style only. Many protocols supported.
404
405       ·   XML::Compile::SOAP
406
407           Creates parser/generator functions for SOAP messages. Includes SOAP
408           Client and Server implementations. Can validate XML messages.
409
410           You might want to give it a try, especially if you need to adhere
411           very closely to the XML Schema / WSDL specs.
412
413   Sources of documentation
414       ·   SOAP::WSDL homepage at sourceforge.net
415
416           <http://soap-wsdl.sourceforge.net>
417
418       ·   SOAP::WSDL forum at CPAN::Forum
419
420           <http://www.cpanforum.com/dist/SOAP-WSDL>
421

ACKNOWLEDGMENTS

423       Scott Walters wrote:
424
425       This code incorporates fixes contributed by "NORDIC@cpan.org",
426       "dam@cpan.org", "sven.schober@uni-ulm.de", myself, and others.
427
428       Martin Kutter wrote:
429
430       There are many people out there who fostered SOAP::WSDL's development.
431       I would like to thank them all (and apologize to all those I have
432       forgotten).
433
434       Giovanni S. Fois wrote a improved version of SOAP::WSDL (which
435       eventually became v1.23)
436
437       David Bussenschutt, Damian A. Martinez Gelabert, Dennis S. Hennen, Dan
438       Horne, Peter Orvos, Mark Overmeer, Jon Robens, Isidro Vila Verde and
439       Glenn Wood (in alphabetical order) spotted bugs and/or suggested
440       improvements in the 1.2x releases.
441
442       JT Justman and Noah Robin provided early feedback and bug reports for
443       the 2.xx pre-releases.
444
445       Adam Kennedy checked and suggested improvements on metadata and
446       dependencies in the 2.xx pre-releases.
447
448       Andreas 'ac0v' Specht constantly asked for better performance.
449
450       Matt S. Trout encouraged me "to get a non-dev-release out."
451
452       CPAN Testers provided most valuable (automated) feedback. Thanks a lot.
453
454       Numerous people sent me their real-world WSDL files and error reports
455       for testing. Thank you.
456
457       Noah Robin contributed lots of documentation fixes, and the mod_perl
458       server, and eventually joined SOAP::WSDL's development. Thanks.
459
460       Mark Overmeer wrote XML::Compile::SOAP - competition is good for
461       business.
462
463       Paul Kulchenko and Byrne Reese wrote and maintained SOAP::Lite and thus
464       provided a base (and counterpart) for SOAP::WSDL.
465
467       Copyright 2004-2008 Martin Kutter.
468
469       This file is part of SOAP-WSDL. You may distribute/modify it under the
470       same terms as perl itself
471

AUTHOR

473       Scott Walters <scott@slowass.net<gt> 2014
474
475       Martin Kutter <martin.kutter fen-net.de> 2004-2008
476

REPOSITORY INFORMATION

478           https://github.com/scrottie/SOAP-WSDL
479
480
481
482perl v5.28.0                      2018-07-15                     SOAP::WSDL(3)
Impressum