1SOAP::Lite(3) User Contributed Perl Documentation SOAP::Lite(3)
2
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 SOAP::Lite 0.71 will be the last version of SOAP::Lite running on perl
18 5.005
19 Future versions of SOAP::Lite will require at least perl 5.6.0
21 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 SOAP::Transport - Transport backend
30 SOAP::Data - Data objects
32 SOAP::Header - Header Data Objects
34 SOAP::Serializer - Serializes data structures to SOAP messages
36 SOAP::Deserializer - Deserializes SOAP messages into SOAP::SOM
38 objects
39 SOAP::SOM - SOAP Message objects
41 SOAP::Constants - Provides access to common constants and defaults
43 SOAP::Trace - Tracing facilities
45 SOAP::Schema - Provides access and stub(s) for schema(s)
47 SOAP::Schema::WSDL - WSDL implementation for SOAP::Schema
49 SOAP::Server - Handles requests on server side
51 SOAP::Server::Object - Handles objects-by-reference
53 SOAP::Fault - Provides support for Faults on server side
55 SOAP::Utils - A set of private and public utility subroutines
57 lib/SOAP/Packager.pm
59 SOAP::Packager - Provides an abstract class for implementing custom
60 packagers.
61 SOAP::Packager::MIME - Provides MIME support to SOAP::Lite
63 SOAP::Packager::DIME - Provides DIME support to SOAP::Lite
65 lib/SOAP/Transport/HTTP.pm
67 SOAP::Transport::HTTP::Client - Client interface to HTTP transport
68 SOAP::Transport::HTTP::Server - Server interface to HTTP transport
70 SOAP::Transport::HTTP::CGI - CGI implementation of server interface
72 SOAP::Transport::HTTP::Daemon - Daemon implementation of server
74 interface
75 SOAP::Transport::HTTP::Apache - mod_perl implementation of server
77 interface
78 lib/SOAP/Transport/POP3.pm
80 SOAP::Transport::POP3::Server - Server interface to POP3 protocol
81 lib/SOAP/Transport/MAILTO.pm
83 SOAP::Transport::MAILTO::Client - Client interface to SMTP/sendmail
84 lib/SOAP/Transport/LOCAL.pm
86 SOAP::Transport::LOCAL::Client - Client interface to local
87 transport
88 lib/SOAP/Transport/TCP.pm
90 SOAP::Transport::TCP::Server - Server interface to TCP protocol
91 SOAP::Transport::TCP::Client - Client interface to TCP protocol
93 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 new(optional key/value pairs)
104 $client = SOAP::Lite->new(proxy => $endpoint)
105 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 transport(optional transport object)
112 $transp = $client->transport( );
113 Gets or sets the transport object used for sending/receiving SOAP
115 messages.
116 See SOAP::Transport for details.
118 serializer(optional serializer object)
120 $serial = $client->serializer( )
121 Gets or sets the serializer object used for creating XML messages.
123 See SOAP::Serializer for details.
125 packager(optional packager object)
127 $packager = $client->packager( )
128 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 See also: SOAP::Packager.
135 proxy(endpoint, optional extra arguments)
137 $client->proxy('http://soap.xml.info/ endPoint');
138 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 This method is actually an alias to the proxy method of
145 SOAP::Transport. It is the same as typing:
146 $client->transport( )->proxy(...arguments);
148 Extra parameters can be passed to proxy() - see below.
150 compress_threshold
152 See COMPRESSION in HTTP::Transport.
153 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 A common option is to create a instance of HTTP::Cookies and
159 pass it as cookie_jar option:
160 my $cookie_jar = HTTP::Cookies->new()
162 $client->proxy('http://www.example.org/webservice',
163 cookie_jar => $cookie_jar,
164 );
165 For example, if you wish to set the HTTP timeout for a SOAP::Lite
167 client to 5 seconds, use the following code:
168 my $soap = SOAP::Lite
170 ->uri($uri)
171 ->proxy($proxyUrl, timeout => 5 );
172 See LWP::UserAgent.
174 endpoint(optional new endpoint address)
176 $client->endpoint('http://soap.xml.info/ newPoint')
177 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 service(service URL)
187 $client->service('http://svc.perl.org/Svc.wsdl');
188 "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 outputxml(boolean)
195 $client->outputxml('true');
196 When set to a true value, the raw XML is returned by the call to a
198 remote method.
199 The default is to return a SOAP::SOM object (false).
201 autotype(boolean)
203 $client->autotype(0);
204 This method is a shortcut for:
206 $client->serializer->autotype(boolean);
208 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 readable(boolean)
214 $client->readable(1);
215 This method is a shortcut for:
217 $client->serializer->readable(boolean);
219 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 headerattr(hash reference of attributes)
227 $obj->headerattr({ attr1 => 'value' });
228 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 <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 The attributes, given to headerattr are placed into the Header as
248 <soap:Header attr1="value">
250 bodyattr(hash reference of attributes)
252 $obj->bodyattr({ attr1 => 'value' });
253 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 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 <soap:Envelope>
267 <soap:Body>
268 <myMethod xmlns="http://www.someuri.com">
269 <foo />
270 </myMethod>
271 </soap:Body>
272 </soap:Envelope>
273 Some .NET web services have been reported to require this XML
275 namespace idiom.
276 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 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 <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 use_prefix(boolean)
296 Deprecated. Use the "ns()" and "default_ns" methods described
297 above.
298 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 When use_prefix is set to 'true', serialized XML will look like
304 this:
305 <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 When use_prefix is set to 'false', serialized XML will look like
313 this:
314 <SOAP-ENV:Envelope ...attributes skipped>
316 <SOAP-ENV:Body>
317 <mymethod xmlns="urn:MyURI" />
318 </SOAP-ENV:Body>
319 </SOAP-ENV:Envelope>
320 Some .NET web services have been reported to require this XML
322 namespace idiom.
323 soapversion(optional value)
325 $client->soapversion('1.2');
326 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 The value should be either 1.1 or 1.2.
333 envprefix(QName)
335 $client->envprefix('env');
336 This method is a shortcut for:
338 $client->serializer->envprefix(QName);
340 Gets or sets the namespace prefix for the SOAP namespace. The
342 default is SOAP.
343 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 encprefix(QName)
349 $client->encprefix('enc');
350 This method is a shortcut for:
352 $client->serializer->encprefix(QName);
354 Gets or sets the namespace prefix for the encoding rules namespace.
356 The default value is SOAP-ENC.
357 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 encoding(encoding URN)
365 $client->encoding($soap_12_encoding_URN);
366 This method is a shortcut for:
368 $client->serializer->encoding(args);
370 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 typelookup
379 $client->typelookup;
380 This method is a shortcut for:
382 $client->serializer->typelookup;
384 Gives the application access to the type-lookup table from the
386 serializer object. See the section on SOAP::Serializer.
387 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 $client->uri($service_uri);
395 This method is a shortcut for:
397 $client->serializer->uri(service);
399 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 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 multirefinplace(boolean)
414 $client->multirefinplace(1);
415 This method is a shortcut for:
417 $client->serializer->multirefinplace(boolean);
419 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 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 self
440 $ref = SOAP::Lite->self;
441 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 The following method isn't an accessor style of method but neither does
447 it fit with the group that immediately follows it:
448 call(arguments)
450 $client->call($method => @arguments);
451 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 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 on_action(callback)
467 $client->on_action(sub { qq("$_[0]") });
468 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 .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 $client->on_action( sub { join '/', @_ } );
482 on_fault(callback)
484 $client->on_fault(sub { popup_dialog($_[1]) });
485 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 on_nonserialized(callback)
495 $client->on_nonserialized(sub { die "$_[0]?!?" });
496 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 on_debug(callback)
508 $client->on_debug(sub { print @_ });
509 Deprecated. Use the global +debug and +trace facilities described
511 in SOAP::Trace
512 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 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 We will use "Martin Kutter" as the name for the call, so all variants
526 will print the following message on success:
527 Hello Martin Kutter!
529 SOAP message styles
531 There are three common (and one less common) variants of SOAP messages.
532 These address the message style (positional parameters vs. specified
534 message documents) and encoding (as-is vs. typed).
535 The different message styles are:
537 • rpc/encoded
539 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 • rpc/literal
545 As-is, positional parameters. The type of arguments is defined by
547 some pre-exchanged interface definition.
548 • document/encoded
550 Specified message with typed elements. Rarely used.
552 • document/literal
554 Specified message with as-is elements. The message specification
556 and element types are defined by some pre-exchanged interface
557 definition.
558 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 You will see clients for the rpc/encoded and document/literal SOAP
564 variants in this section.
565 Example implementations
567 RPC/ENCODED
568 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 Method: sayHello(string, string)
574 Parameters:
575 name: string
576 givenName: string
577 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 The message corresponding to this description looks somewhat like this:
583 <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 Any XML tag names may be used instead of the "s-gensym01" stuff -
590 parameters are positional, the tag names have no meaning.
591 A client producing such a call is implemented like this:
593 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 You can of course use a one-liner, too...
602 Sometimes, rpc/encoded interfaces are described with WSDL definitions.
604 A WSDL accepting "named" parameters with rpc/encoded looks like this:
605 <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 <portType name="Service1Soap">
624 <operation name="sayHello">
625 <input message="s0:sayHello" />
626 <output message="s0:sayHelloResponse" />
627 </operation>
628 </portType>
629 <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 The message corresponding to this schema looks like this:
653 <sayHello xmlns="urn:HelloWorld">
655 <name xsi:type="xsd:string">Kutter</name>
656 <givenName xsi:type="xsd:string">Martin</givenName>
657 </sayHello>
658 A web service client using this schema looks like this:
660 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 You may of course also use the following one-liner:
670 perl -MSOAP::Lite -e 'print SOAP::Lite->service("file:say_hello_rpcenc.wsdl")\
672 ->sayHello('Kutter', 'Martin'), "\n";'
673 A web service client (without a service description) looks like this.
675 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 RPC/LITERAL
687 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 <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 <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 <portType name="Service1Soap">
724 <operation name="sayHello">
725 <input message="s0:sayHello" />
726 <output message="s0:sayHelloResponse" />
727 </operation>
728 </portType>
729 <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 The XML message (inside the SOAP Envelope) look like this:
751 <ns0:sayHello xmlns:ns0="urn:HelloWorld">
753 <parameters>
754 <name>Kutter</name>
755 <givenName>Martin</givenName>
756 </parameters>
757 </ns0:sayHello>
758 <sayHelloResponse xmlns:ns0="urn:HelloWorld">
760 <parameters>
761 <sayHelloResult>Hello Martin Kutter!</sayHelloResult>
762 </parameters>
763 </sayHelloResponse>
764 This is the SOAP::Lite implementation for the web service client:
766 use SOAP::Lite +trace;
768 my $soap = SOAP::Lite->new( proxy => 'http://localhost:80/helloworld.pl');
769 $soap->on_action( sub { "urn:HelloWorld#sayHello" });
771 $soap->autotype(0)->readable(1);
772 $soap->default_ns('urn:HelloWorld');
773 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 die $som->fault->{ faultstring } if ($som->fault);
782 print $som->result, "\n";
783 DOCUMENT/LITERAL
785 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 <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 <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 <portType name="Service1Soap">
822 <operation name="sayHello">
823 <input message="s0:sayHelloSoapIn" />
824 <output message="s0:sayHelloSoapOut" />
825 </operation>
826 </portType>
827 <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 The XML message (inside the SOAP Envelope) look like this:
849 <sayHello xmlns="urn:HelloWorld">
851 <name>Kutter</name>
852 <givenName>Martin</givenName>
853 </sayHello>
854 <sayHelloResponse>
856 <sayHelloResult>Hello Martin Kutter!</sayHelloResult>
857 </sayHelloResponse>
858 You can call this web service with the following client code:
860 use SOAP::Lite;
862 my $soap = SOAP::Lite->new( proxy => 'http://localhost:80/helloworld.pl');
863 $soap->on_action( sub { "urn:HelloWorld#sayHello" });
865 $soap->autotype(0);
866 $soap->default_ns('urn:HelloWorld');
867 my $som = $soap->call("sayHello",
869 SOAP::Data->name('name')->value( 'Kutter' ),
870 SOAP::Data->name('givenName')->value('Martin'),
871 );
872 die $som->fault->{ faultstring } if ($som->fault);
874 print $som->result, "\n";
875 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 In our example, the rpc/encoded variant already used named parameters
884 (by using two messages), so there's no difference at all.
885 You may have noticed the somewhat strange idiom for passing a list of
887 named parameters in the rpc/literal example:
888 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 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 EXAMPLES
909 Client sending an attachment
911 "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 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 Client retrieving an attachment
931 A client accessing attachments that were returned in a response by
933 using the "SOAP::SOM::parts()" accessor.
934 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 Server receiving an attachment
946 Servers, like clients, use the SOAP::SOM module to access attachments
948 transmitted to it.
949 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 Server responding with an attachment
966 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 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 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 If you wish to provide common "proxy()" or "uri()" settings for all
996 "SOAP::Lite" objects in your application you may do:
997 use SOAP::Lite
999 proxy => 'http://localhost/cgi-bin/soap.cgi',
1000 uri => 'http://my.own.com/My/Examples';
1001 my $soap1 = new SOAP::Lite; # will get the same proxy()/uri() as above
1003 print $soap1->getStateName(1)->result;
1004 my $soap2 = SOAP::Lite->new; # same thing as above
1006 print $soap2->getStateName(2)->result;
1007 # or you may override any settings you want
1009 my $soap3 = SOAP::Lite->proxy('http://localhost/');
1010 print $soap3->getStateName(1)->result;
1011 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 SOAP::Lite->self(undef);
1019 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 use SOAP::Lite
1027 on_action => sub {sprintf '%s#%s', @_};
1028 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 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 use SOAP::Lite proxy => 'http://localhost/';
1038 print SOAP::Lite->getStateName(1)->result;
1039 use SOAP::Lite proxy => 'http://localhost/cgi-bin/soap.cgi';
1041 print SOAP::Lite->getStateName(1)->result;
1042 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 eval "use SOAP::Lite proxy => 'http://localhost/cgi-bin/soap.cgi'; 1" or die;
1047 Or alternatively,
1049 SOAP::Lite->self->proxy('http://localhost/cgi-bin/soap.cgi');
1051 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 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 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 <mehodResponse>
1071 <res1>name1</res1>
1072 <res2>name2</res2>
1073 <res3>name3</res3>
1074 </mehodResponse>
1075 In that case:
1077 $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 or
1084 @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 Generally, if server returns "return (1,2,3)" you will get 1 as the
1090 result and 2 and 3 as out parameters.
1091 If the server returns "return [1,2,3]" you will get an ARRAY reference
1093 from "result()" and "undef" from "paramsout()".
1094 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 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 Server Code:
1105 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 Client Code:
1114 $a = 10;
1116 $b = SOAP::Data->name('myparam' => 12);
1117 $result = $soap->mymethod($a, $b);
1118 After that, "$result == 10 and $b->value == 24"! Magic? Sort of.
1120 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 Server Code:
1127 package My::PingPong;
1129 sub new {
1131 my $self = shift;
1132 my $class = ref($self) || $self;
1133 bless {_num=>shift} => $class;
1134 }
1135 sub next {
1137 my $self = shift;
1138 $self->{_num}++;
1139 }
1140 Client Code:
1142 use SOAP::Lite +autodispatch =>
1144 uri => 'urn:',
1145 proxy => 'http://localhost/';
1146 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 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 When statically deploying a SOAP Server, you need to know all modules
1160 handling SOAP requests before.
1161 Dynamic deployment allows extending your SOAP Server's interface by
1163 just installing another module into the dispatch_to path (see below).
1164 STATIC DEPLOYMENT EXAMPLE
1166 use SOAP::Transport::HTTP;
1168 use My::Examples; # module is preloaded
1169 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 For static deployment you should specify the MODULE name directly.
1177 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 DYNAMIC DEPLOYMENT EXAMPLE
1182 use SOAP::Transport::HTTP;
1184 # name is unknown, module will be loaded on demand
1185 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 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 SUMMARY
1198 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 # 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 # 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 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 For example:
1226 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 "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 See also: EXAMPLE APACHE::REGISTRY USAGE, "SECURITY"
1240 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 Note: Compression currently only works for HTTP based servers and
1248 clients.
1249 Client Code
1251 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 Server Code
1259 my $server = SOAP::Transport::HTTP::CGI
1261 ->dispatch_to('My::Parameters')
1262 ->options({compress_threshold => 10000})
1263 ->handle;
1264 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 1. Switch to static linking:
1274 use MODULE;
1276 $server->dispatch_to('MODULE');
1277 Which can also be useful when you want to import something specific
1279 from the deployed modules:
1280 use MODULE qw(import_list);
1282 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 3. Wrap "use" in an "eval" block:
1289 eval 'use MODULE qw(import_list)'; die if $@;
1291 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 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 return SOAP::Data->name('myname')
1304 ->type('string')
1305 ->uri($MY_NAMESPACE)
1306 ->value($output);
1307 In addition see comment about default encoding in .NET Web Services
1309 below.
1310 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 Declare a proper soapAction in your call
1317 For example, use "on_action( sub {
1318 'http://www.myuri.com/WebService.aspx#someMethod'; } )".
1319 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 Server found request content type to be 'text/xml; charset=utf-8',
1327 but expected 'text/xml'
1328 To turn off this behavior specify use the following code:
1330 use SOAP::Lite;
1332 $SOAP::Constants::DO_NOT_USE_CHARSET = 1;
1333 # The rest of your code
1334 Use fully qualified name for method parameters
1336 For example, the following code is preferred:
1337 SOAP::Data->name(Query => 'biztalk')
1339 ->uri('http://tempuri.org/')
1340 As opposed to:
1342 SOAP::Data->name('Query' => 'biztalk')
1344 Place method in default namespace
1346 For example, the following code is preferred:
1347 my $method = SOAP::Data->name('add')
1349 ->attr({xmlns => 'http://tempuri.org/'});
1350 my @rc = $soap->call($method => @parms)->result;
1351 As opposed to:
1353 my @rc = $soap->call(add => @parms)->result;
1355 # -- OR --
1356 my @rc = $soap->add(@parms)->result;
1357 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 <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 SOAP::Lite allows users to disable the use of explicit namespaces
1370 through the "use_prefix()" method. For example, the following code:
1371 $som = SOAP::Lite->uri('urn:MyURI')
1373 ->proxy($HOST)
1374 ->use_prefix(0)
1375 ->myMethod();
1376 Will result in the following XML, which is more palatable by .NET:
1378 <SOAP-ENV:Envelope ...attributes skipped>
1380 <SOAP-ENV:Body>
1381 <mymethod xmlns="urn:MyURI" />
1382 </SOAP-ENV:Body>
1383 </SOAP-ENV:Envelope>
1384 Modify your .NET server, if possible
1386 Stefan Pharies <stefanph@microsoft.com>:
1387 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 [SoapService(Style=SoapServiceStyle.RPC)]
1397 Another source said it might be this attribute (for Beta 2):
1399 [SoapRpcService]
1401 Full Web Service text may look like:
1403 <%@ WebService Language="C#" Class="Test" %>
1405 using System;
1406 using System.Web.Services;
1407 using System.Xml.Serialization;
1408 [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 Another example from Kirill Gavrylyuk <kirillg@microsoft.com>:
1418 "You can insert [SoapRpcService()] attribute either on your class
1420 or on operation level".
1421 <%@ WebService Language=CS class="DataType.StringTest"%>
1423 namespace DataType {
1425 using System;
1427 using System.Web.Services;
1428 using System.Web.Services.Protocols;
1429 using System.Web.Services.Description;
1430 [SoapRpcService()]
1432 public class StringTest: WebService {
1433 [WebMethod]
1434 [SoapRpcMethod()]
1435 public string RetString(string x) {
1436 return(x);
1437 }
1438 }
1439 }
1440 Example from Yann Christensen <yannc@microsoft.com>:
1442 using System;
1444 using System.Web.Services;
1445 using System.Web.Services.Protocols;
1446 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 Special thanks goes to the following people for providing the above
1459 description and details on .NET interoperability issues:
1460 Petr Janata <petr.janata@i.cz>,
1462 Stefan Pharies <stefanph@microsoft.com>,
1464 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 You may force the type by passing a SOAP::Data object with a type
1475 specified:
1476 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 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 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 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 See SOAP::Serializer for more details.
1498 "+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 use Some::Module;
1506 use SOAP::Lite +autodispatch =>
1507 uri => 'urn:Foo'
1508 proxy => 'http://...';
1509 You would do something like this:
1511 use SOAP::Lite dispatch_from(Some::Module) =>
1513 uri => 'urn:Foo'
1514 proxy => 'http://...';
1515 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 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 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 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 Then try placing the following into your httpd.conf file and see if
1539 it fixes your problem.
1540 <IfModule mod_env.c>
1542 PassEnv LD_LIBRARY_PATH
1543 </IfModule>
1544 SOAP client reports "500 unexpected EOF before status line seen
1546 See "Apache is crashing with segfaults"
1547 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 RULE_EXPAT=no
1554 If you are using Apache 1.3.20 and later, try configuring Apache
1556 with the following option:
1557 ./configure --disable-rule=EXPAT
1559 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 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 Thanks to Tim Bunce <Tim.Bunce@pobox.com>.
1569 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 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 http://www.megginson.com/SAX/index.html
1585 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 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 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 my $soap = new SOAP::Lite
1622 serializer => My::Serializer->new,
1623 ..... other parameters
1624 or on server side:
1626 my $server = new SOAP::Transport::HTTP::Daemon # or any other server
1628 serializer => My::Serializer->new,
1629 ..... other parameters
1630 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 *SOAP::Serializer::as_string = \&SOAP::XMLSchema2001::Serializer::as_base64Binary;
1637 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 • Limited support for WSDL schema.
1649 • XML::Parser::Lite relies on Unicode support in Perl and doesn't do
1651 entity decoding.
1652 • Limited support for mustUnderstand and Actor attributes.
1654
1656 MacOS
1657 Information about XML::Parser for MacPerl could be found here:
1658 http://bumppo.net/lists/macperl-modules/1999/07/msg00047.html
1660 Compiled XML::Parser for MacOS could be found here:
1662 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 • SOAP-Transport-HTTP-Nginx
1673 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 * CPAN: http://search.cpan.org/search?dist=SOAP-Lite
1682 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 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 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 git@github.com:redhotpenguin/perl-soaplite.git
1703 Also see the HACKING file.
1705 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 Copyright (C) 2007-2008 Martin Kutter
1716 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 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 Randy J. Ray (rjray@blackperl.com)
1731 Byrne Reese (byrne@majordojo.com)
1733 Martin Kutter (martin.kutter@fen-net.de)
1735 Fred Moyer (fred@redhotpenguin.com)
1737perl v5.32.1 2021-01-27 SOAP::Lite(3)