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