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

NAME

6       SOAP::Lite - Perl's Web Services Toolkit
7

DESCRIPTION

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

PERL VERSION WARNING

14       SOAP::Lite 0.71 will be the last version of SOAP::Lite running on perl
15       5.005
16
17       Future versions of SOAP::Lite will require at least perl 5.6.0
18
19       If you have not had the time to upgrad your perl, you should consider
20       this now.
21

OVERVIEW OF CLASSES AND PACKAGES

23       lib/SOAP/Lite.pm
24           SOAP::Lite - Main class provides all logic
25
26           SOAP::Transport - Transport backend
27
28           SOAP::Data - Data objects
29
30           SOAP::Header - Header Data Objects
31
32           SOAP::Serializer - Serializes data structures to SOAP messages
33
34           SOAP::Deserializer - Deserializes SOAP messages into SOAP::SOM
35           objects
36
37           SOAP::SOM - SOAP Message objects
38
39           SOAP::Constants - Provides access to common constants and defaults
40
41           SOAP::Trace - Tracing facilities
42
43           SOAP::Schema - Provides access and stub(s) for schema(s)
44
45           SOAP::Schema::WSDL - WSDL implementation for SOAP::Schema
46
47           SOAP::Server - Handles requests on server side
48
49           SOAP::Server::Object - Handles objects-by-reference
50
51           SOAP::Fault - Provides support for Faults on server side
52
53           SOAP::Utils - A set of private and public utility subroutines
54
55       lib/SOAP/Packager.pm
56           SOAP::Packager - Provides an abstract class for implementing custom
57           packagers.
58
59           SOAP::Packager::MIME - Provides MIME support to SOAP::Lite
60
61           SOAP::Packager::DIME - Provides DIME support to SOAP::Lite
62
63       lib/SOAP/Transport/HTTP.pm
64           SOAP::Transport::HTTP::Client - Client interface to HTTP transport
65
66           SOAP::Transport::HTTP::Server - Server interface to HTTP transport
67
68           SOAP::Transport::HTTP::CGI - CGI implementation of server interface
69
70           SOAP::Transport::HTTP::Daemon - Daemon implementation of server
71           interface
72
73           SOAP::Transport::HTTP::Apache - mod_perl implementation of server
74           interface
75
76       lib/SOAP/Transport/POP3.pm
77           SOAP::Transport::POP3::Server - Server interface to POP3 protocol
78
79       lib/SOAP/Transport/MAILTO.pm
80           SOAP::Transport::MAILTO::Client - Client interface to SMTP/sendmail
81
82       lib/SOAP/Transport/LOCAL.pm
83           SOAP::Transport::LOCAL::Client - Client interface to local
84           transport
85
86       lib/SOAP/Transport/TCP.pm
87           SOAP::Transport::TCP::Server - Server interface to TCP protocol
88
89           SOAP::Transport::TCP::Client - Client interface to TCP protocol
90
91       lib/SOAP/Transport/IO.pm
92           SOAP::Transport::IO::Server - Server interface to IO transport
93

METHODS

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
100       new(optional key/value pairs)
101               $client = SOAP::Lite->new(proxy => $endpoint)
102
103           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
108       transport(optional transport object)
109               $transp = $client->transport( );
110
111           Gets or sets the transport object used for sending/receiving SOAP
112           messages.
113
114           See SOAP::Transport for details.
115
116       serializer(optional serializer object)
117               $serial = $client->serializer( )
118
119           Gets or sets the serializer object used for creating XML messages.
120
121           See SOAP::Serializer for details.
122
123       packager(optional packager object)
124               $packager = $client->packager( )
125
126           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
131           See also: SOAP::Packager.
132
133       proxy(endpoint, optional extra arguments)
134               $client->proxy('http://soap.xml.info/ endPoint');
135
136           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
141           This method is actually an alias to the proxy method of
142           SOAP::Transport.  It is the same as typing:
143
144               $client->transport( )->proxy(...arguments);
145
146           Extra parameters can be passed to proxy() - see below.
147
148           compress_threshold
149               See COMPRESSION in HTTP::Transport.
150
151           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
155               A common option is to create a instance of HTTP::Cookies and
156               pass it as cookie_jar option:
157
158                my $cookie_jar = HTTP::Cookies->new()
159                $client->proxy('http://www.example.org/webservice',
160                   cookie_jar => $cookie_jar,
161                );
162
163           For example, if you wish to set the HTTP timeout for a SOAP::Lite
164           client to 5 seconds, use the following code:
165
166             my $soap = SOAP::Lite
167              ->uri($uri)
168              ->proxy($proxyUrl, timeout => 5 );
169
170           See LWP::UserAgent.
171
172       endpoint(optional new endpoint address)
173               $client->endpoint('http://soap.xml.info/ newPoint')
174
175           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
183       service(service URL)
184               $client->service('http://svc.perl.org/Svc.wsdl');
185
186           "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
191       outputxml(boolean)
192               $client->outputxml('true');
193
194           When set to a true value, the raw XML is returned by the call to a
195           remote method.
196
197           The default is to return the a SOAP::SOM object (false).
198
199       autotype(boolean)
200               $client->autotype(0);
201
202           This method is a shortcut for:
203
204               $client->serializer->autotype(boolean);
205
206           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
210       readable(boolean)
211               $client->readable(1);
212
213           This method is a shortcut for:
214
215               $client->serializer->readable(boolean);
216
217           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
223       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
230             <soap:Envelope>
231               <soap:Body>
232                 <myMethod xmlns="http://www.someuri.com">
233                   <foo />
234                 </myMethod>
235               </soap:Body>
236             </soap:Envelope>
237
238           Some .NET web services have been reported to require this XML
239           namespace idiom.
240
241       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
247           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
251             <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
259       use_prefix(boolean)
260           Deprecated. Use the "ns()" and "default_ns" methods described
261           above.
262
263           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
267           When use_prefix is set to 'true', serialized XML will look like
268           this:
269
270             <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
276           When use_prefix is set to 'false', serialized XML will look like
277           this:
278
279             <SOAP-ENV:Envelope ...attributes skipped>
280               <SOAP-ENV:Body>
281                 <mymethod xmlns="urn:MyURI" />
282               </SOAP-ENV:Body>
283             </SOAP-ENV:Envelope>
284
285           Some .NET web services have been reported to require this XML
286           namespace idiom.
287
288       soapversion(optional value)
289               $client->soapversion('1.2');
290
291           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
296           The value should be either 1.1 or 1.2.
297
298       envprefix(QName)
299               $client->envprefix('env');
300
301           This method is a shortcut for:
302
303               $client->serializer->envprefix(QName);
304
305           Gets or sets the namespace prefix for the SOAP namespace. The
306           default is SOAP.
307
308           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
312       encprefix(QName)
313               $client->encprefix('enc');
314
315           This method is a shortcut for:
316
317               $client->serializer->encprefix(QName);
318
319           Gets or sets the namespace prefix for the encoding rules namespace.
320           The default value is SOAP-ENC.
321
322       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
328       encoding(encoding URN)
329               $client->encoding($soap_12_encoding_URN);
330
331           This method is a shortcut for:
332
333               $client->serializer->encoding(args);
334
335           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
342       typelookup
343               $client->typelookup;
344
345           This method is a shortcut for:
346
347               $client->serializer->typelookup;
348
349           Gives the application access to the type-lookup table from the
350           serializer object. See the section on SOAP::Serializer.
351
352       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
358               $client->uri($service_uri);
359
360           This method is a shortcut for:
361
362               $client->serializer->uri(service);
363
364           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
371           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
377       multirefinplace(boolean)
378               $client->multirefinplace(1);
379
380           This method is a shortcut for:
381
382               $client->serializer->multirefinplace(boolean);
383
384           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
398       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
403       self
404               $ref = SOAP::Lite->self;
405
406           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
410       The following method isn't an accessor style of method but neither does
411       it fit with the group that immediately follows it:
412
413       call(arguments)
414               $client->call($method => @arguments);
415
416           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
426       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
430       on_action(callback)
431               $client->on_action(sub { qq("$_[0]") });
432
433           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
441           .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
445               $client->on_action( sub { join '/', @_ } );
446           =item on_fault(callback)
447
448               $client->on_fault(sub { popup_dialog($_[1]) });
449
450           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
458       on_nonserialized(callback)
459               $client->on_nonserialized(sub { die "$_[0]?!?" });
460
461           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
471       on_debug(callback)
472               $client->on_debug(sub { print @_ });
473
474           Deprecated. Use the global +debug and +trace facilities described
475           in SOAP::Trace
476
477           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

WRITING A SOAP CLIENT

483       This chapter guides you to writing a SOAP client by example.
484
485       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
489       We will use "Martin Kutter" as the name for the call, so all variants
490       will print the following message on success:
491
492        Hello Martin Kutter!
493
494   SOAP message styles
495       There are three common (and one less common) variants of SOAP messages.
496
497       These address the message style (positional parameters vs. specified
498       message documents) and encoding (as-is vs. typed).
499
500       The different message styles are:
501
502       ·   rpc/encoded
503
504           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
508       ·   rpc/literal
509
510           As-is, positional parameters. The type of arguments is defined by
511           some pre-exchanged interface definition.
512
513       ·   document/encoded
514
515           Specified message with typed elements. Rarely used.
516
517       ·   document/literal
518
519           Specified message with as-is elements. The message specification
520           and element types are defined by some pre-exchanged interface
521           definition.
522
523       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
527       You will see clients for the rpc/encoded and document/literal SOAP
528       variants in this section.
529
530   Example implementations
531       RPC/ENCODED
532
533       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
537        Method: sayHello(string, string)
538        Parameters:
539           name: string
540           givenName: string
541
542       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
546       The message corresponding to this description looks somewhat like this:
547
548        <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
553       Any XML tag names may be used instead of the "s-gensym01" stuff -
554       parameters are positional, the tag names have no meaning.
555
556       A client producing such a call is implemented like this:
557
558        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
565       You can of course use a one-liner, too...
566
567       Sometimes, rpc/encoded interfaces are described with WSDL definitions.
568       A WSDL accepting "named" parameters with rpc/encoded looks like this:
569
570        <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
587          <portType name="Service1Soap">
588            <operation name="sayHello">
589              <input message="s0:sayHello" />
590              <output message="s0:sayHelloResponse" />
591            </operation>
592          </portType>
593
594          <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
616       The message corresponding to this schema looks like this:
617
618        <sayHello xmlns="urn:HelloWorld">
619          <name xsi:type="xsd:string">Kutter</name>
620          <givenName xsi:type="xsd:string">Martin</givenName>
621        </sayHello>
622
623       A web service client using this schema looks like this:
624
625        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
633       You may of course also use the following one-liner:
634
635        perl -MSOAP::Lite -e 'print SOAP::Lite->service("file:say_hello_rpcenc.wsdl")\
636          ->sayHello('Kutter', 'Martin'), "\n";'
637
638       A web service client (without a service description) looks like this.
639
640        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
650       RPC/LITERAL
651
652       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
656        <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
672              <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
687          <portType name="Service1Soap">
688            <operation name="sayHello">
689              <input message="s0:sayHello" />
690              <output message="s0:sayHelloResponse" />
691            </operation>
692          </portType>
693
694          <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
714       The XML message (inside the SOAP Envelope) look like this:
715
716        <ns0:sayHello xmlns:ns0="urn:HelloWorld">
717           <parameters>
718             <name>Kutter</name>
719             <givenName>Martin</givenName>
720           </parameters>
721        </ns0:sayHello>
722
723        <sayHelloResponse xmlns:ns0="urn:HelloWorld">
724           <parameters>
725               <sayHelloResult>Hello Martin Kutter!</sayHelloResult>
726           </parameters>
727        </sayHelloResponse>
728
729       This is the SOAP::Lite implementation for the web service client:
730
731        use SOAP::Lite +trace;
732        my $soap = SOAP::Lite->new( proxy => 'http://localhost:80/helloworld.pl');
733
734        $soap->on_action( sub { "urn:HelloWorld#sayHello" });
735        $soap->autotype(0)->readable(1);
736        $soap->default_ns('urn:HelloWorld');
737
738        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
745        die $som->fault->{ faultstring } if ($som->fault);
746        print $som->result, "\n";
747
748       DOCUMENT/LITERAL
749
750       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
754        <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
770               <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
785           <portType name="Service1Soap">
786             <operation name="sayHello">
787               <input message="s0:sayHelloSoapIn" />
788               <output message="s0:sayHelloSoapOut" />
789             </operation>
790           </portType>
791
792           <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
812       The XML message (inside the SOAP Envelope) look like this:
813
814        <sayHello xmlns="urn:HelloWorld">
815          <name>Kutter</name>
816          <givenName>Martin</givenName>
817        </sayHello>
818
819        <sayHelloResponse>
820          <sayHelloResult>Hello Martin Kutter!</sayHelloResult>
821        </sayHelloResponse>
822
823       You can call this web service with the following client code:
824
825        use SOAP::Lite;
826        my $soap = SOAP::Lite->new( proxy => 'http://localhost:80/helloworld.pl');
827
828        $soap->on_action( sub { "urn:HelloWorld#sayHello" });
829        $soap->autotype(0);
830        $soap->default_ns('urn:HelloWorld');
831
832        my $som = $soap->call("sayHello",
833           SOAP::Data->name('name')->value( 'Kutter' ),
834           SOAP::Data->name('givenName')->value('Martin'),
835       );
836
837        die $som->fault->{ faultstring } if ($som->fault);
838        print $som->result, "\n";
839
840   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
847       In our example, the rpc/encoded variant already used named parameters
848       (by using two messages), so there's no difference at all.
849
850       You may have noticed the somewhat strange idiom for passing a list of
851       named paraneters in the rpc/literal example:
852
853        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
860       While SOAP::Data provides full control over the XML generated, passing
861       hash-like structures require additional coding.
862

WRITING A SOAP SERVER

864       See SOAP::Server, or SOAP::Transport.
865

FEATURES

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
872       EXAMPLES
873
874       Client sending an attachment
875
876       "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
880         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
894       Client retrieving an attachment
895
896       A client accessing attachments that were returned in a response by
897       using the "SOAP::SOM::parts()" accessor.
898
899         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
909       Server receiving an attachment
910
911       Servers, like clients, use the SOAP::SOM module to access attachments
912       transmitted to it.
913
914         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
929       Server responding with an attachment
930
931       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
935         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
953   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
959       If you wish to provide common "proxy()" or "uri()" settings for all
960       "SOAP::Lite" objects in your application you may do:
961
962         use SOAP::Lite
963           proxy => 'http://localhost/cgi-bin/soap.cgi',
964           uri => 'http://my.own.com/My/Examples';
965
966         my $soap1 = new SOAP::Lite; # will get the same proxy()/uri() as above
967         print $soap1->getStateName(1)->result;
968
969         my $soap2 = SOAP::Lite->new; # same thing as above
970         print $soap2->getStateName(2)->result;
971
972         # or you may override any settings you want
973         my $soap3 = SOAP::Lite->proxy('http://localhost/');
974         print $soap3->getStateName(1)->result;
975
976       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
982         SOAP::Lite->self(undef);
983
984       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
990         use SOAP::Lite
991           on_action => sub {sprintf '%s#%s', @_};
992
993       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
997       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
1001         use SOAP::Lite proxy => 'http://localhost/';
1002         print SOAP::Lite->getStateName(1)->result;
1003
1004         use SOAP::Lite proxy => 'http://localhost/cgi-bin/soap.cgi';
1005         print SOAP::Lite->getStateName(1)->result;
1006
1007       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
1010         eval "use SOAP::Lite proxy => 'http://localhost/cgi-bin/soap.cgi'; 1" or die;
1011
1012       Or alternatively,
1013
1014         SOAP::Lite->self->proxy('http://localhost/cgi-bin/soap.cgi');
1015
1016   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
1022         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
1029   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
1034         <mehodResponse>
1035           <res1>name1</res1>
1036           <res2>name2</res2>
1037           <res3>name3</res3>
1038         </mehodResponse>
1039
1040       In that case:
1041
1042         $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
1047       or
1048
1049         @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
1053       Generally, if server returns "return (1,2,3)" you will get 1 as the
1054       result and 2 and 3 as out parameters.
1055
1056       If the server returns "return [1,2,3]" you will get an ARRAY reference
1057       from "result()" and "undef" from "paramsout()".
1058
1059       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
1064       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
1068       Server Code:
1069
1070         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
1077       Client Code:
1078
1079         $a = 10;
1080         $b = SOAP::Data->name('myparam' => 12);
1081         $result = $soap->mymethod($a, $b);
1082
1083       After that, "$result == 10 and $b->value == 24"! Magic? Sort of.
1084
1085       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
1090       Server Code:
1091
1092         package My::PingPong;
1093
1094         sub new {
1095           my $self = shift;
1096           my $class = ref($self) || $self;
1097           bless {_num=>shift} => $class;
1098         }
1099
1100         sub next {
1101           my $self = shift;
1102           $self->{_num}++;
1103         }
1104
1105       Client Code:
1106
1107         use SOAP::Lite +autodispatch =>
1108           uri => 'urn:',
1109           proxy => 'http://localhost/';
1110
1111         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
1114   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
1123       When statically deploying a SOAP Server, you need to know all modules
1124       handling SOAP requests before.
1125
1126       Dynamic deployment allows extending your SOAP Server's interface by
1127       just installing another module into the dispatch_to path (see below).
1128
1129       STATIC DEPLOYMENT EXAMPLE
1130
1131         use SOAP::Transport::HTTP;
1132         use My::Examples;           # module is preloaded
1133
1134         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
1140       For static deployment you should specify the MODULE name directly.
1141
1142       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
1145       DYNAMIC DEPLOYMENT EXAMPLE
1146
1147         use SOAP::Transport::HTTP;
1148         # name is unknown, module will be loaded on demand
1149
1150         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
1155       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
1161       SUMMARY
1162
1163         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
1170           # 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
1178           # 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
1185       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
1189       For example:
1190
1191         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
1197       "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
1203       See also: EXAMPLE APACHE::REGISTRY USAGE, "SECURITY"
1204
1205   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
1211       Note: Compression currently only works for HTTP based servers and
1212       clients.
1213
1214       Client Code
1215
1216         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
1222       Server Code
1223
1224         my $server = SOAP::Transport::HTTP::CGI
1225           ->dispatch_to('My::Parameters')
1226           ->options({compress_threshold => 10000})
1227           ->handle;
1228
1229       For more information see COMPRESSION in HTTP::Transport.
1230

SECURITY

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
1237       1.  Switch to static linking:
1238
1239              use MODULE;
1240              $server->dispatch_to('MODULE');
1241
1242           Which can also be useful when you want to import something specific
1243           from the deployed modules:
1244
1245              use MODULE qw(import_list);
1246
1247       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
1252       3.  Wrap "use" in an "eval" block:
1253
1254              eval 'use MODULE qw(import_list)'; die if $@;
1255
1256       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
1260              BEGIN { @INC = qw(my_directory); use MODULE }
1261

INTEROPERABILITY

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
1267         return SOAP::Data->name('myname')
1268                          ->type('string')
1269                          ->uri($MY_NAMESPACE)
1270                          ->value($output);
1271
1272       In addition see comment about default incoding in .NET Web Services
1273       below.
1274
1275   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
1280       Declare a proper soapAction in your call
1281           For example, use "on_action( sub {
1282           'http://www.myuri.com/WebService.aspx#someMethod'; } )".
1283
1284       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
1290             Server found request content type to be 'text/xml; charset=utf-8',
1291             but expected 'text/xml'
1292
1293           To turn off this behavior specify use the following code:
1294
1295             use SOAP::Lite;
1296             $SOAP::Constants::DO_NOT_USE_CHARSET = 1;
1297             # The rest of your code
1298
1299       Use fully qualified name for method parameters
1300           For example, the following code is preferred:
1301
1302             SOAP::Data->name(Query  => 'biztalk')
1303                       ->uri('http://tempuri.org/')
1304
1305           As opposed to:
1306
1307             SOAP::Data->name('Query'  => 'biztalk')
1308
1309       Place method in default namespace
1310           For example, the following code is preferred:
1311
1312             my $method = SOAP::Data->name('add')
1313                                    ->attr({xmlns => 'http://tempuri.org/'});
1314             my @rc = $soap->call($method => @parms)->result;
1315
1316           As opposed to:
1317
1318             my @rc = $soap->call(add => @parms)->result;
1319             # -- OR --
1320             my @rc = $soap->add(@parms)->result;
1321
1322       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
1327             <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
1333           SOAP::Lite allows users to disable the use of explicit namespaces
1334           through the "use_prefix()" method. For example, the following code:
1335
1336             $som = SOAP::Lite->uri('urn:MyURI')
1337                              ->proxy($HOST)
1338                              ->use_prefix(0)
1339                              ->myMethod();
1340
1341           Will result in the following XML, which is more pallatable by .NET:
1342
1343             <SOAP-ENV:Envelope ...attributes skipped>
1344               <SOAP-ENV:Body>
1345                 <mymethod xmlns="urn:MyURI" />
1346               </SOAP-ENV:Body>
1347             </SOAP-ENV:Envelope>
1348
1349       Modify your .NET server, if possible
1350           Stefan Pharies <stefanph@microsoft.com>:
1351
1352           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
1360             [SoapService(Style=SoapServiceStyle.RPC)]
1361
1362           Another source said it might be this attribute (for Beta 2):
1363
1364             [SoapRpcService]
1365
1366           Full Web Service text may look like:
1367
1368             <%@ WebService Language="C#" Class="Test" %>
1369             using System;
1370             using System.Web.Services;
1371             using System.Xml.Serialization;
1372
1373             [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
1381           Another example from Kirill Gavrylyuk <kirillg@microsoft.com>:
1382
1383           "You can insert [SoapRpcService()] attribute either on your class
1384           or on operation level".
1385
1386             <%@ WebService Language=CS class="DataType.StringTest"%>
1387
1388             namespace DataType {
1389
1390               using System;
1391               using System.Web.Services;
1392               using System.Web.Services.Protocols;
1393               using System.Web.Services.Description;
1394
1395              [SoapRpcService()]
1396              public class StringTest: WebService {
1397                [WebMethod]
1398                [SoapRpcMethod()]
1399                public string RetString(string x) {
1400                  return(x);
1401                }
1402              }
1403            }
1404
1405           Example from Yann Christensen <yannc@microsoft.com>:
1406
1407             using System;
1408             using System.Web.Services;
1409             using System.Web.Services.Protocols;
1410
1411             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
1422       Special thanks goes to the following people for providing the above
1423       description and details on .NET interoperability issues:
1424
1425       Petr Janata <petr.janata@i.cz>,
1426
1427       Stefan Pharies <stefanph@microsoft.com>,
1428
1429       Brian Jepson <bjepson@jepstone.net>, and others
1430

TROUBLESHOOTING

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
1438           You may force the type by passing a SOAP::Data object with a type
1439           specified:
1440
1441            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
1446           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
1450           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
1454             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
1459           See SOAP::Serializer for more details.
1460
1461       "+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
1467              use Some::Module;
1468              use SOAP::Lite +autodispatch =>
1469                  uri => 'urn:Foo'
1470                  proxy => 'http://...';
1471
1472           You would do something like this:
1473
1474              use SOAP::Lite dispatch_from(Some::Module) =>
1475                  uri => 'urn:Foo'
1476                  proxy => 'http://...';
1477
1478       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
1483           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
1491       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
1495             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
1500           Then try placing the following into your httpd.conf file and see if
1501           it fixes your problem.
1502
1503            <IfModule mod_env.c>
1504                PassEnv LD_LIBRARY_PATH
1505            </IfModule>
1506
1507       SOAP client reports "500 unexpected EOF before status line seen
1508           See "Apache is crashing with segfaults"
1509
1510       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
1515            RULE_EXPAT=no
1516
1517           If you are using Apache 1.3.20 and later, try configuring Apache
1518           with the following option:
1519
1520            ./configure --disable-rule=EXPAT
1521
1522           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
1526           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
1530           Thanks to Tim Bunce <Tim.Bunce@pobox.com>.
1531
1532       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
1537       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
1546           http://www.megginson.com/SAX/index.html
1547
1548           Thanks to Steve Alpert (Steve_Alpert@idx.com) for pointing on it.
1549

PERFORMANCE

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
1566           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
1575           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
1583             my $soap = new SOAP::Lite
1584               serializer => My::Serializer->new,
1585               ..... other parameters
1586
1587           or on server side:
1588
1589             my $server = new SOAP::Transport::HTTP::Daemon # or any other server
1590               serializer => My::Serializer->new,
1591               ..... other parameters
1592
1593           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
1598             *SOAP::Serializer::as_string = \&SOAP::XMLSchema2001::Serializer::as_base64Binary;
1599
1600           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

BUGS AND LIMITATIONS

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
1610       ·   Limited support for WSDL schema.
1611
1612       ·   XML::Parser::Lite relies on Unicode support in Perl and doesn't do
1613           entity decoding.
1614
1615       ·   Limited support for mustUnderstand and Actor attributes.
1616

PLATFORM SPECIFICS

1618       MacOS
1619           Information about XML::Parser for MacPerl could be found here:
1620
1621           http://bumppo.net/lists/macperl-modules/1999/07/msg00047.html
1622
1623           Compiled XML::Parser for MacOS could be found here:
1624
1625           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
1634       ·   SOAP-Transport-HTTP-Nginx
1635
1636           SOAP::Transport::HTTP::Nginx provides a transport module for nginx
1637           (<http://nginx.net/>)
1638

AVAILABILITY

1640       You can download the latest version SOAP::Lite for Unix or SOAP::Lite
1641       for Win32 from the following sources:
1642
1643        * CPAN:                http://search.cpan.org/search?dist=SOAP-Lite
1644        * Sourceforge:         http://sourceforge.net/projects/soaplite/
1645
1646       PPM packages are also available from sourceforge.
1647
1648       You are welcome to send e-mail to the maintainers of SOAP::Lite with
1649       your comments, suggestions, bug reports and complaints.
1650

ACKNOWLEDGEMENTS

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
1656       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
1660       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

HACKING

1665       SOAP::Lite's development takes place on sourceforge.net.
1666
1667       There's a subversion repository set up at
1668
1669        https://soaplite.svn.sourceforge.net/svnroot/soaplite/
1670

REPORTING BUGS

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
1676       http://sourceforge.net/tracker/?group_id=66000&atid=513017
1677
1679       Copyright (C) 2000-2007 Paul Kulchenko. All rights reserved.
1680
1681       Copyright (C) 2007-2008 Martin Kutter
1682

LICENSE

1684       This library is free software; you can redistribute it and/or modify it
1685       under the same terms as Perl itself.
1686
1687       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

AUTHORS

1692       Paul Kulchenko (paulclinger@yahoo.com)
1693
1694       Randy J. Ray (rjray@blackperl.com)
1695
1696       Byrne Reese (byrne@majordojo.com)
1697
1698       Martin Kutter (martin.kutter@fen-net.de)
1699
1700
1701
1702perl v5.12.3                      2010-06-03                     SOAP::Lite(3)
Impressum