1SOAP::Lite(3) User Contributed Perl Documentation SOAP::Lite(3)
2
3
4
6 SOAP::Lite - Perl's Web Services Toolkit
7
9 SOAP::Lite is a collection of Perl modules which provides a simple and
10 lightweight interface to the Simple Object Access Protocol (SOAP) both
11 on client and server side.
12
14 As of version SOAP::Lite version 1.05, no perl versions before 5.8 will
15 be supported.
16
17 SOAP::Lite 0.71 will be the last version of SOAP::Lite running on perl
18 5.005
19
20 Future versions of SOAP::Lite will require at least perl 5.6.0
21
22 If you have not had the time to upgrade your perl, you should consider
23 this now.
24
26 lib/SOAP/Lite.pm
27 SOAP::Lite - Main class provides all logic
28
29 SOAP::Transport - Transport backend
30
31 SOAP::Data - Data objects
32
33 SOAP::Header - Header Data Objects
34
35 SOAP::Serializer - Serializes data structures to SOAP messages
36
37 SOAP::Deserializer - Deserializes SOAP messages into SOAP::SOM
38 objects
39
40 SOAP::SOM - SOAP Message objects
41
42 SOAP::Constants - Provides access to common constants and defaults
43
44 SOAP::Trace - Tracing facilities
45
46 SOAP::Schema - Provides access and stub(s) for schema(s)
47
48 SOAP::Schema::WSDL - WSDL implementation for SOAP::Schema
49
50 SOAP::Server - Handles requests on server side
51
52 SOAP::Server::Object - Handles objects-by-reference
53
54 SOAP::Fault - Provides support for Faults on server side
55
56 SOAP::Utils - A set of private and public utility subroutines
57
58 lib/SOAP/Packager.pm
59 SOAP::Packager - Provides an abstract class for implementing custom
60 packagers.
61
62 SOAP::Packager::MIME - Provides MIME support to SOAP::Lite
63
64 SOAP::Packager::DIME - Provides DIME support to SOAP::Lite
65
66 lib/SOAP/Transport/HTTP.pm
67 SOAP::Transport::HTTP::Client - Client interface to HTTP transport
68
69 SOAP::Transport::HTTP::Server - Server interface to HTTP transport
70
71 SOAP::Transport::HTTP::CGI - CGI implementation of server interface
72
73 SOAP::Transport::HTTP::Daemon - Daemon implementation of server
74 interface
75
76 SOAP::Transport::HTTP::Apache - mod_perl implementation of server
77 interface
78
79 lib/SOAP/Transport/POP3.pm
80 SOAP::Transport::POP3::Server - Server interface to POP3 protocol
81
82 lib/SOAP/Transport/MAILTO.pm
83 SOAP::Transport::MAILTO::Client - Client interface to SMTP/sendmail
84
85 lib/SOAP/Transport/LOCAL.pm
86 SOAP::Transport::LOCAL::Client - Client interface to local
87 transport
88
89 lib/SOAP/Transport/TCP.pm
90 SOAP::Transport::TCP::Server - Server interface to TCP protocol
91
92 SOAP::Transport::TCP::Client - Client interface to TCP protocol
93
94 lib/SOAP/Transport/IO.pm
95 SOAP::Transport::IO::Server - Server interface to IO transport
96
98 All accessor methods return the current value when called with no
99 arguments, while returning the object reference itself when called with
100 a new value. This allows the set-attribute calls to be chained
101 together.
102
103 new(optional key/value pairs)
104 $client = SOAP::Lite->new(proxy => $endpoint)
105
106 Constructor. Many of the accessor methods defined here may be
107 initialized at creation by providing their name as a key, followed
108 by the desired value. The example provides the value for the proxy
109 element of the client.
110
111 transport(optional transport object)
112 $transp = $client->transport( );
113
114 Gets or sets the transport object used for sending/receiving SOAP
115 messages.
116
117 See SOAP::Transport for details.
118
119 serializer(optional serializer object)
120 $serial = $client->serializer( )
121
122 Gets or sets the serializer object used for creating XML messages.
123
124 See SOAP::Serializer for details.
125
126 packager(optional packager object)
127 $packager = $client->packager( )
128
129 Provides access to the "SOAP::Packager" object that the client uses
130 to manage the use of attachments. The default packager is a MIME
131 packager, but unless you specify parts to send, no MIME formatting
132 will be done.
133
134 See also: SOAP::Packager.
135
136 proxy(endpoint, optional extra arguments)
137 $client->proxy('http://soap.xml.info/ endPoint');
138
139 The proxy is the server or endpoint to which the client is going to
140 connect. This method allows the setting of the endpoint, along
141 with any extra information that the transport object may need when
142 communicating the request.
143
144 This method is actually an alias to the proxy method of
145 SOAP::Transport. It is the same as typing:
146
147 $client->transport( )->proxy(...arguments);
148
149 Extra parameters can be passed to proxy() - see below.
150
151 compress_threshold
152 See COMPRESSION in HTTP::Transport.
153
154 All initialization options from the underlying transport layer
155 The options for HTTP(S) are the same as for LWP::UserAgent's
156 new() method.
157
158 A common option is to create a instance of HTTP::Cookies and
159 pass it as cookie_jar option:
160
161 my $cookie_jar = HTTP::Cookies->new()
162 $client->proxy('http://www.example.org/webservice',
163 cookie_jar => $cookie_jar,
164 );
165
166 For example, if you wish to set the HTTP timeout for a SOAP::Lite
167 client to 5 seconds, use the following code:
168
169 my $soap = SOAP::Lite
170 ->uri($uri)
171 ->proxy($proxyUrl, timeout => 5 );
172
173 See LWP::UserAgent.
174
175 endpoint(optional new endpoint address)
176 $client->endpoint('http://soap.xml.info/ newPoint')
177
178 It may be preferable to set a new endpoint without the additional
179 work of examining the new address for protocol information and
180 checking to ensure the support code is loaded and available. This
181 method allows the caller to change the endpoint that the client is
182 currently set to connect to, without reloading the relevant
183 transport code. Note that the proxy method must have been called
184 before this method is used.
185
186 service(service URL)
187 $client->service('http://svc.perl.org/Svc.wsdl');
188
189 "SOAP::Lite" offers some support for creating method stubs from
190 service descriptions. At present, only WSDL support is in place.
191 This method loads the specified WSDL schema and uses it as the
192 basis for generating stubs.
193
194 outputxml(boolean)
195 $client->outputxml('true');
196
197 When set to a true value, the raw XML is returned by the call to a
198 remote method.
199
200 The default is to return a SOAP::SOM object (false).
201
202 autotype(boolean)
203 $client->autotype(0);
204
205 This method is a shortcut for:
206
207 $client->serializer->autotype(boolean);
208
209 By default, the serializer tries to automatically deduce types for
210 the data being sent in a message. Setting a false value with this
211 method disables the behavior.
212
213 readable(boolean)
214 $client->readable(1);
215
216 This method is a shortcut for:
217
218 $client->serializer->readable(boolean);
219
220 When this is used to set a true value for this property, the
221 generated XML sent to the endpoint has extra characters (spaces and
222 new lines) added in to make the XML itself more readable to human
223 eyes (presumably for debugging). The default is to not send any
224 additional characters.
225
226 headerattr(hash reference of attributes)
227 $obj->headerattr({ attr1 => 'value' });
228
229 Allows for the setting of arbitrary attributes on the header
230 object. Keep in mind the requirement that
231 any attributes not natively known to SOAP must be namespace-
232 qualified. If using $session->call ($method, $callData,
233 $callHeader), SOAP::Lite serializes information as
234
235 <soap:Envelope>
236 <soap:Header>
237 <userId>xxxxx</userId>
238 <password>yyyyy</password>
239 </soap:Header>
240 <soap:Body>
241 <myMethod xmlns="http://www.someuri.com">
242 <foo />
243 </myMethod>
244 </soap:Body>
245 </soap:Envelope>
246
247 The attributes, given to headerattr are placed into the Header as
248
249 <soap:Header attr1="value">
250
251 bodyattr(hash reference of attributes)
252 $obj->bodyattr({ attr1 => 'value' });
253
254 Allows for the setting of arbitrary attributes on the body object.
255 Keep in mind the requirement that
256 any attributes not natively known to SOAP must be namespace-
257 qualified. See headerattr
258
259 default_ns($uri)
260 Sets the default namespace for the request to the specified uri.
261 This overrides any previous namespace declaration that may have
262 been set using a previous call to "ns()" or "default_ns()". Setting
263 the default namespace causes elements to be serialized without a
264 namespace prefix, like this:
265
266 <soap:Envelope>
267 <soap:Body>
268 <myMethod xmlns="http://www.someuri.com">
269 <foo />
270 </myMethod>
271 </soap:Body>
272 </soap:Envelope>
273
274 Some .NET web services have been reported to require this XML
275 namespace idiom.
276
277 ns($uri,$prefix=undef)
278 Sets the namespace uri and optionally the namespace prefix for the
279 request to the specified values. This overrides any previous
280 namespace declaration that may have been set using a previous call
281 to "ns()" or "default_ns()".
282
283 If a prefix is not specified, one will be generated for you
284 automatically. Setting the namespace causes elements to be
285 serialized with a declared namespace prefix, like this:
286
287 <soap:Envelope>
288 <soap:Body>
289 <my:myMethod xmlns:my="http://www.someuri.com">
290 <my:foo />
291 </my:myMethod>
292 </soap:Body>
293 </soap:Envelope>
294
295 use_prefix(boolean)
296 Deprecated. Use the "ns()" and "default_ns" methods described
297 above.
298
299 Shortcut for "serializer->use_prefix()". This lets you turn on/off
300 the use of a namespace prefix for the children of the
301 /Envelope/Body element. Default is 'true'.
302
303 When use_prefix is set to 'true', serialized XML will look like
304 this:
305
306 <SOAP-ENV:Envelope ...attributes skipped>
307 <SOAP-ENV:Body>
308 <namesp1:mymethod xmlns:namesp1="urn:MyURI" />
309 </SOAP-ENV:Body>
310 </SOAP-ENV:Envelope>
311
312 When use_prefix is set to 'false', serialized XML will look like
313 this:
314
315 <SOAP-ENV:Envelope ...attributes skipped>
316 <SOAP-ENV:Body>
317 <mymethod xmlns="urn:MyURI" />
318 </SOAP-ENV:Body>
319 </SOAP-ENV:Envelope>
320
321 Some .NET web services have been reported to require this XML
322 namespace idiom.
323
324 soapversion(optional value)
325 $client->soapversion('1.2');
326
327 If no parameter is given, returns the current version of SOAP that
328 is being used by the client object to encode requests. If a
329 parameter is given, the method attempts to set that as the version
330 of SOAP being used.
331
332 The value should be either 1.1 or 1.2.
333
334 envprefix(QName)
335 $client->envprefix('env');
336
337 This method is a shortcut for:
338
339 $client->serializer->envprefix(QName);
340
341 Gets or sets the namespace prefix for the SOAP namespace. The
342 default is SOAP.
343
344 The prefix itself has no meaning, but applications may wish to
345 chose one explicitly to denote different versions of SOAP or the
346 like.
347
348 encprefix(QName)
349 $client->encprefix('enc');
350
351 This method is a shortcut for:
352
353 $client->serializer->encprefix(QName);
354
355 Gets or sets the namespace prefix for the encoding rules namespace.
356 The default value is SOAP-ENC.
357
358 While it may seem to be an unnecessary operation to set a value that
359 isn't relevant to the message, such as the namespace labels for the
360 envelope and encoding URNs, the ability to set these labels explicitly
361 can prove to be a great aid in distinguishing and debugging messages on
362 the server side of operations.
363
364 encoding(encoding URN)
365 $client->encoding($soap_12_encoding_URN);
366
367 This method is a shortcut for:
368
369 $client->serializer->encoding(args);
370
371 Where the earlier method dealt with the label used for the
372 attributes related to the SOAP encoding scheme, this method
373 actually sets the URN to be specified as the encoding scheme for
374 the message. The default is to specify the encoding for SOAP 1.1,
375 so this is handy for applications that need to encode according to
376 SOAP 1.2 rules.
377
378 typelookup
379 $client->typelookup;
380
381 This method is a shortcut for:
382
383 $client->serializer->typelookup;
384
385 Gives the application access to the type-lookup table from the
386 serializer object. See the section on SOAP::Serializer.
387
388 uri(service specifier)
389 Deprecated - the "uri" subroutine is deprecated in order to provide
390 a more intuitive naming scheme for subroutines that set namespaces.
391 In the future, you will be required to use either the "ns()" or
392 "default_ns()" subroutines instead of "uri()".
393
394 $client->uri($service_uri);
395
396 This method is a shortcut for:
397
398 $client->serializer->uri(service);
399
400 The URI associated with this accessor on a client object is the
401 service-specifier for the request, often encoded for HTTP-based
402 requests as the SOAPAction header. While the names may seem
403 confusing, this method doesn't specify the endpoint itself. In most
404 circumstances, the "uri" refers to the namespace used for the
405 request.
406
407 Often times, the value may look like a valid URL. Despite this, it
408 doesn't have to point to an existing resource (and often doesn't).
409 This method sets and retrieves this value from the object. Note
410 that no transport code is triggered by this because it has no
411 direct effect on the transport of the object.
412
413 multirefinplace(boolean)
414 $client->multirefinplace(1);
415
416 This method is a shortcut for:
417
418 $client->serializer->multirefinplace(boolean);
419
420 Controls how the serializer handles values that have multiple
421 references to them. Recall from previous SOAP chapters that a value
422 may be tagged with an identifier, then referred to in several
423 places. When this is the case for a value, the serializer defaults
424 to putting the data element towards the top of the message, right
425 after the opening tag of the method-specification. It is serialized
426 as a standalone entity with an ID that is then referenced at the
427 relevant places later on. If this method is used to set a true
428 value, the behavior is different. When the multirefinplace
429 attribute is true, the data is serialized at the first place that
430 references it, rather than as a separate element higher up in the
431 body. This is more compact but may be harder to read or trace in a
432 debugging environment.
433
434 parts( ARRAY )
435 Used to specify an array of MIME::Entity's to be attached to the
436 transmitted SOAP message. Attachments that are returned in a
437 response can be accessed by "SOAP::SOM::parts()".
438
439 self
440 $ref = SOAP::Lite->self;
441
442 Returns an object reference to the default global object the
443 "SOAP::Lite" package maintains. This is the object that processes
444 many of the arguments when provided on the use line.
445
446 The following method isn't an accessor style of method but neither does
447 it fit with the group that immediately follows it:
448
449 call(arguments)
450 $client->call($method => @arguments);
451
452 As has been illustrated in previous chapters, the "SOAP::Lite"
453 client objects can manage remote calls with auto-dispatching using
454 some of Perl's more elaborate features. call is used when the
455 application wants a greater degree of control over the details of
456 the call itself. The method may be built up from a SOAP::Data
457 object, so as to allow full control over the namespace associated
458 with the tag, as well as other attributes like encoding. This is
459 also important for calling methods that contain characters not
460 allowable in Perl function names, such as A.B.C.
461
462 The next four methods used in the "SOAP::Lite" class are geared towards
463 handling the types of events than can occur during the message
464 lifecycle. Each of these sets up a callback for the event in question:
465
466 on_action(callback)
467 $client->on_action(sub { qq("$_[0]") });
468
469 Triggered when the transport object sets up the SOAPAction header
470 for an HTTP-based call. The default is to set the header to the
471 string, uri#method, in which URI is the value set by the uri method
472 described earlier, and method is the name of the method being
473 called. When called, the routine referenced (or the closure, if
474 specified as in the example) is given two arguments, uri and
475 method, in that order.
476
477 .NET web services usually expect "/" as separator for "uri" and
478 "method". To change SOAP::Lite's behaviour to use uri/method as
479 SOAPAction header, use the following code:
480
481 $client->on_action( sub { join '/', @_ } );
482
483 on_fault(callback)
484 $client->on_fault(sub { popup_dialog($_[1]) });
485
486 Triggered when a method call results in a fault response from the
487 server. When it is called, the argument list is first the client
488 object itself, followed by the object that encapsulates the fault.
489 In the example, the fault object is passed (without the client
490 object) to a hypothetical GUI function that presents an error
491 dialog with the text of fault extracted from the object (which is
492 covered shortly under the SOAP::SOM methods).
493
494 on_nonserialized(callback)
495 $client->on_nonserialized(sub { die "$_[0]?!?" });
496
497 Occasionally, the serializer may be given data it can't turn into
498 SOAP-savvy XML; for example, if a program bug results in a code
499 reference or something similar being passed in as a parameter to
500 method call. When that happens, this callback is activated, with
501 one argument. That argument is the data item that could not be
502 understood. It will be the only argument. If the routine returns,
503 the return value is pasted into the message as the serialization.
504 Generally, an error is in order, and this callback allows for
505 control over signaling that error.
506
507 on_debug(callback)
508 $client->on_debug(sub { print @_ });
509
510 Deprecated. Use the global +debug and +trace facilities described
511 in SOAP::Trace
512
513 Note that this method will not work as expected: Instead of
514 affecting the debugging behaviour of the object called on, it will
515 globally affect the debugging behaviour for all objects of that
516 class.
517
519 This chapter guides you to writing a SOAP client by example.
520
521 The SOAP service to be accessed is a simple variation of the well-known
522 hello world program. It accepts two parameters, a name and a given
523 name, and returns "Hello $given_name $name".
524
525 We will use "Martin Kutter" as the name for the call, so all variants
526 will print the following message on success:
527
528 Hello Martin Kutter!
529
530 SOAP message styles
531 There are three common (and one less common) variants of SOAP messages.
532
533 These address the message style (positional parameters vs. specified
534 message documents) and encoding (as-is vs. typed).
535
536 The different message styles are:
537
538 · rpc/encoded
539
540 Typed, positional parameters. Widely used in scripting languages.
541 The type of the arguments is included in the message. Arrays and
542 the like may be encoded using SOAP encoding rules (or others).
543
544 · rpc/literal
545
546 As-is, positional parameters. The type of arguments is defined by
547 some pre-exchanged interface definition.
548
549 · document/encoded
550
551 Specified message with typed elements. Rarely used.
552
553 · document/literal
554
555 Specified message with as-is elements. The message specification
556 and element types are defined by some pre-exchanged interface
557 definition.
558
559 As of 2008, document/literal has become the predominant SOAP message
560 variant. rpc/literal and rpc/encoded are still in use, mainly with
561 scripting languages, while document/encoded is hardly used at all.
562
563 You will see clients for the rpc/encoded and document/literal SOAP
564 variants in this section.
565
566 Example implementations
567 RPC/ENCODED
568
569 Rpc/encoded is most popular with scripting languages like perl, php and
570 python without the use of a WSDL. Usual method descriptions look like
571 this:
572
573 Method: sayHello(string, string)
574 Parameters:
575 name: string
576 givenName: string
577
578 Such a description usually means that you can call a method named
579 "sayHello" with two positional parameters, "name" and "givenName",
580 which both are strings.
581
582 The message corresponding to this description looks somewhat like this:
583
584 <sayHello xmlns="urn:HelloWorld">
585 <s-gensym01 xsi:type="xsd:string">Kutter</s-gensym01>
586 <s-gensym02 xsi:type="xsd:string">Martin</s-gensym02>
587 </sayHello>
588
589 Any XML tag names may be used instead of the "s-gensym01" stuff -
590 parameters are positional, the tag names have no meaning.
591
592 A client producing such a call is implemented like this:
593
594 use SOAP::Lite;
595 my $soap = SOAP::Lite->new( proxy => 'http://localhost:81/soap-wsdl-test/helloworld.pl');
596 $soap->default_ns('urn:HelloWorld');
597 my $som = $soap->call('sayHello', 'Kutter', 'Martin');
598 die $som->faultstring if ($som->fault);
599 print $som->result, "\n";
600
601 You can of course use a one-liner, too...
602
603 Sometimes, rpc/encoded interfaces are described with WSDL definitions.
604 A WSDL accepting "named" parameters with rpc/encoded looks like this:
605
606 <definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
607 xmlns:s="http://www.w3.org/2001/XMLSchema"
608 xmlns:s0="urn:HelloWorld"
609 targetNamespace="urn:HelloWorld"
610 xmlns="http://schemas.xmlsoap.org/wsdl/">
611 <types>
612 <s:schema targetNamespace="urn:HelloWorld">
613 </s:schema>
614 </types>
615 <message name="sayHello">
616 <part name="name" type="s:string" />
617 <part name="givenName" type="s:string" />
618 </message>
619 <message name="sayHelloResponse">
620 <part name="sayHelloResult" type="s:string" />
621 </message>
622
623 <portType name="Service1Soap">
624 <operation name="sayHello">
625 <input message="s0:sayHello" />
626 <output message="s0:sayHelloResponse" />
627 </operation>
628 </portType>
629
630 <binding name="Service1Soap" type="s0:Service1Soap">
631 <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
632 style="rpc" />
633 <operation name="sayHello">
634 <soap:operation soapAction="urn:HelloWorld#sayHello"/>
635 <input>
636 <soap:body use="encoded"
637 encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
638 </input>
639 <output>
640 <soap:body use="encoded"
641 encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
642 </output>
643 </operation>
644 </binding>
645 <service name="HelloWorld">
646 <port name="HelloWorldSoap" binding="s0:Service1Soap">
647 <soap:address location="http://localhost:81/soap-wsdl-test/helloworld.pl" />
648 </port>
649 </service>
650 </definitions>
651
652 The message corresponding to this schema looks like this:
653
654 <sayHello xmlns="urn:HelloWorld">
655 <name xsi:type="xsd:string">Kutter</name>
656 <givenName xsi:type="xsd:string">Martin</givenName>
657 </sayHello>
658
659 A web service client using this schema looks like this:
660
661 use SOAP::Lite;
662 my $soap = SOAP::Lite->service("file:say_hello_rpcenc.wsdl");
663 eval { my $result = $soap->sayHello('Kutter', 'Martin'); };
664 if ($@) {
665 die $@;
666 }
667 print $som->result();
668
669 You may of course also use the following one-liner:
670
671 perl -MSOAP::Lite -e 'print SOAP::Lite->service("file:say_hello_rpcenc.wsdl")\
672 ->sayHello('Kutter', 'Martin'), "\n";'
673
674 A web service client (without a service description) looks like this.
675
676 use SOAP::Lite;
677 my $soap = SOAP::Lite->new( proxy => 'http://localhost:81/soap-wsdl-test/helloworld.pl');
678 $soap->default_ns('urn:HelloWorld');
679 my $som = $soap->call('sayHello',
680 SOAP::Data->name('name')->value('Kutter'),
681 SOAP::Data->name('givenName')->value('Martin')
682 );
683 die $som->faultstring if ($som->fault);
684 print $som->result, "\n";
685
686 RPC/LITERAL
687
688 SOAP web services using the document/literal message encoding are
689 usually described by some Web Service Definition. Our web service has
690 the following WSDL description:
691
692 <definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
693 xmlns:s="http://www.w3.org/2001/XMLSchema"
694 xmlns:s0="urn:HelloWorld"
695 targetNamespace="urn:HelloWorld"
696 xmlns="http://schemas.xmlsoap.org/wsdl/">
697 <types>
698 <s:schema targetNamespace="urn:HelloWorld">
699 <s:complexType name="sayHello">
700 <s:sequence>
701 <s:element minOccurs="0" maxOccurs="1" name="name"
702 type="s:string" />
703 <s:element minOccurs="0" maxOccurs="1" name="givenName"
704 type="s:string" nillable="1" />
705 </s:sequence>
706 </s:complexType>
707
708 <s:complexType name="sayHelloResponse">
709 <s:sequence>
710 <s:element minOccurs="0" maxOccurs="1" name="sayHelloResult"
711 type="s:string" />
712 </s:sequence>
713 </s:complexType>
714 </s:schema>
715 </types>
716 <message name="sayHello">
717 <part name="parameters" type="s0:sayHello" />
718 </message>
719 <message name="sayHelloResponse">
720 <part name="parameters" type="s0:sayHelloResponse" />
721 </message>
722
723 <portType name="Service1Soap">
724 <operation name="sayHello">
725 <input message="s0:sayHello" />
726 <output message="s0:sayHelloResponse" />
727 </operation>
728 </portType>
729
730 <binding name="Service1Soap" type="s0:Service1Soap">
731 <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
732 style="rpc" />
733 <operation name="sayHello">
734 <soap:operation soapAction="urn:HelloWorld#sayHello"/>
735 <input>
736 <soap:body use="literal" namespace="urn:HelloWorld"/>
737 </input>
738 <output>
739 <soap:body use="literal" namespace="urn:HelloWorld"/>
740 </output>
741 </operation>
742 </binding>
743 <service name="HelloWorld">
744 <port name="HelloWorldSoap" binding="s0:Service1Soap">
745 <soap:address location="http://localhost:80//helloworld.pl" />
746 </port>
747 </service>
748 </definitions>
749
750 The XML message (inside the SOAP Envelope) look like this:
751
752 <ns0:sayHello xmlns:ns0="urn:HelloWorld">
753 <parameters>
754 <name>Kutter</name>
755 <givenName>Martin</givenName>
756 </parameters>
757 </ns0:sayHello>
758
759 <sayHelloResponse xmlns:ns0="urn:HelloWorld">
760 <parameters>
761 <sayHelloResult>Hello Martin Kutter!</sayHelloResult>
762 </parameters>
763 </sayHelloResponse>
764
765 This is the SOAP::Lite implementation for the web service client:
766
767 use SOAP::Lite +trace;
768 my $soap = SOAP::Lite->new( proxy => 'http://localhost:80/helloworld.pl');
769
770 $soap->on_action( sub { "urn:HelloWorld#sayHello" });
771 $soap->autotype(0)->readable(1);
772 $soap->default_ns('urn:HelloWorld');
773
774 my $som = $soap->call('sayHello', SOAP::Data->name('parameters')->value(
775 \SOAP::Data->value([
776 SOAP::Data->name('name')->value( 'Kutter' ),
777 SOAP::Data->name('givenName')->value('Martin'),
778 ]))
779 );
780
781 die $som->fault->{ faultstring } if ($som->fault);
782 print $som->result, "\n";
783
784 DOCUMENT/LITERAL
785
786 SOAP web services using the document/literal message encoding are
787 usually described by some Web Service Definition. Our web service has
788 the following WSDL description:
789
790 <definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
791 xmlns:s="http://www.w3.org/2001/XMLSchema"
792 xmlns:s0="urn:HelloWorld"
793 targetNamespace="urn:HelloWorld"
794 xmlns="http://schemas.xmlsoap.org/wsdl/">
795 <types>
796 <s:schema targetNamespace="urn:HelloWorld">
797 <s:element name="sayHello">
798 <s:complexType>
799 <s:sequence>
800 <s:element minOccurs="0" maxOccurs="1" name="name" type="s:string" />
801 <s:element minOccurs="0" maxOccurs="1" name="givenName" type="s:string" nillable="1" />
802 </s:sequence>
803 </s:complexType>
804 </s:element>
805
806 <s:element name="sayHelloResponse">
807 <s:complexType>
808 <s:sequence>
809 <s:element minOccurs="0" maxOccurs="1" name="sayHelloResult" type="s:string" />
810 </s:sequence>
811 </s:complexType>
812 </s:element>
813 </types>
814 <message name="sayHelloSoapIn">
815 <part name="parameters" element="s0:sayHello" />
816 </message>
817 <message name="sayHelloSoapOut">
818 <part name="parameters" element="s0:sayHelloResponse" />
819 </message>
820
821 <portType name="Service1Soap">
822 <operation name="sayHello">
823 <input message="s0:sayHelloSoapIn" />
824 <output message="s0:sayHelloSoapOut" />
825 </operation>
826 </portType>
827
828 <binding name="Service1Soap" type="s0:Service1Soap">
829 <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
830 style="document" />
831 <operation name="sayHello">
832 <soap:operation soapAction="urn:HelloWorld#sayHello"/>
833 <input>
834 <soap:body use="literal" />
835 </input>
836 <output>
837 <soap:body use="literal" />
838 </output>
839 </operation>
840 </binding>
841 <service name="HelloWorld">
842 <port name="HelloWorldSoap" binding="s0:Service1Soap">
843 <soap:address location="http://localhost:80//helloworld.pl" />
844 </port>
845 </service>
846 </definitions>
847
848 The XML message (inside the SOAP Envelope) look like this:
849
850 <sayHello xmlns="urn:HelloWorld">
851 <name>Kutter</name>
852 <givenName>Martin</givenName>
853 </sayHello>
854
855 <sayHelloResponse>
856 <sayHelloResult>Hello Martin Kutter!</sayHelloResult>
857 </sayHelloResponse>
858
859 You can call this web service with the following client code:
860
861 use SOAP::Lite;
862 my $soap = SOAP::Lite->new( proxy => 'http://localhost:80/helloworld.pl');
863
864 $soap->on_action( sub { "urn:HelloWorld#sayHello" });
865 $soap->autotype(0);
866 $soap->default_ns('urn:HelloWorld');
867
868 my $som = $soap->call("sayHello",
869 SOAP::Data->name('name')->value( 'Kutter' ),
870 SOAP::Data->name('givenName')->value('Martin'),
871 );
872
873 die $som->fault->{ faultstring } if ($som->fault);
874 print $som->result, "\n";
875
876 Differences between the implementations
877 You may have noticed that there's little difference between the
878 rpc/encoded, rpc/literal and the document/literal example's
879 implementation. In fact, from SOAP::Lite's point of view, the only
880 differences between rpc/literal and document/literal that parameters
881 are always named.
882
883 In our example, the rpc/encoded variant already used named parameters
884 (by using two messages), so there's no difference at all.
885
886 You may have noticed the somewhat strange idiom for passing a list of
887 named parameters in the rpc/literal example:
888
889 my $som = $soap->call('sayHello', SOAP::Data->name('parameters')->value(
890 \SOAP::Data->value([
891 SOAP::Data->name('name')->value( 'Kutter' ),
892 SOAP::Data->name('givenName')->value('Martin'),
893 ]))
894 );
895
896 While SOAP::Data provides full control over the XML generated, passing
897 hash-like structures require additional coding.
898
900 See SOAP::Server, or SOAP::Transport.
901
903 ATTACHMENTS
904 "SOAP::Lite" features support for the SOAP with Attachments
905 specification. Currently, SOAP::Lite only supports MIME based
906 attachments. DIME based attachments are yet to be fully functional.
907
908 EXAMPLES
909
910 Client sending an attachment
911
912 "SOAP::Lite" clients can specify attachments to be sent along with a
913 request by using the "SOAP::Lite::parts()" method, which takes as an
914 argument an ARRAY of "MIME::Entity"'s.
915
916 use SOAP::Lite;
917 use MIME::Entity;
918 my $ent = build MIME::Entity
919 Type => "image/gif",
920 Encoding => "base64",
921 Path => "somefile.gif",
922 Filename => "saveme.gif",
923 Disposition => "attachment";
924 my $som = SOAP::Lite
925 ->uri($SOME_NAMESPACE)
926 ->parts([ $ent ])
927 ->proxy($SOME_HOST)
928 ->some_method(SOAP::Data->name("foo" => "bar"));
929
930 Client retrieving an attachment
931
932 A client accessing attachments that were returned in a response by
933 using the "SOAP::SOM::parts()" accessor.
934
935 use SOAP::Lite;
936 use MIME::Entity;
937 my $soap = SOAP::Lite
938 ->uri($NS)
939 ->proxy($HOST);
940 my $som = $soap->foo();
941 foreach my $part (${$som->parts}) {
942 print $part->stringify;
943 }
944
945 Server receiving an attachment
946
947 Servers, like clients, use the SOAP::SOM module to access attachments
948 transmitted to it.
949
950 package Attachment;
951 use SOAP::Lite;
952 use MIME::Entity;
953 use strict;
954 use vars qw(@ISA);
955 @ISA = qw(SOAP::Server::Parameters);
956 sub someMethod {
957 my $self = shift;
958 my $envelope = pop;
959 foreach my $part (@{$envelope->parts}) {
960 print "AttachmentService: attachment found! (".ref($part).")\n";
961 }
962 # do something
963 }
964
965 Server responding with an attachment
966
967 Servers wishing to return an attachment to the calling client need only
968 return "MIME::Entity" objects along with SOAP::Data elements, or any
969 other data intended for the response.
970
971 package Attachment;
972 use SOAP::Lite;
973 use MIME::Entity;
974 use strict;
975 use vars qw(@ISA);
976 @ISA = qw(SOAP::Server::Parameters);
977 sub someMethod {
978 my $self = shift;
979 my $envelope = pop;
980 my $ent = build MIME::Entity
981 'Id' => "<1234>",
982 'Type' => "text/xml",
983 'Path' => "some.xml",
984 'Filename' => "some.xml",
985 'Disposition' => "attachment";
986 return SOAP::Data->name("foo" => "blah blah blah"),$ent;
987 }
988
989 DEFAULT SETTINGS
990 Though this feature looks similar to autodispatch they have (almost)
991 nothing in common. This capability allows you specify default settings
992 so that all objects created after that will be initialized with the
993 proper default settings.
994
995 If you wish to provide common "proxy()" or "uri()" settings for all
996 "SOAP::Lite" objects in your application you may do:
997
998 use SOAP::Lite
999 proxy => 'http://localhost/cgi-bin/soap.cgi',
1000 uri => 'http://my.own.com/My/Examples';
1001
1002 my $soap1 = new SOAP::Lite; # will get the same proxy()/uri() as above
1003 print $soap1->getStateName(1)->result;
1004
1005 my $soap2 = SOAP::Lite->new; # same thing as above
1006 print $soap2->getStateName(2)->result;
1007
1008 # or you may override any settings you want
1009 my $soap3 = SOAP::Lite->proxy('http://localhost/');
1010 print $soap3->getStateName(1)->result;
1011
1012 Any "SOAP::Lite" properties can be propagated this way. Changes in
1013 object copies will not affect global settings and you may still change
1014 global settings with "SOAP::Lite->self" call which returns reference to
1015 global object. Provided parameter will update this object and you can
1016 even set it to "undef":
1017
1018 SOAP::Lite->self(undef);
1019
1020 The "use SOAP::Lite" syntax also lets you specify default event
1021 handlers for your code. If you have different SOAP objects and want to
1022 share the same "on_action()" (or "on_fault()" for that matter) handler.
1023 You can specify "on_action()" during initialization for every object,
1024 but you may also do:
1025
1026 use SOAP::Lite
1027 on_action => sub {sprintf '%s#%s', @_};
1028
1029 and this handler will be the default handler for all your SOAP objects.
1030 You can override it if you specify a handler for a particular object.
1031 See t/*.t for example of on_fault() handler.
1032
1033 Be warned, that since "use ..." is executed at compile time all "use"
1034 statements will be executed before script execution that can make
1035 unexpected results. Consider code:
1036
1037 use SOAP::Lite proxy => 'http://localhost/';
1038 print SOAP::Lite->getStateName(1)->result;
1039
1040 use SOAP::Lite proxy => 'http://localhost/cgi-bin/soap.cgi';
1041 print SOAP::Lite->getStateName(1)->result;
1042
1043 Both SOAP calls will go to 'http://localhost/cgi-bin/soap.cgi'. If you
1044 want to execute "use" at run-time, put it in "eval":
1045
1046 eval "use SOAP::Lite proxy => 'http://localhost/cgi-bin/soap.cgi'; 1" or die;
1047
1048 Or alternatively,
1049
1050 SOAP::Lite->self->proxy('http://localhost/cgi-bin/soap.cgi');
1051
1052 SETTING MAXIMUM MESSAGE SIZE
1053 One feature of "SOAP::Lite" is the ability to control the maximum size
1054 of a message a SOAP::Lite server will be allowed to process. To control
1055 this feature simply define $SOAP::Constants::MAX_CONTENT_SIZE in your
1056 code like so:
1057
1058 use SOAP::Transport::HTTP;
1059 use MIME::Entity;
1060 $SOAP::Constants::MAX_CONTENT_SIZE = 10000;
1061 SOAP::Transport::HTTP::CGI
1062 ->dispatch_to('TemperatureService')
1063 ->handle;
1064
1065 IN/OUT, OUT PARAMETERS AND AUTOBINDING
1066 "SOAP::Lite" gives you access to all parameters (both in/out and out)
1067 and also does some additional work for you. Lets consider following
1068 example:
1069
1070 <mehodResponse>
1071 <res1>name1</res1>
1072 <res2>name2</res2>
1073 <res3>name3</res3>
1074 </mehodResponse>
1075
1076 In that case:
1077
1078 $result = $r->result; # gives you 'name1'
1079 $paramout1 = $r->paramsout; # gives you 'name2', because of scalar context
1080 $paramout1 = ($r->paramsout)[0]; # gives you 'name2' also
1081 $paramout2 = ($r->paramsout)[1]; # gives you 'name3'
1082
1083 or
1084
1085 @paramsout = $r->paramsout; # gives you ARRAY of out parameters
1086 $paramout1 = $paramsout[0]; # gives you 'res2', same as ($r->paramsout)[0]
1087 $paramout2 = $paramsout[1]; # gives you 'res3', same as ($r->paramsout)[1]
1088
1089 Generally, if server returns "return (1,2,3)" you will get 1 as the
1090 result and 2 and 3 as out parameters.
1091
1092 If the server returns "return [1,2,3]" you will get an ARRAY reference
1093 from "result()" and "undef" from "paramsout()".
1094
1095 Results can be arbitrary complex: they can be an array references, they
1096 can be objects, they can be anything and still be returned by
1097 "result()" . If only one parameter is returned, "paramsout()" will
1098 return "undef".
1099
1100 Furthermore, if you have in your output parameters a parameter with the
1101 same signature (name+type) as in the input parameters this parameter
1102 will be mapped into your input automatically. For example:
1103
1104 Server Code:
1105
1106 sub mymethod {
1107 shift; # object/class reference
1108 my $param1 = shift;
1109 my $param2 = SOAP::Data->name('myparam' => shift() * 2);
1110 return $param1, $param2;
1111 }
1112
1113 Client Code:
1114
1115 $a = 10;
1116 $b = SOAP::Data->name('myparam' => 12);
1117 $result = $soap->mymethod($a, $b);
1118
1119 After that, "$result == 10 and $b->value == 24"! Magic? Sort of.
1120
1121 Autobinding gives it to you. That will work with objects also with one
1122 difference: you do not need to worry about the name and the type of
1123 object parameter. Consider the "PingPong" example
1124 (examples/My/PingPong.pm and examples/pingpong.pl):
1125
1126 Server Code:
1127
1128 package My::PingPong;
1129
1130 sub new {
1131 my $self = shift;
1132 my $class = ref($self) || $self;
1133 bless {_num=>shift} => $class;
1134 }
1135
1136 sub next {
1137 my $self = shift;
1138 $self->{_num}++;
1139 }
1140
1141 Client Code:
1142
1143 use SOAP::Lite +autodispatch =>
1144 uri => 'urn:',
1145 proxy => 'http://localhost/';
1146
1147 my $p = My::PingPong->new(10); # $p->{_num} is 10 now, real object returned
1148 print $p->next, "\n"; # $p->{_num} is 11 now!, object autobinded
1149
1150 STATIC AND DYNAMIC SERVICE DEPLOYMENT
1151 Let us scrutinize the deployment process. When designing your SOAP
1152 server you can consider two kind of deployment: static and dynamic. For
1153 both, static and dynamic, you should specify "MODULE",
1154 "MODULE::method", "method" or "PATH/" when creating "use"ing the
1155 SOAP::Lite module. The difference between static and dynamic deployment
1156 is that in case of 'dynamic', any module which is not present will be
1157 loaded on demand. See the "SECURITY" section for detailed description.
1158
1159 When statically deploying a SOAP Server, you need to know all modules
1160 handling SOAP requests before.
1161
1162 Dynamic deployment allows extending your SOAP Server's interface by
1163 just installing another module into the dispatch_to path (see below).
1164
1165 STATIC DEPLOYMENT EXAMPLE
1166
1167 use SOAP::Transport::HTTP;
1168 use My::Examples; # module is preloaded
1169
1170 SOAP::Transport::HTTP::CGI
1171 # deployed module should be present here or client will get
1172 # 'access denied'
1173 -> dispatch_to('My::Examples')
1174 -> handle;
1175
1176 For static deployment you should specify the MODULE name directly.
1177
1178 You should also use static binding when you have several different
1179 classes in one file and want to make them available for SOAP calls.
1180
1181 DYNAMIC DEPLOYMENT EXAMPLE
1182
1183 use SOAP::Transport::HTTP;
1184 # name is unknown, module will be loaded on demand
1185
1186 SOAP::Transport::HTTP::CGI
1187 # deployed module should be present here or client will get 'access denied'
1188 -> dispatch_to('/Your/Path/To/Deployed/Modules', 'My::Examples')
1189 -> handle;
1190
1191 For dynamic deployment you can specify the name either directly (in
1192 that case it will be "require"d without any restriction) or indirectly,
1193 with a PATH. In that case, the ONLY path that will be available will be
1194 the PATH given to the dispatch_to() method). For information how to
1195 handle this situation see "SECURITY" section.
1196
1197 SUMMARY
1198
1199 dispatch_to(
1200 # dynamic dispatch that allows access to ALL modules in specified directory
1201 PATH/TO/MODULES
1202 # 1. specifies directory
1203 # -- AND --
1204 # 2. gives access to ALL modules in this directory without limits
1205
1206 # static dispatch that allows access to ALL methods in particular MODULE
1207 MODULE
1208 # 1. gives access to particular module (all available methods)
1209 # PREREQUISITES:
1210 # module should be loaded manually (for example with 'use ...')
1211 # -- OR --
1212 # you can still specify it in PATH/TO/MODULES
1213
1214 # static dispatch that allows access to particular method ONLY
1215 MODULE::method
1216 # same as MODULE, but gives access to ONLY particular method,
1217 # so there is not much sense to use both MODULE and MODULE::method
1218 # for the same MODULE
1219 );
1220
1221 In addition to this "SOAP::Lite" also supports an experimental syntax
1222 that allows you to bind a specific URL or SOAPAction to a CLASS/MODULE
1223 or object.
1224
1225 For example:
1226
1227 dispatch_with({
1228 URI => MODULE, # 'http://www.soaplite.com/' => 'My::Class',
1229 SOAPAction => MODULE, # 'http://www.soaplite.com/method' => 'Another::Class',
1230 URI => object, # 'http://www.soaplite.com/obj' => My::Class->new,
1231 })
1232
1233 "URI" is checked before "SOAPAction". You may use both the
1234 "dispatch_to()" and "dispatch_with()" methods in the same server, but
1235 note that "dispatch_with()" has a higher order of precedence.
1236 "dispatch_to()" will be checked only after "URI" and "SOAPAction" has
1237 been checked.
1238
1239 See also: EXAMPLE APACHE::REGISTRY USAGE, "SECURITY"
1240
1241 COMPRESSION
1242 "SOAP::Lite" provides you option to enable transparent compression over
1243 the wire. Compression can be enabled by specifying a threshold value
1244 (in the form of kilobytes) for compression on both the client and
1245 server sides:
1246
1247 Note: Compression currently only works for HTTP based servers and
1248 clients.
1249
1250 Client Code
1251
1252 print SOAP::Lite
1253 ->uri('http://localhost/My/Parameters')
1254 ->proxy('http://localhost/', options => {compress_threshold => 10000})
1255 ->echo(1 x 10000)
1256 ->result;
1257
1258 Server Code
1259
1260 my $server = SOAP::Transport::HTTP::CGI
1261 ->dispatch_to('My::Parameters')
1262 ->options({compress_threshold => 10000})
1263 ->handle;
1264
1265 For more information see COMPRESSION in HTTP::Transport.
1266
1268 For security reasons, the existing path for Perl modules (@INC) will be
1269 disabled once you have chosen dynamic deployment and specified your own
1270 "PATH/". If you wish to access other modules in your included package
1271 you have several options:
1272
1273 1. Switch to static linking:
1274
1275 use MODULE;
1276 $server->dispatch_to('MODULE');
1277
1278 Which can also be useful when you want to import something specific
1279 from the deployed modules:
1280
1281 use MODULE qw(import_list);
1282
1283 2. Change "use" to "require". The path is only unavailable during the
1284 initialization phase. It is available once more during execution.
1285 Therefore, if you utilize "require" somewhere in your package, it
1286 will work.
1287
1288 3. Wrap "use" in an "eval" block:
1289
1290 eval 'use MODULE qw(import_list)'; die if $@;
1291
1292 4. Set your include path in your package and then specify "use". Don't
1293 forget to put @INC in a "BEGIN{}" block or it won't work. For
1294 example,
1295
1296 BEGIN { @INC = qw(my_directory); use MODULE }
1297
1299 Microsoft .NET client with SOAP::Lite Server
1300 In order to use a .NET client with a SOAP::Lite server, be sure you use
1301 fully qualified names for your return values. For example:
1302
1303 return SOAP::Data->name('myname')
1304 ->type('string')
1305 ->uri($MY_NAMESPACE)
1306 ->value($output);
1307
1308 In addition see comment about default encoding in .NET Web Services
1309 below.
1310
1311 SOAP::Lite client with a .NET server
1312 If experiencing problems when using a SOAP::Lite client to call a .NET
1313 Web service, it is recommended you check, or adhere to all of the
1314 following recommendations:
1315
1316 Declare a proper soapAction in your call
1317 For example, use "on_action( sub {
1318 'http://www.myuri.com/WebService.aspx#someMethod'; } )".
1319
1320 Disable charset definition in Content-type header
1321 Some users have said that Microsoft .NET prefers the value of the
1322 Content-type header to be a mimetype exclusively, but SOAP::Lite
1323 specifies a character set in addition to the mimetype. This results
1324 in an error similar to:
1325
1326 Server found request content type to be 'text/xml; charset=utf-8',
1327 but expected 'text/xml'
1328
1329 To turn off this behavior specify use the following code:
1330
1331 use SOAP::Lite;
1332 $SOAP::Constants::DO_NOT_USE_CHARSET = 1;
1333 # The rest of your code
1334
1335 Use fully qualified name for method parameters
1336 For example, the following code is preferred:
1337
1338 SOAP::Data->name(Query => 'biztalk')
1339 ->uri('http://tempuri.org/')
1340
1341 As opposed to:
1342
1343 SOAP::Data->name('Query' => 'biztalk')
1344
1345 Place method in default namespace
1346 For example, the following code is preferred:
1347
1348 my $method = SOAP::Data->name('add')
1349 ->attr({xmlns => 'http://tempuri.org/'});
1350 my @rc = $soap->call($method => @parms)->result;
1351
1352 As opposed to:
1353
1354 my @rc = $soap->call(add => @parms)->result;
1355 # -- OR --
1356 my @rc = $soap->add(@parms)->result;
1357
1358 Disable use of explicit namespace prefixes
1359 Some user's have reported that .NET will simply not parse messages
1360 that use namespace prefixes on anything but SOAP elements
1361 themselves. For example, the following XML would not be parsed:
1362
1363 <SOAP-ENV:Envelope ...attributes skipped>
1364 <SOAP-ENV:Body>
1365 <namesp1:mymethod xmlns:namesp1="urn:MyURI" />
1366 </SOAP-ENV:Body>
1367 </SOAP-ENV:Envelope>
1368
1369 SOAP::Lite allows users to disable the use of explicit namespaces
1370 through the "use_prefix()" method. For example, the following code:
1371
1372 $som = SOAP::Lite->uri('urn:MyURI')
1373 ->proxy($HOST)
1374 ->use_prefix(0)
1375 ->myMethod();
1376
1377 Will result in the following XML, which is more palatable by .NET:
1378
1379 <SOAP-ENV:Envelope ...attributes skipped>
1380 <SOAP-ENV:Body>
1381 <mymethod xmlns="urn:MyURI" />
1382 </SOAP-ENV:Body>
1383 </SOAP-ENV:Envelope>
1384
1385 Modify your .NET server, if possible
1386 Stefan Pharies <stefanph@microsoft.com>:
1387
1388 SOAP::Lite uses the SOAP encoding (section 5 of the soap 1.1 spec),
1389 and the default for .NET Web Services is to use a literal encoding.
1390 So elements in the request are unqualified, but your service
1391 expects them to be qualified. .Net Web Services has a way for you
1392 to change the expected message format, which should allow you to
1393 get your interop working. At the top of your class in the asmx,
1394 add this attribute (for Beta 1):
1395
1396 [SoapService(Style=SoapServiceStyle.RPC)]
1397
1398 Another source said it might be this attribute (for Beta 2):
1399
1400 [SoapRpcService]
1401
1402 Full Web Service text may look like:
1403
1404 <%@ WebService Language="C#" Class="Test" %>
1405 using System;
1406 using System.Web.Services;
1407 using System.Xml.Serialization;
1408
1409 [SoapService(Style=SoapServiceStyle.RPC)]
1410 public class Test : WebService {
1411 [WebMethod]
1412 public int add(int a, int b) {
1413 return a + b;
1414 }
1415 }
1416
1417 Another example from Kirill Gavrylyuk <kirillg@microsoft.com>:
1418
1419 "You can insert [SoapRpcService()] attribute either on your class
1420 or on operation level".
1421
1422 <%@ WebService Language=CS class="DataType.StringTest"%>
1423
1424 namespace DataType {
1425
1426 using System;
1427 using System.Web.Services;
1428 using System.Web.Services.Protocols;
1429 using System.Web.Services.Description;
1430
1431 [SoapRpcService()]
1432 public class StringTest: WebService {
1433 [WebMethod]
1434 [SoapRpcMethod()]
1435 public string RetString(string x) {
1436 return(x);
1437 }
1438 }
1439 }
1440
1441 Example from Yann Christensen <yannc@microsoft.com>:
1442
1443 using System;
1444 using System.Web.Services;
1445 using System.Web.Services.Protocols;
1446
1447 namespace Currency {
1448 [WebService(Namespace="http://www.yourdomain.com/example")]
1449 [SoapRpcService]
1450 public class Exchange {
1451 [WebMethod]
1452 public double getRate(String country, String country2) {
1453 return 122.69;
1454 }
1455 }
1456 }
1457
1458 Special thanks goes to the following people for providing the above
1459 description and details on .NET interoperability issues:
1460
1461 Petr Janata <petr.janata@i.cz>,
1462
1463 Stefan Pharies <stefanph@microsoft.com>,
1464
1465 Brian Jepson <bjepson@jepstone.net>, and others
1466
1468 SOAP::Lite serializes "18373" as an integer, but I want it to be a
1469 string!
1470 SOAP::Lite guesses datatypes from the content provided, using a set
1471 of common-sense rules. These rules are not 100% reliable, though
1472 they fit for most data.
1473
1474 You may force the type by passing a SOAP::Data object with a type
1475 specified:
1476
1477 my $proxy = SOAP::Lite->proxy('http://www.example.org/soapservice');
1478 my $som = $proxy->myMethod(
1479 SOAP::Data->name('foo')->value(12345)->type('string')
1480 );
1481
1482 You may also change the precedence of the type-guessing rules. Note
1483 that this means fiddling with SOAP::Lite's internals - this may not
1484 work as expected in future versions.
1485
1486 The example above forces everything to be encoded as string (this
1487 is because the string test is normally last and always returns
1488 true):
1489
1490 my @list = qw(-1 45 foo bar 3838);
1491 my $proxy = SOAP::Lite->uri($uri)->proxy($proxyUrl);
1492 my $lookup = $proxy->serializer->typelookup;
1493 $lookup->{string}->[0] = 0;
1494 $proxy->serializer->typelookup($lookup);
1495 $proxy->myMethod(\@list);
1496
1497 See SOAP::Serializer for more details.
1498
1499 "+autodispatch" doesn't work in Perl 5.8
1500 There is a bug in Perl 5.8's "UNIVERSAL::AUTOLOAD" functionality
1501 that prevents the "+autodispatch" functionality from working
1502 properly. The workaround is to use "dispatch_from" instead. Where
1503 you might normally do something like this:
1504
1505 use Some::Module;
1506 use SOAP::Lite +autodispatch =>
1507 uri => 'urn:Foo'
1508 proxy => 'http://...';
1509
1510 You would do something like this:
1511
1512 use SOAP::Lite dispatch_from(Some::Module) =>
1513 uri => 'urn:Foo'
1514 proxy => 'http://...';
1515
1516 Problems using SOAP::Lite's COM Interface
1517 Can't call method "server" on undefined value
1518 You probably did not register Lite.dll using "regsvr32
1519 Lite.dll"
1520
1521 Failed to load PerlCtrl Runtime
1522 It is likely that you have install Perl in two different
1523 locations and the location of ActiveState's Perl is not the
1524 first instance of Perl specified in your PATH. To rectify,
1525 rename the directory in which the non-ActiveState Perl is
1526 installed, or be sure the path to ActiveState's Perl is
1527 specified prior to any other instance of Perl in your PATH.
1528
1529 Dynamic libraries are not found
1530 If you are using the Apache web server, and you are seeing
1531 something like the following in your webserver log file:
1532
1533 Can't load '/usr/local/lib/perl5/site_perl/.../XML/Parser/Expat/Expat.so'
1534 for module XML::Parser::Expat: dynamic linker: /usr/local/bin/perl:
1535 libexpat.so.0 is NEEDED, but object does not exist at
1536 /usr/local/lib/perl5/.../DynaLoader.pm line 200.
1537
1538 Then try placing the following into your httpd.conf file and see if
1539 it fixes your problem.
1540
1541 <IfModule mod_env.c>
1542 PassEnv LD_LIBRARY_PATH
1543 </IfModule>
1544
1545 SOAP client reports "500 unexpected EOF before status line seen
1546 See "Apache is crashing with segfaults"
1547
1548 Apache is crashing with segfaults
1549 Using "SOAP::Lite" (or XML::Parser::Expat) in combination with
1550 mod_perl causes random segmentation faults in httpd processes. To
1551 fix, try configuring Apache with the following:
1552
1553 RULE_EXPAT=no
1554
1555 If you are using Apache 1.3.20 and later, try configuring Apache
1556 with the following option:
1557
1558 ./configure --disable-rule=EXPAT
1559
1560 See http://archive.covalent.net/modperl/2000/04/0185.xml for more
1561 details and lot of thanks to Robert Barta <rho@bigpond.net.au> for
1562 explaining this weird behavior.
1563
1564 If this doesn't address the problem, you may wish to try
1565 "-Uusemymalloc", or a similar option in order to instruct Perl to
1566 use the system's own "malloc".
1567
1568 Thanks to Tim Bunce <Tim.Bunce@pobox.com>.
1569
1570 CGI scripts do not work under Microsoft Internet Information Server
1571 (IIS)
1572 CGI scripts may not work under IIS unless scripts use the ".pl"
1573 extension, opposed to ".cgi".
1574
1575 Java SAX parser unable to parse message composed by SOAP::Lite
1576 In some cases SOAP messages created by "SOAP::Lite" may not be
1577 parsed properly by a SAX2/Java XML parser. This is due to a known
1578 bug in "org.xml.sax.helpers.ParserAdapter". This bug manifests
1579 itself when an attribute in an XML element occurs prior to the XML
1580 namespace declaration on which it depends. However, according to
1581 the XML specification, the order of these attributes is not
1582 significant.
1583
1584 http://www.megginson.com/SAX/index.html
1585
1586 Thanks to Steve Alpert (Steve_Alpert@idx.com) for pointing on it.
1587
1589 Processing of XML encoded fragments
1590 "SOAP::Lite" is based on XML::Parser which is basically wrapper
1591 around James Clark's expat parser. Expat's behavior for parsing XML
1592 encoded string can affect processing messages that have lot of
1593 encoded entities, like XML fragments, encoded as strings. Providing
1594 low-level details, parser will call char() callback for every
1595 portion of processed stream, but individually for every processed
1596 entity or newline. It can lead to lot of calls and additional
1597 memory manager expenses even for small messages. By contrast, XML
1598 messages which are encoded as base64Binary, don't have this problem
1599 and difference in processing time can be significant. For XML
1600 encoded string that has about 20 lines and 30 tags, number of call
1601 could be about 100 instead of one for the same string encoded as
1602 base64Binary.
1603
1604 Since it is parser's feature there is NO fix for this behavior (let
1605 me know if you find one), especially because you need to parse
1606 message you already got (and you cannot control content of this
1607 message), however, if your are in charge for both ends of
1608 processing you can switch encoding to base64 on sender's side. It
1609 will definitely work with SOAP::Lite and it may work with other
1610 toolkits/implementations also, but obviously I cannot guarantee
1611 that.
1612
1613 If you want to encode specific string as base64, just do
1614 "SOAP::Data->type(base64 => $string)" either on client or on server
1615 side. If you want change behavior for specific instance of
1616 SOAP::Lite, you may subclass "SOAP::Serializer", override
1617 "as_string()" method that is responsible for string encoding (take
1618 a look into "as_base64Binary()") and specify new serializer class
1619 for your SOAP::Lite object with:
1620
1621 my $soap = new SOAP::Lite
1622 serializer => My::Serializer->new,
1623 ..... other parameters
1624
1625 or on server side:
1626
1627 my $server = new SOAP::Transport::HTTP::Daemon # or any other server
1628 serializer => My::Serializer->new,
1629 ..... other parameters
1630
1631 If you want to change this behavior for all instances of
1632 SOAP::Lite, just substitute "as_string()" method with
1633 "as_base64Binary()" somewhere in your code after "use SOAP::Lite"
1634 and before actual processing/sending:
1635
1636 *SOAP::Serializer::as_string = \&SOAP::XMLSchema2001::Serializer::as_base64Binary;
1637
1638 Be warned that last two methods will affect all strings and convert
1639 them into base64 encoded. It doesn't make any difference for
1640 SOAP::Lite, but it may make a difference for other toolkits.
1641
1643 · No support for multidimensional, partially transmitted and sparse
1644 arrays (however arrays of arrays are supported, as well as any
1645 other data structures, and you can add your own implementation with
1646 SOAP::Data).
1647
1648 · Limited support for WSDL schema.
1649
1650 · XML::Parser::Lite relies on Unicode support in Perl and doesn't do
1651 entity decoding.
1652
1653 · Limited support for mustUnderstand and Actor attributes.
1654
1656 MacOS
1657 Information about XML::Parser for MacPerl could be found here:
1658
1659 http://bumppo.net/lists/macperl-modules/1999/07/msg00047.html
1660
1661 Compiled XML::Parser for MacOS could be found here:
1662
1663 http://www.perl.com/CPAN-local/authors/id/A/AS/ASANDSTRM/XML-Parser-2.27-bin-1-MacOS.tgz
1664
1666 Transport Modules
1667 SOAP::Lite allows one to add support for additional transport
1668 protocols, or server handlers, via separate modules implementing the
1669 SOAP::Transport::* interface. The following modules are available from
1670 CPAN:
1671
1672 · SOAP-Transport-HTTP-Nginx
1673
1674 SOAP::Transport::HTTP::Nginx provides a transport module for nginx
1675 (<http://nginx.net/>)
1676
1678 You can download the latest version SOAP::Lite for Unix or SOAP::Lite
1679 for Win32 from the following sources:
1680
1681 * CPAN: http://search.cpan.org/search?dist=SOAP-Lite
1682
1683 You are welcome to send e-mail to the maintainers of SOAP::Lite with
1684 your comments, suggestions, bug reports and complaints.
1685
1687 Special thanks to Randy J. Ray, author of Programming Web Services with
1688 Perl, who has contributed greatly to the documentation effort of
1689 SOAP::Lite.
1690
1691 Special thanks to O'Reilly publishing which has graciously allowed
1692 SOAP::Lite to republish and redistribute the SOAP::Lite reference
1693 manual found in Appendix B of Programming Web Services with Perl.
1694
1695 And special gratitude to all the developers who have contributed
1696 patches, ideas, time, energy, and help in a million different forms to
1697 the development of this software.
1698
1700 Latest development takes place on GitHub.com. Come on by and fork it.
1701
1702 git@github.com:redhotpenguin/perl-soaplite.git
1703
1704 Also see the HACKING file.
1705
1706 Actively recruiting maintainers for this module. Come and get it on!
1707
1709 Please use rt.cpan.org or github to report bugs. Pull requests are
1710 preferred.
1711
1713 Copyright (C) 2000-2007 Paul Kulchenko. All rights reserved.
1714
1715 Copyright (C) 2007-2008 Martin Kutter
1716
1717 Copyright (C) 2013 Fred Moyer
1718
1720 This library is free software; you can redistribute it and/or modify it
1721 under the same terms as Perl itself.
1722
1723 This text and all associated documentation for this library is made
1724 available under the Creative Commons Attribution-NoDerivs 2.0 license.
1725 http://creativecommons.org/licenses/by-nd/2.0/
1726
1728 Paul Kulchenko (paulclinger@yahoo.com)
1729
1730 Randy J. Ray (rjray@blackperl.com)
1731
1732 Byrne Reese (byrne@majordojo.com)
1733
1734 Martin Kutter (martin.kutter@fen-net.de)
1735
1736 Fred Moyer (fred@redhotpenguin.com)
1737
1738
1739
1740perl v5.28.1 2018-05-14 SOAP::Lite(3)