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 the
263 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 above.
297 Shortcut for "serializer->use_prefix()". This lets you turn on/off
299 the use of a namespace prefix for the children of the
300 /Envelope/Body element. Default is 'true'.
301 When use_prefix is set to 'true', serialized XML will look like
303 this:
304 <SOAP-ENV:Envelope ...attributes skipped>
306 <SOAP-ENV:Body>
307 <namesp1:mymethod xmlns:namesp1="urn:MyURI" />
308 </SOAP-ENV:Body>
309 </SOAP-ENV:Envelope>
310 When use_prefix is set to 'false', serialized XML will look like
312 this:
313 <SOAP-ENV:Envelope ...attributes skipped>
315 <SOAP-ENV:Body>
316 <mymethod xmlns="urn:MyURI" />
317 </SOAP-ENV:Body>
318 </SOAP-ENV:Envelope>
319 Some .NET web services have been reported to require this XML
321 namespace idiom.
322 soapversion(optional value)
324 $client->soapversion('1.2');
325 If no parameter is given, returns the current version of SOAP that
327 is being used by the client object to encode requests. If a
328 parameter is given, the method attempts to set that as the version
329 of SOAP being used.
330 The value should be either 1.1 or 1.2.
332 envprefix(QName)
334 $client->envprefix('env');
335 This method is a shortcut for:
337 $client->serializer->envprefix(QName);
339 Gets or sets the namespace prefix for the SOAP namespace. The
341 default is SOAP.
342 The prefix itself has no meaning, but applications may wish to
344 chose one explicitly to denote different versions of SOAP or the
345 like.
346 encprefix(QName)
348 $client->encprefix('enc');
349 This method is a shortcut for:
351 $client->serializer->encprefix(QName);
353 Gets or sets the namespace prefix for the encoding rules namespace.
355 The default value is SOAP-ENC.
356 While it may seem to be an unnecessary operation to set a value that
358 isn't relevant to the message, such as the namespace labels for the
359 envelope and encoding URNs, the ability to set these labels explicitly
360 can prove to be a great aid in distinguishing and debugging messages on
361 the server side of operations.
362 encoding(encoding URN)
364 $client->encoding($soap_12_encoding_URN);
365 This method is a shortcut for:
367 $client->serializer->encoding(args);
369 Where the earlier method dealt with the label used for the
371 attributes related to the SOAP encoding scheme, this method
372 actually sets the URN to be specified as the encoding scheme for
373 the message. The default is to specify the encoding for SOAP 1.1,
374 so this is handy for applications that need to encode according to
375 SOAP 1.2 rules.
376 typelookup
378 $client->typelookup;
379 This method is a shortcut for:
381 $client->serializer->typelookup;
383 Gives the application access to the type-lookup table from the
385 serializer object. See the section on SOAP::Serializer.
386 uri(service specifier)
388 Deprecated - the "uri" subroutine is deprecated in order to provide
389 a more intuitive naming scheme for subroutines that set namespaces.
390 In the future, you will be required to use either the ns() or
391 default_ns() subroutines instead of uri().
392 $client->uri($service_uri);
394 This method is a shortcut for:
396 $client->serializer->uri(service);
398 The URI associated with this accessor on a client object is the
400 service-specifier for the request, often encoded for HTTP-based
401 requests as the SOAPAction header. While the names may seem
402 confusing, this method doesn't specify the endpoint itself. In most
403 circumstances, the "uri" refers to the namespace used for the
404 request.
405 Often times, the value may look like a valid URL. Despite this, it
407 doesn't have to point to an existing resource (and often doesn't).
408 This method sets and retrieves this value from the object. Note
409 that no transport code is triggered by this because it has no
410 direct effect on the transport of the object.
411 multirefinplace(boolean)
413 $client->multirefinplace(1);
414 This method is a shortcut for:
416 $client->serializer->multirefinplace(boolean);
418 Controls how the serializer handles values that have multiple
420 references to them. Recall from previous SOAP chapters that a value
421 may be tagged with an identifier, then referred to in several
422 places. When this is the case for a value, the serializer defaults
423 to putting the data element towards the top of the message, right
424 after the opening tag of the method-specification. It is serialized
425 as a standalone entity with an ID that is then referenced at the
426 relevant places later on. If this method is used to set a true
427 value, the behavior is different. When the multirefinplace
428 attribute is true, the data is serialized at the first place that
429 references it, rather than as a separate element higher up in the
430 body. This is more compact but may be harder to read or trace in a
431 debugging environment.
432 parts( ARRAY )
434 Used to specify an array of MIME::Entity's to be attached to the
435 transmitted SOAP message. Attachments that are returned in a
436 response can be accessed by SOAP::SOM::parts().
437 self
439 $ref = SOAP::Lite->self;
440 Returns an object reference to the default global object the
442 "SOAP::Lite" package maintains. This is the object that processes
443 many of the arguments when provided on the use line.
444 The following method isn't an accessor style of method but neither does
446 it fit with the group that immediately follows it:
447 call(arguments)
449 $client->call($method => @arguments);
450 As has been illustrated in previous chapters, the "SOAP::Lite"
452 client objects can manage remote calls with auto-dispatching using
453 some of Perl's more elaborate features. call is used when the
454 application wants a greater degree of control over the details of
455 the call itself. The method may be built up from a SOAP::Data
456 object, so as to allow full control over the namespace associated
457 with the tag, as well as other attributes like encoding. This is
458 also important for calling methods that contain characters not
459 allowable in Perl function names, such as A.B.C.
460 The next four methods used in the "SOAP::Lite" class are geared towards
462 handling the types of events than can occur during the message
463 lifecycle. Each of these sets up a callback for the event in question:
464 on_action(callback)
466 $client->on_action(sub { qq("$_[0]") });
467 Triggered when the transport object sets up the SOAPAction header
469 for an HTTP-based call. The default is to set the header to the
470 string, uri#method, in which URI is the value set by the uri method
471 described earlier, and method is the name of the method being
472 called. When called, the routine referenced (or the closure, if
473 specified as in the example) is given two arguments, uri and
474 method, in that order.
475 .NET web services usually expect "/" as separator for "uri" and
477 "method". To change SOAP::Lite's behaviour to use uri/method as
478 SOAPAction header, use the following code:
479 $client->on_action( sub { join '/', @_ } );
481 on_fault(callback)
483 $client->on_fault(sub { popup_dialog($_[1]) });
484 Triggered when a method call results in a fault response from the
486 server. When it is called, the argument list is first the client
487 object itself, followed by the object that encapsulates the fault.
488 In the example, the fault object is passed (without the client
489 object) to a hypothetical GUI function that presents an error
490 dialog with the text of fault extracted from the object (which is
491 covered shortly under the SOAP::SOM methods).
492 on_nonserialized(callback)
494 $client->on_nonserialized(sub { die "$_[0]?!?" });
495 Occasionally, the serializer may be given data it can't turn into
497 SOAP-savvy XML; for example, if a program bug results in a code
498 reference or something similar being passed in as a parameter to
499 method call. When that happens, this callback is activated, with
500 one argument. That argument is the data item that could not be
501 understood. It will be the only argument. If the routine returns,
502 the return value is pasted into the message as the serialization.
503 Generally, an error is in order, and this callback allows for
504 control over signaling that error.
505 on_debug(callback)
507 $client->on_debug(sub { print @_ });
508 Deprecated. Use the global +debug and +trace facilities described
510 in SOAP::Trace
511 Note that this method will not work as expected: Instead of
513 affecting the debugging behaviour of the object called on, it will
514 globally affect the debugging behaviour for all objects of that
515 class.
516
518 This chapter guides you to writing a SOAP client by example.
519 The SOAP service to be accessed is a simple variation of the well-known
521 hello world program. It accepts two parameters, a name and a given
522 name, and returns "Hello $given_name $name".
523 We will use "Martin Kutter" as the name for the call, so all variants
525 will print the following message on success:
526 Hello Martin Kutter!
528 SOAP message styles
530 There are three common (and one less common) variants of SOAP messages.
531 These address the message style (positional parameters vs. specified
533 message documents) and encoding (as-is vs. typed).
534 The different message styles are:
536 • rpc/encoded
538 Typed, positional parameters. Widely used in scripting languages.
540 The type of the arguments is included in the message. Arrays and
541 the like may be encoded using SOAP encoding rules (or others).
542 • rpc/literal
544 As-is, positional parameters. The type of arguments is defined by
546 some pre-exchanged interface definition.
547 • document/encoded
549 Specified message with typed elements. Rarely used.
551 • document/literal
553 Specified message with as-is elements. The message specification
555 and element types are defined by some pre-exchanged interface
556 definition.
557 As of 2008, document/literal has become the predominant SOAP message
559 variant. rpc/literal and rpc/encoded are still in use, mainly with
560 scripting languages, while document/encoded is hardly used at all.
561 You will see clients for the rpc/encoded and document/literal SOAP
563 variants in this section.
564 Example implementations
566 RPC/ENCODED
567 Rpc/encoded is most popular with scripting languages like perl, php and
569 python without the use of a WSDL. Usual method descriptions look like
570 this:
571 Method: sayHello(string, string)
573 Parameters:
574 name: string
575 givenName: string
576 Such a description usually means that you can call a method named
578 "sayHello" with two positional parameters, "name" and "givenName",
579 which both are strings.
580 The message corresponding to this description looks somewhat like this:
582 <sayHello xmlns="urn:HelloWorld">
584 <s-gensym01 xsi:type="xsd:string">Kutter</s-gensym01>
585 <s-gensym02 xsi:type="xsd:string">Martin</s-gensym02>
586 </sayHello>
587 Any XML tag names may be used instead of the "s-gensym01" stuff -
589 parameters are positional, the tag names have no meaning.
590 A client producing such a call is implemented like this:
592 use SOAP::Lite;
594 my $soap = SOAP::Lite->new( proxy => 'http://localhost:81/soap-wsdl-test/helloworld.pl');
595 $soap->default_ns('urn:HelloWorld');
596 my $som = $soap->call('sayHello', 'Kutter', 'Martin');
597 die $som->faultstring if ($som->fault);
598 print $som->result, "\n";
599 You can of course use a one-liner, too...
601 Sometimes, rpc/encoded interfaces are described with WSDL definitions.
603 A WSDL accepting "named" parameters with rpc/encoded looks like this:
604 <definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
606 xmlns:s="http://www.w3.org/2001/XMLSchema"
607 xmlns:s0="urn:HelloWorld"
608 targetNamespace="urn:HelloWorld"
609 xmlns="http://schemas.xmlsoap.org/wsdl/">
610 <types>
611 <s:schema targetNamespace="urn:HelloWorld">
612 </s:schema>
613 </types>
614 <message name="sayHello">
615 <part name="name" type="s:string" />
616 <part name="givenName" type="s:string" />
617 </message>
618 <message name="sayHelloResponse">
619 <part name="sayHelloResult" type="s:string" />
620 </message>
621 <portType name="Service1Soap">
623 <operation name="sayHello">
624 <input message="s0:sayHello" />
625 <output message="s0:sayHelloResponse" />
626 </operation>
627 </portType>
628 <binding name="Service1Soap" type="s0:Service1Soap">
630 <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
631 style="rpc" />
632 <operation name="sayHello">
633 <soap:operation soapAction="urn:HelloWorld#sayHello"/>
634 <input>
635 <soap:body use="encoded"
636 encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
637 </input>
638 <output>
639 <soap:body use="encoded"
640 encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
641 </output>
642 </operation>
643 </binding>
644 <service name="HelloWorld">
645 <port name="HelloWorldSoap" binding="s0:Service1Soap">
646 <soap:address location="http://localhost:81/soap-wsdl-test/helloworld.pl" />
647 </port>
648 </service>
649 </definitions>
650 The message corresponding to this schema looks like this:
652 <sayHello xmlns="urn:HelloWorld">
654 <name xsi:type="xsd:string">Kutter</name>
655 <givenName xsi:type="xsd:string">Martin</givenName>
656 </sayHello>
657 A web service client using this schema looks like this:
659 use SOAP::Lite;
661 my $soap = SOAP::Lite->service("file:say_hello_rpcenc.wsdl");
662 eval { my $result = $soap->sayHello('Kutter', 'Martin'); };
663 if ($@) {
664 die $@;
665 }
666 print $som->result();
667 You may of course also use the following one-liner:
669 perl -MSOAP::Lite -e 'print SOAP::Lite->service("file:say_hello_rpcenc.wsdl")\
671 ->sayHello('Kutter', 'Martin'), "\n";'
672 A web service client (without a service description) looks like this.
674 use SOAP::Lite;
676 my $soap = SOAP::Lite->new( proxy => 'http://localhost:81/soap-wsdl-test/helloworld.pl');
677 $soap->default_ns('urn:HelloWorld');
678 my $som = $soap->call('sayHello',
679 SOAP::Data->name('name')->value('Kutter'),
680 SOAP::Data->name('givenName')->value('Martin')
681 );
682 die $som->faultstring if ($som->fault);
683 print $som->result, "\n";
684 RPC/LITERAL
686 SOAP web services using the document/literal message encoding are
688 usually described by some Web Service Definition. Our web service has
689 the following WSDL description:
690 <definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
692 xmlns:s="http://www.w3.org/2001/XMLSchema"
693 xmlns:s0="urn:HelloWorld"
694 targetNamespace="urn:HelloWorld"
695 xmlns="http://schemas.xmlsoap.org/wsdl/">
696 <types>
697 <s:schema targetNamespace="urn:HelloWorld">
698 <s:complexType name="sayHello">
699 <s:sequence>
700 <s:element minOccurs="0" maxOccurs="1" name="name"
701 type="s:string" />
702 <s:element minOccurs="0" maxOccurs="1" name="givenName"
703 type="s:string" nillable="1" />
704 </s:sequence>
705 </s:complexType>
706 <s:complexType name="sayHelloResponse">
708 <s:sequence>
709 <s:element minOccurs="0" maxOccurs="1" name="sayHelloResult"
710 type="s:string" />
711 </s:sequence>
712 </s:complexType>
713 </s:schema>
714 </types>
715 <message name="sayHello">
716 <part name="parameters" type="s0:sayHello" />
717 </message>
718 <message name="sayHelloResponse">
719 <part name="parameters" type="s0:sayHelloResponse" />
720 </message>
721 <portType name="Service1Soap">
723 <operation name="sayHello">
724 <input message="s0:sayHello" />
725 <output message="s0:sayHelloResponse" />
726 </operation>
727 </portType>
728 <binding name="Service1Soap" type="s0:Service1Soap">
730 <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
731 style="rpc" />
732 <operation name="sayHello">
733 <soap:operation soapAction="urn:HelloWorld#sayHello"/>
734 <input>
735 <soap:body use="literal" namespace="urn:HelloWorld"/>
736 </input>
737 <output>
738 <soap:body use="literal" namespace="urn:HelloWorld"/>
739 </output>
740 </operation>
741 </binding>
742 <service name="HelloWorld">
743 <port name="HelloWorldSoap" binding="s0:Service1Soap">
744 <soap:address location="http://localhost:80//helloworld.pl" />
745 </port>
746 </service>
747 </definitions>
748 The XML message (inside the SOAP Envelope) look like this:
750 <ns0:sayHello xmlns:ns0="urn:HelloWorld">
752 <parameters>
753 <name>Kutter</name>
754 <givenName>Martin</givenName>
755 </parameters>
756 </ns0:sayHello>
757 <sayHelloResponse xmlns:ns0="urn:HelloWorld">
759 <parameters>
760 <sayHelloResult>Hello Martin Kutter!</sayHelloResult>
761 </parameters>
762 </sayHelloResponse>
763 This is the SOAP::Lite implementation for the web service client:
765 use SOAP::Lite +trace;
767 my $soap = SOAP::Lite->new( proxy => 'http://localhost:80/helloworld.pl');
768 $soap->on_action( sub { "urn:HelloWorld#sayHello" });
770 $soap->autotype(0)->readable(1);
771 $soap->default_ns('urn:HelloWorld');
772 my $som = $soap->call('sayHello', SOAP::Data->name('parameters')->value(
774 \SOAP::Data->value([
775 SOAP::Data->name('name')->value( 'Kutter' ),
776 SOAP::Data->name('givenName')->value('Martin'),
777 ]))
778 );
779 die $som->fault->{ faultstring } if ($som->fault);
781 print $som->result, "\n";
782 DOCUMENT/LITERAL
784 SOAP web services using the document/literal message encoding are
786 usually described by some Web Service Definition. Our web service has
787 the following WSDL description:
788 <definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
790 xmlns:s="http://www.w3.org/2001/XMLSchema"
791 xmlns:s0="urn:HelloWorld"
792 targetNamespace="urn:HelloWorld"
793 xmlns="http://schemas.xmlsoap.org/wsdl/">
794 <types>
795 <s:schema targetNamespace="urn:HelloWorld">
796 <s:element name="sayHello">
797 <s:complexType>
798 <s:sequence>
799 <s:element minOccurs="0" maxOccurs="1" name="name" type="s:string" />
800 <s:element minOccurs="0" maxOccurs="1" name="givenName" type="s:string" nillable="1" />
801 </s:sequence>
802 </s:complexType>
803 </s:element>
804 <s:element name="sayHelloResponse">
806 <s:complexType>
807 <s:sequence>
808 <s:element minOccurs="0" maxOccurs="1" name="sayHelloResult" type="s:string" />
809 </s:sequence>
810 </s:complexType>
811 </s:element>
812 </types>
813 <message name="sayHelloSoapIn">
814 <part name="parameters" element="s0:sayHello" />
815 </message>
816 <message name="sayHelloSoapOut">
817 <part name="parameters" element="s0:sayHelloResponse" />
818 </message>
819 <portType name="Service1Soap">
821 <operation name="sayHello">
822 <input message="s0:sayHelloSoapIn" />
823 <output message="s0:sayHelloSoapOut" />
824 </operation>
825 </portType>
826 <binding name="Service1Soap" type="s0:Service1Soap">
828 <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
829 style="document" />
830 <operation name="sayHello">
831 <soap:operation soapAction="urn:HelloWorld#sayHello"/>
832 <input>
833 <soap:body use="literal" />
834 </input>
835 <output>
836 <soap:body use="literal" />
837 </output>
838 </operation>
839 </binding>
840 <service name="HelloWorld">
841 <port name="HelloWorldSoap" binding="s0:Service1Soap">
842 <soap:address location="http://localhost:80//helloworld.pl" />
843 </port>
844 </service>
845 </definitions>
846 The XML message (inside the SOAP Envelope) look like this:
848 <sayHello xmlns="urn:HelloWorld">
850 <name>Kutter</name>
851 <givenName>Martin</givenName>
852 </sayHello>
853 <sayHelloResponse>
855 <sayHelloResult>Hello Martin Kutter!</sayHelloResult>
856 </sayHelloResponse>
857 You can call this web service with the following client code:
859 use SOAP::Lite;
861 my $soap = SOAP::Lite->new( proxy => 'http://localhost:80/helloworld.pl');
862 $soap->on_action( sub { "urn:HelloWorld#sayHello" });
864 $soap->autotype(0);
865 $soap->default_ns('urn:HelloWorld');
866 my $som = $soap->call("sayHello",
868 SOAP::Data->name('name')->value( 'Kutter' ),
869 SOAP::Data->name('givenName')->value('Martin'),
870 );
871 die $som->fault->{ faultstring } if ($som->fault);
873 print $som->result, "\n";
874 Differences between the implementations
876 You may have noticed that there's little difference between the
877 rpc/encoded, rpc/literal and the document/literal example's
878 implementation. In fact, from SOAP::Lite's point of view, the only
879 differences between rpc/literal and document/literal that parameters
880 are always named.
881 In our example, the rpc/encoded variant already used named parameters
883 (by using two messages), so there's no difference at all.
884 You may have noticed the somewhat strange idiom for passing a list of
886 named parameters in the rpc/literal example:
887 my $som = $soap->call('sayHello', SOAP::Data->name('parameters')->value(
889 \SOAP::Data->value([
890 SOAP::Data->name('name')->value( 'Kutter' ),
891 SOAP::Data->name('givenName')->value('Martin'),
892 ]))
893 );
894 While SOAP::Data provides full control over the XML generated, passing
896 hash-like structures require additional coding.
897
899 See SOAP::Server, or SOAP::Transport.
900
902 ATTACHMENTS
903 "SOAP::Lite" features support for the SOAP with Attachments
904 specification. Currently, SOAP::Lite only supports MIME based
905 attachments. DIME based attachments are yet to be fully functional.
906 EXAMPLES
908 Client sending an attachment
910 "SOAP::Lite" clients can specify attachments to be sent along with a
912 request by using the SOAP::Lite::parts() method, which takes as an
913 argument an ARRAY of "MIME::Entity"'s.
914 use SOAP::Lite;
916 use MIME::Entity;
917 my $ent = build MIME::Entity
918 Type => "image/gif",
919 Encoding => "base64",
920 Path => "somefile.gif",
921 Filename => "saveme.gif",
922 Disposition => "attachment";
923 my $som = SOAP::Lite
924 ->uri($SOME_NAMESPACE)
925 ->parts([ $ent ])
926 ->proxy($SOME_HOST)
927 ->some_method(SOAP::Data->name("foo" => "bar"));
928 Client retrieving an attachment
930 A client accessing attachments that were returned in a response by
932 using the SOAP::SOM::parts() accessor.
933 use SOAP::Lite;
935 use MIME::Entity;
936 my $soap = SOAP::Lite
937 ->uri($NS)
938 ->proxy($HOST);
939 my $som = $soap->foo();
940 foreach my $part (${$som->parts}) {
941 print $part->stringify;
942 }
943 Server receiving an attachment
945 Servers, like clients, use the SOAP::SOM module to access attachments
947 transmitted to it.
948 package Attachment;
950 use SOAP::Lite;
951 use MIME::Entity;
952 use strict;
953 use vars qw(@ISA);
954 @ISA = qw(SOAP::Server::Parameters);
955 sub someMethod {
956 my $self = shift;
957 my $envelope = pop;
958 foreach my $part (@{$envelope->parts}) {
959 print "AttachmentService: attachment found! (".ref($part).")\n";
960 }
961 # do something
962 }
963 Server responding with an attachment
965 Servers wishing to return an attachment to the calling client need only
967 return "MIME::Entity" objects along with SOAP::Data elements, or any
968 other data intended for the response.
969 package Attachment;
971 use SOAP::Lite;
972 use MIME::Entity;
973 use strict;
974 use vars qw(@ISA);
975 @ISA = qw(SOAP::Server::Parameters);
976 sub someMethod {
977 my $self = shift;
978 my $envelope = pop;
979 my $ent = build MIME::Entity
980 'Id' => "<1234>",
981 'Type' => "text/xml",
982 'Path' => "some.xml",
983 'Filename' => "some.xml",
984 'Disposition' => "attachment";
985 return SOAP::Data->name("foo" => "blah blah blah"),$ent;
986 }
987 DEFAULT SETTINGS
989 Though this feature looks similar to autodispatch they have (almost)
990 nothing in common. This capability allows you specify default settings
991 so that all objects created after that will be initialized with the
992 proper default settings.
993 If you wish to provide common proxy() or uri() settings for all
995 "SOAP::Lite" objects in your application you may do:
996 use SOAP::Lite
998 proxy => 'http://localhost/cgi-bin/soap.cgi',
999 uri => 'http://my.own.com/My/Examples';
1000 my $soap1 = new SOAP::Lite; # will get the same proxy()/uri() as above
1002 print $soap1->getStateName(1)->result;
1003 my $soap2 = SOAP::Lite->new; # same thing as above
1005 print $soap2->getStateName(2)->result;
1006 # or you may override any settings you want
1008 my $soap3 = SOAP::Lite->proxy('http://localhost/');
1009 print $soap3->getStateName(1)->result;
1010 Any "SOAP::Lite" properties can be propagated this way. Changes in
1012 object copies will not affect global settings and you may still change
1013 global settings with "SOAP::Lite->self" call which returns reference to
1014 global object. Provided parameter will update this object and you can
1015 even set it to "undef":
1016 SOAP::Lite->self(undef);
1018 The "use SOAP::Lite" syntax also lets you specify default event
1020 handlers for your code. If you have different SOAP objects and want to
1021 share the same on_action() (or on_fault() for that matter) handler. You
1022 can specify on_action() during initialization for every object, but you
1023 may also do:
1024 use SOAP::Lite
1026 on_action => sub {sprintf '%s#%s', @_};
1027 and this handler will be the default handler for all your SOAP objects.
1029 You can override it if you specify a handler for a particular object.
1030 See t/*.t for example of on_fault() handler.
1031 Be warned, that since "use ..." is executed at compile time all "use"
1033 statements will be executed before script execution that can make
1034 unexpected results. Consider code:
1035 use SOAP::Lite proxy => 'http://localhost/';
1037 print SOAP::Lite->getStateName(1)->result;
1038 use SOAP::Lite proxy => 'http://localhost/cgi-bin/soap.cgi';
1040 print SOAP::Lite->getStateName(1)->result;
1041 Both SOAP calls will go to 'http://localhost/cgi-bin/soap.cgi'. If you
1043 want to execute "use" at run-time, put it in "eval":
1044 eval "use SOAP::Lite proxy => 'http://localhost/cgi-bin/soap.cgi'; 1" or die;
1046 Or alternatively,
1048 SOAP::Lite->self->proxy('http://localhost/cgi-bin/soap.cgi');
1050 SETTING MAXIMUM MESSAGE SIZE
1052 One feature of "SOAP::Lite" is the ability to control the maximum size
1053 of a message a SOAP::Lite server will be allowed to process. To control
1054 this feature simply define $SOAP::Constants::MAX_CONTENT_SIZE in your
1055 code like so:
1056 use SOAP::Transport::HTTP;
1058 use MIME::Entity;
1059 $SOAP::Constants::MAX_CONTENT_SIZE = 10000;
1060 SOAP::Transport::HTTP::CGI
1061 ->dispatch_to('TemperatureService')
1062 ->handle;
1063 IN/OUT, OUT PARAMETERS AND AUTOBINDING
1065 "SOAP::Lite" gives you access to all parameters (both in/out and out)
1066 and also does some additional work for you. Lets consider following
1067 example:
1068 <mehodResponse>
1070 <res1>name1</res1>
1071 <res2>name2</res2>
1072 <res3>name3</res3>
1073 </mehodResponse>
1074 In that case:
1076 $result = $r->result; # gives you 'name1'
1078 $paramout1 = $r->paramsout; # gives you 'name2', because of scalar context
1079 $paramout1 = ($r->paramsout)[0]; # gives you 'name2' also
1080 $paramout2 = ($r->paramsout)[1]; # gives you 'name3'
1081 or
1083 @paramsout = $r->paramsout; # gives you ARRAY of out parameters
1085 $paramout1 = $paramsout[0]; # gives you 'res2', same as ($r->paramsout)[0]
1086 $paramout2 = $paramsout[1]; # gives you 'res3', same as ($r->paramsout)[1]
1087 Generally, if server returns "return (1,2,3)" you will get 1 as the
1089 result and 2 and 3 as out parameters.
1090 If the server returns "return [1,2,3]" you will get an ARRAY reference
1092 from result() and "undef" from paramsout().
1093 Results can be arbitrary complex: they can be an array references, they
1095 can be objects, they can be anything and still be returned by result()
1096 . If only one parameter is returned, paramsout() will return "undef".
1097 Furthermore, if you have in your output parameters a parameter with the
1099 same signature (name+type) as in the input parameters this parameter
1100 will be mapped into your input automatically. For example:
1101 Server Code:
1103 sub mymethod {
1105 shift; # object/class reference
1106 my $param1 = shift;
1107 my $param2 = SOAP::Data->name('myparam' => shift() * 2);
1108 return $param1, $param2;
1109 }
1110 Client Code:
1112 $a = 10;
1114 $b = SOAP::Data->name('myparam' => 12);
1115 $result = $soap->mymethod($a, $b);
1116 After that, "$result == 10 and $b->value == 24"! Magic? Sort of.
1118 Autobinding gives it to you. That will work with objects also with one
1120 difference: you do not need to worry about the name and the type of
1121 object parameter. Consider the "PingPong" example
1122 (examples/My/PingPong.pm and examples/pingpong.pl):
1123 Server Code:
1125 package My::PingPong;
1127 sub new {
1129 my $self = shift;
1130 my $class = ref($self) || $self;
1131 bless {_num=>shift} => $class;
1132 }
1133 sub next {
1135 my $self = shift;
1136 $self->{_num}++;
1137 }
1138 Client Code:
1140 use SOAP::Lite +autodispatch =>
1142 uri => 'urn:',
1143 proxy => 'http://localhost/';
1144 my $p = My::PingPong->new(10); # $p->{_num} is 10 now, real object returned
1146 print $p->next, "\n"; # $p->{_num} is 11 now!, object autobinded
1147 STATIC AND DYNAMIC SERVICE DEPLOYMENT
1149 Let us scrutinize the deployment process. When designing your SOAP
1150 server you can consider two kind of deployment: static and dynamic. For
1151 both, static and dynamic, you should specify "MODULE",
1152 "MODULE::method", "method" or "PATH/" when creating "use"ing the
1153 SOAP::Lite module. The difference between static and dynamic deployment
1154 is that in case of 'dynamic', any module which is not present will be
1155 loaded on demand. See the "SECURITY" section for detailed description.
1156 When statically deploying a SOAP Server, you need to know all modules
1158 handling SOAP requests before.
1159 Dynamic deployment allows extending your SOAP Server's interface by
1161 just installing another module into the dispatch_to path (see below).
1162 STATIC DEPLOYMENT EXAMPLE
1164 use SOAP::Transport::HTTP;
1166 use My::Examples; # module is preloaded
1167 SOAP::Transport::HTTP::CGI
1169 # deployed module should be present here or client will get
1170 # 'access denied'
1171 -> dispatch_to('My::Examples')
1172 -> handle;
1173 For static deployment you should specify the MODULE name directly.
1175 You should also use static binding when you have several different
1177 classes in one file and want to make them available for SOAP calls.
1178 DYNAMIC DEPLOYMENT EXAMPLE
1180 use SOAP::Transport::HTTP;
1182 # name is unknown, module will be loaded on demand
1183 SOAP::Transport::HTTP::CGI
1185 # deployed module should be present here or client will get 'access denied'
1186 -> dispatch_to('/Your/Path/To/Deployed/Modules', 'My::Examples')
1187 -> handle;
1188 For dynamic deployment you can specify the name either directly (in
1190 that case it will be "require"d without any restriction) or indirectly,
1191 with a PATH. In that case, the ONLY path that will be available will be
1192 the PATH given to the dispatch_to() method). For information how to
1193 handle this situation see "SECURITY" section.
1194 SUMMARY
1196 dispatch_to(
1198 # dynamic dispatch that allows access to ALL modules in specified directory
1199 PATH/TO/MODULES
1200 # 1. specifies directory
1201 # -- AND --
1202 # 2. gives access to ALL modules in this directory without limits
1203 # static dispatch that allows access to ALL methods in particular MODULE
1205 MODULE
1206 # 1. gives access to particular module (all available methods)
1207 # PREREQUISITES:
1208 # module should be loaded manually (for example with 'use ...')
1209 # -- OR --
1210 # you can still specify it in PATH/TO/MODULES
1211 # static dispatch that allows access to particular method ONLY
1213 MODULE::method
1214 # same as MODULE, but gives access to ONLY particular method,
1215 # so there is not much sense to use both MODULE and MODULE::method
1216 # for the same MODULE
1217 );
1218 In addition to this "SOAP::Lite" also supports an experimental syntax
1220 that allows you to bind a specific URL or SOAPAction to a CLASS/MODULE
1221 or object.
1222 For example:
1224 dispatch_with({
1226 URI => MODULE, # 'http://www.soaplite.com/' => 'My::Class',
1227 SOAPAction => MODULE, # 'http://www.soaplite.com/method' => 'Another::Class',
1228 URI => object, # 'http://www.soaplite.com/obj' => My::Class->new,
1229 })
1230 "URI" is checked before "SOAPAction". You may use both the
1232 dispatch_to() and dispatch_with() methods in the same server, but note
1233 that dispatch_with() has a higher order of precedence. dispatch_to()
1234 will be checked only after "URI" and "SOAPAction" has been checked.
1235 See also: EXAMPLE APACHE::REGISTRY USAGE, "SECURITY"
1237 COMPRESSION
1239 "SOAP::Lite" provides you option to enable transparent compression over
1240 the wire. Compression can be enabled by specifying a threshold value
1241 (in the form of kilobytes) for compression on both the client and
1242 server sides:
1243 Note: Compression currently only works for HTTP based servers and
1245 clients.
1246 Client Code
1248 print SOAP::Lite
1250 ->uri('http://localhost/My/Parameters')
1251 ->proxy('http://localhost/', options => {compress_threshold => 10000})
1252 ->echo(1 x 10000)
1253 ->result;
1254 Server Code
1256 my $server = SOAP::Transport::HTTP::CGI
1258 ->dispatch_to('My::Parameters')
1259 ->options({compress_threshold => 10000})
1260 ->handle;
1261 For more information see COMPRESSION in HTTP::Transport.
1263
1265 For security reasons, the existing path for Perl modules (@INC) will be
1266 disabled once you have chosen dynamic deployment and specified your own
1267 "PATH/". If you wish to access other modules in your included package
1268 you have several options:
1269 1. Switch to static linking:
1271 use MODULE;
1273 $server->dispatch_to('MODULE');
1274 Which can also be useful when you want to import something specific
1276 from the deployed modules:
1277 use MODULE qw(import_list);
1279 2. Change "use" to "require". The path is only unavailable during the
1281 initialization phase. It is available once more during execution.
1282 Therefore, if you utilize "require" somewhere in your package, it
1283 will work.
1284 3. Wrap "use" in an "eval" block:
1286 eval 'use MODULE qw(import_list)'; die if $@;
1288 4. Set your include path in your package and then specify "use". Don't
1290 forget to put @INC in a "BEGIN{}" block or it won't work. For
1291 example,
1292 BEGIN { @INC = qw(my_directory); use MODULE }
1294
1296 Microsoft .NET client with SOAP::Lite Server
1297 In order to use a .NET client with a SOAP::Lite server, be sure you use
1298 fully qualified names for your return values. For example:
1299 return SOAP::Data->name('myname')
1301 ->type('string')
1302 ->uri($MY_NAMESPACE)
1303 ->value($output);
1304 In addition see comment about default encoding in .NET Web Services
1306 below.
1307 SOAP::Lite client with a .NET server
1309 If experiencing problems when using a SOAP::Lite client to call a .NET
1310 Web service, it is recommended you check, or adhere to all of the
1311 following recommendations:
1312 Declare a proper soapAction in your call
1314 For example, use "on_action( sub {
1315 'http://www.myuri.com/WebService.aspx#someMethod'; } )".
1316 Disable charset definition in Content-type header
1318 Some users have said that Microsoft .NET prefers the value of the
1319 Content-type header to be a mimetype exclusively, but SOAP::Lite
1320 specifies a character set in addition to the mimetype. This results
1321 in an error similar to:
1322 Server found request content type to be 'text/xml; charset=utf-8',
1324 but expected 'text/xml'
1325 To turn off this behavior specify use the following code:
1327 use SOAP::Lite;
1329 $SOAP::Constants::DO_NOT_USE_CHARSET = 1;
1330 # The rest of your code
1331 Use fully qualified name for method parameters
1333 For example, the following code is preferred:
1334 SOAP::Data->name(Query => 'biztalk')
1336 ->uri('http://tempuri.org/')
1337 As opposed to:
1339 SOAP::Data->name('Query' => 'biztalk')
1341 Place method in default namespace
1343 For example, the following code is preferred:
1344 my $method = SOAP::Data->name('add')
1346 ->attr({xmlns => 'http://tempuri.org/'});
1347 my @rc = $soap->call($method => @parms)->result;
1348 As opposed to:
1350 my @rc = $soap->call(add => @parms)->result;
1352 # -- OR --
1353 my @rc = $soap->add(@parms)->result;
1354 Disable use of explicit namespace prefixes
1356 Some user's have reported that .NET will simply not parse messages
1357 that use namespace prefixes on anything but SOAP elements
1358 themselves. For example, the following XML would not be parsed:
1359 <SOAP-ENV:Envelope ...attributes skipped>
1361 <SOAP-ENV:Body>
1362 <namesp1:mymethod xmlns:namesp1="urn:MyURI" />
1363 </SOAP-ENV:Body>
1364 </SOAP-ENV:Envelope>
1365 SOAP::Lite allows users to disable the use of explicit namespaces
1367 through the use_prefix() method. For example, the following code:
1368 $som = SOAP::Lite->uri('urn:MyURI')
1370 ->proxy($HOST)
1371 ->use_prefix(0)
1372 ->myMethod();
1373 Will result in the following XML, which is more palatable by .NET:
1375 <SOAP-ENV:Envelope ...attributes skipped>
1377 <SOAP-ENV:Body>
1378 <mymethod xmlns="urn:MyURI" />
1379 </SOAP-ENV:Body>
1380 </SOAP-ENV:Envelope>
1381 Modify your .NET server, if possible
1383 Stefan Pharies <stefanph@microsoft.com>:
1384 SOAP::Lite uses the SOAP encoding (section 5 of the soap 1.1 spec),
1386 and the default for .NET Web Services is to use a literal encoding.
1387 So elements in the request are unqualified, but your service
1388 expects them to be qualified. .Net Web Services has a way for you
1389 to change the expected message format, which should allow you to
1390 get your interop working. At the top of your class in the asmx,
1391 add this attribute (for Beta 1):
1392 [SoapService(Style=SoapServiceStyle.RPC)]
1394 Another source said it might be this attribute (for Beta 2):
1396 [SoapRpcService]
1398 Full Web Service text may look like:
1400 <%@ WebService Language="C#" Class="Test" %>
1402 using System;
1403 using System.Web.Services;
1404 using System.Xml.Serialization;
1405 [SoapService(Style=SoapServiceStyle.RPC)]
1407 public class Test : WebService {
1408 [WebMethod]
1409 public int add(int a, int b) {
1410 return a + b;
1411 }
1412 }
1413 Another example from Kirill Gavrylyuk <kirillg@microsoft.com>:
1415 "You can insert [SoapRpcService()] attribute either on your class
1417 or on operation level".
1418 <%@ WebService Language=CS class="DataType.StringTest"%>
1420 namespace DataType {
1422 using System;
1424 using System.Web.Services;
1425 using System.Web.Services.Protocols;
1426 using System.Web.Services.Description;
1427 [SoapRpcService()]
1429 public class StringTest: WebService {
1430 [WebMethod]
1431 [SoapRpcMethod()]
1432 public string RetString(string x) {
1433 return(x);
1434 }
1435 }
1436 }
1437 Example from Yann Christensen <yannc@microsoft.com>:
1439 using System;
1441 using System.Web.Services;
1442 using System.Web.Services.Protocols;
1443 namespace Currency {
1445 [WebService(Namespace="http://www.yourdomain.com/example")]
1446 [SoapRpcService]
1447 public class Exchange {
1448 [WebMethod]
1449 public double getRate(String country, String country2) {
1450 return 122.69;
1451 }
1452 }
1453 }
1454 Special thanks goes to the following people for providing the above
1456 description and details on .NET interoperability issues:
1457 Petr Janata <petr.janata@i.cz>,
1459 Stefan Pharies <stefanph@microsoft.com>,
1461 Brian Jepson <bjepson@jepstone.net>, and others
1463
1465 SOAP::Lite serializes "18373" as an integer, but I want it to be a
1466 string!
1467 SOAP::Lite guesses datatypes from the content provided, using a set
1468 of common-sense rules. These rules are not 100% reliable, though
1469 they fit for most data.
1470 You may force the type by passing a SOAP::Data object with a type
1472 specified:
1473 my $proxy = SOAP::Lite->proxy('http://www.example.org/soapservice');
1475 my $som = $proxy->myMethod(
1476 SOAP::Data->name('foo')->value(12345)->type('string')
1477 );
1478 You may also change the precedence of the type-guessing rules. Note
1480 that this means fiddling with SOAP::Lite's internals - this may not
1481 work as expected in future versions.
1482 The example above forces everything to be encoded as string (this
1484 is because the string test is normally last and always returns
1485 true):
1486 my @list = qw(-1 45 foo bar 3838);
1488 my $proxy = SOAP::Lite->uri($uri)->proxy($proxyUrl);
1489 my $lookup = $proxy->serializer->typelookup;
1490 $lookup->{string}->[0] = 0;
1491 $proxy->serializer->typelookup($lookup);
1492 $proxy->myMethod(\@list);
1493 See SOAP::Serializer for more details.
1495 "+autodispatch" doesn't work in Perl 5.8
1497 There is a bug in Perl 5.8's "UNIVERSAL::AUTOLOAD" functionality
1498 that prevents the "+autodispatch" functionality from working
1499 properly. The workaround is to use "dispatch_from" instead. Where
1500 you might normally do something like this:
1501 use Some::Module;
1503 use SOAP::Lite +autodispatch =>
1504 uri => 'urn:Foo'
1505 proxy => 'http://...';
1506 You would do something like this:
1508 use SOAP::Lite dispatch_from(Some::Module) =>
1510 uri => 'urn:Foo'
1511 proxy => 'http://...';
1512 Problems using SOAP::Lite's COM Interface
1514 Can't call method "server" on undefined value
1515 You probably did not register Lite.dll using "regsvr32
1516 Lite.dll"
1517 Failed to load PerlCtrl Runtime
1519 It is likely that you have install Perl in two different
1520 locations and the location of ActiveState's Perl is not the
1521 first instance of Perl specified in your PATH. To rectify,
1522 rename the directory in which the non-ActiveState Perl is
1523 installed, or be sure the path to ActiveState's Perl is
1524 specified prior to any other instance of Perl in your PATH.
1525 Dynamic libraries are not found
1527 If you are using the Apache web server, and you are seeing
1528 something like the following in your webserver log file:
1529 Can't load '/usr/local/lib/perl5/site_perl/.../XML/Parser/Expat/Expat.so'
1531 for module XML::Parser::Expat: dynamic linker: /usr/local/bin/perl:
1532 libexpat.so.0 is NEEDED, but object does not exist at
1533 /usr/local/lib/perl5/.../DynaLoader.pm line 200.
1534 Then try placing the following into your httpd.conf file and see if
1536 it fixes your problem.
1537 <IfModule mod_env.c>
1539 PassEnv LD_LIBRARY_PATH
1540 </IfModule>
1541 SOAP client reports "500 unexpected EOF before status line seen
1543 See "Apache is crashing with segfaults"
1544 Apache is crashing with segfaults
1546 Using "SOAP::Lite" (or XML::Parser::Expat) in combination with
1547 mod_perl causes random segmentation faults in httpd processes. To
1548 fix, try configuring Apache with the following:
1549 RULE_EXPAT=no
1551 If you are using Apache 1.3.20 and later, try configuring Apache
1553 with the following option:
1554 ./configure --disable-rule=EXPAT
1556 See http://archive.covalent.net/modperl/2000/04/0185.xml for more
1558 details and lot of thanks to Robert Barta <rho@bigpond.net.au> for
1559 explaining this weird behavior.
1560 If this doesn't address the problem, you may wish to try
1562 "-Uusemymalloc", or a similar option in order to instruct Perl to
1563 use the system's own "malloc".
1564 Thanks to Tim Bunce <Tim.Bunce@pobox.com>.
1566 CGI scripts do not work under Microsoft Internet Information Server
1568 (IIS)
1569 CGI scripts may not work under IIS unless scripts use the ".pl"
1570 extension, opposed to ".cgi".
1571 Java SAX parser unable to parse message composed by SOAP::Lite
1573 In some cases SOAP messages created by "SOAP::Lite" may not be
1574 parsed properly by a SAX2/Java XML parser. This is due to a known
1575 bug in "org.xml.sax.helpers.ParserAdapter". This bug manifests
1576 itself when an attribute in an XML element occurs prior to the XML
1577 namespace declaration on which it depends. However, according to
1578 the XML specification, the order of these attributes is not
1579 significant.
1580 http://www.megginson.com/SAX/index.html
1582 Thanks to Steve Alpert (Steve_Alpert@idx.com) for pointing on it.
1584
1586 Processing of XML encoded fragments
1587 "SOAP::Lite" is based on XML::Parser which is basically wrapper
1588 around James Clark's expat parser. Expat's behavior for parsing XML
1589 encoded string can affect processing messages that have lot of
1590 encoded entities, like XML fragments, encoded as strings. Providing
1591 low-level details, parser will call char() callback for every
1592 portion of processed stream, but individually for every processed
1593 entity or newline. It can lead to lot of calls and additional
1594 memory manager expenses even for small messages. By contrast, XML
1595 messages which are encoded as base64Binary, don't have this problem
1596 and difference in processing time can be significant. For XML
1597 encoded string that has about 20 lines and 30 tags, number of call
1598 could be about 100 instead of one for the same string encoded as
1599 base64Binary.
1600 Since it is parser's feature there is NO fix for this behavior (let
1602 me know if you find one), especially because you need to parse
1603 message you already got (and you cannot control content of this
1604 message), however, if your are in charge for both ends of
1605 processing you can switch encoding to base64 on sender's side. It
1606 will definitely work with SOAP::Lite and it may work with other
1607 toolkits/implementations also, but obviously I cannot guarantee
1608 that.
1609 If you want to encode specific string as base64, just do
1611 "SOAP::Data->type(base64 => $string)" either on client or on server
1612 side. If you want change behavior for specific instance of
1613 SOAP::Lite, you may subclass "SOAP::Serializer", override
1614 as_string() method that is responsible for string encoding (take a
1615 look into as_base64Binary()) and specify new serializer class for
1616 your SOAP::Lite object with:
1617 my $soap = new SOAP::Lite
1619 serializer => My::Serializer->new,
1620 ..... other parameters
1621 or on server side:
1623 my $server = new SOAP::Transport::HTTP::Daemon # or any other server
1625 serializer => My::Serializer->new,
1626 ..... other parameters
1627 If you want to change this behavior for all instances of
1629 SOAP::Lite, just substitute as_string() method with
1630 as_base64Binary() somewhere in your code after "use SOAP::Lite" and
1631 before actual processing/sending:
1632 *SOAP::Serializer::as_string = \&SOAP::XMLSchema2001::Serializer::as_base64Binary;
1634 Be warned that last two methods will affect all strings and convert
1636 them into base64 encoded. It doesn't make any difference for
1637 SOAP::Lite, but it may make a difference for other toolkits.
1638
1640 • No support for multidimensional, partially transmitted and sparse
1641 arrays (however arrays of arrays are supported, as well as any
1642 other data structures, and you can add your own implementation with
1643 SOAP::Data).
1644 • Limited support for WSDL schema.
1646 • XML::Parser::Lite relies on Unicode support in Perl and doesn't do
1648 entity decoding.
1649 • Limited support for mustUnderstand and Actor attributes.
1651
1653 MacOS
1654 Information about XML::Parser for MacPerl could be found here:
1655 http://bumppo.net/lists/macperl-modules/1999/07/msg00047.html
1657 Compiled XML::Parser for MacOS could be found here:
1659 http://www.perl.com/CPAN-local/authors/id/A/AS/ASANDSTRM/XML-Parser-2.27-bin-1-MacOS.tgz
1661
1663 Transport Modules
1664 SOAP::Lite allows one to add support for additional transport
1665 protocols, or server handlers, via separate modules implementing the
1666 SOAP::Transport::* interface. The following modules are available from
1667 CPAN:
1668 • SOAP-Transport-HTTP-Nginx
1670 SOAP::Transport::HTTP::Nginx provides a transport module for nginx
1672 (<http://nginx.net/>)
1673
1675 You can download the latest version SOAP::Lite for Unix or SOAP::Lite
1676 for Win32 from the following sources:
1677 * CPAN: http://search.cpan.org/search?dist=SOAP-Lite
1679 You are welcome to send e-mail to the maintainers of SOAP::Lite with
1681 your comments, suggestions, bug reports and complaints.
1682
1684 Special thanks to Randy J. Ray, author of Programming Web Services with
1685 Perl, who has contributed greatly to the documentation effort of
1686 SOAP::Lite.
1687 Special thanks to O'Reilly publishing which has graciously allowed
1689 SOAP::Lite to republish and redistribute the SOAP::Lite reference
1690 manual found in Appendix B of Programming Web Services with Perl.
1691 And special gratitude to all the developers who have contributed
1693 patches, ideas, time, energy, and help in a million different forms to
1694 the development of this software.
1695
1697 Latest development takes place on GitHub.com. Come on by and fork it.
1698 git@github.com:redhotpenguin/perl-soaplite.git
1700 Also see the HACKING file.
1702 Actively recruiting maintainers for this module. Come and get it on!
1704
1706 Please use rt.cpan.org or github to report bugs. Pull requests are
1707 preferred.
1708
1710 Copyright (C) 2000-2007 Paul Kulchenko. All rights reserved.
1711 Copyright (C) 2007-2008 Martin Kutter
1713 Copyright (C) 2013 Fred Moyer
1715
1717 This library is free software; you can redistribute it and/or modify it
1718 under the same terms as Perl itself.
1719 This text and all associated documentation for this library is made
1721 available under the Creative Commons Attribution-NoDerivs 2.0 license.
1722 http://creativecommons.org/licenses/by-nd/2.0/
1723
1725 Paul Kulchenko (paulclinger@yahoo.com)
1726 Randy J. Ray (rjray@blackperl.com)
1728 Byrne Reese (byrne@majordojo.com)
1730 Martin Kutter (martin.kutter@fen-net.de)
1732 Fred Moyer (fred@redhotpenguin.com)
1734perl v5.36.0 2023-01-20 SOAP::Lite(3)