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       As of version SOAP::Lite version 1.05, no perl versions before 5.8 will
15       be supported.
16
17       SOAP::Lite 0.71 will be the last version of SOAP::Lite running on perl
18       5.005
19
20       Future versions of SOAP::Lite will require at least perl 5.6.0
21
22       If you have not had the time to upgrade your perl, you should consider
23       this now.
24

OVERVIEW OF CLASSES AND PACKAGES

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

METHODS

98       All accessor methods return the current value when called with no
99       arguments, while returning the object reference itself when called with
100       a new value.  This allows the set-attribute calls to be chained
101       together.
102
103       new(optional key/value pairs)
104               $client = SOAP::Lite->new(proxy => $endpoint)
105
106           Constructor. Many of the accessor methods defined here may be
107           initialized at creation by providing their name as a key, followed
108           by the desired value.  The example provides the value for the proxy
109           element of the client.
110
111       transport(optional transport object)
112               $transp = $client->transport( );
113
114           Gets or sets the transport object used for sending/receiving SOAP
115           messages.
116
117           See SOAP::Transport for details.
118
119       serializer(optional serializer object)
120               $serial = $client->serializer( )
121
122           Gets or sets the serializer object used for creating XML messages.
123
124           See SOAP::Serializer for details.
125
126       packager(optional packager object)
127               $packager = $client->packager( )
128
129           Provides access to the "SOAP::Packager" object that the client uses
130           to manage the use of attachments. The default packager is a MIME
131           packager, but unless you specify parts to send, no MIME formatting
132           will be done.
133
134           See also: SOAP::Packager.
135
136       proxy(endpoint, optional extra arguments)
137               $client->proxy('http://soap.xml.info/ endPoint');
138
139           The proxy is the server or endpoint to which the client is going to
140           connect.  This method allows the setting of the endpoint, along
141           with any extra information that the transport object may need when
142           communicating the request.
143
144           This method is actually an alias to the proxy method of
145           SOAP::Transport.  It is the same as typing:
146
147               $client->transport( )->proxy(...arguments);
148
149           Extra parameters can be passed to proxy() - see below.
150
151           compress_threshold
152               See COMPRESSION in HTTP::Transport.
153
154           All initialization options from the underlying transport layer
155               The options for HTTP(S) are the same as for LWP::UserAgent's
156               new() method.
157
158               A common option is to create a instance of HTTP::Cookies and
159               pass it as cookie_jar option:
160
161                my $cookie_jar = HTTP::Cookies->new()
162                $client->proxy('http://www.example.org/webservice',
163                   cookie_jar => $cookie_jar,
164                );
165
166           For example, if you wish to set the HTTP timeout for a SOAP::Lite
167           client to 5 seconds, use the following code:
168
169             my $soap = SOAP::Lite
170              ->uri($uri)
171              ->proxy($proxyUrl, timeout => 5 );
172
173           See LWP::UserAgent.
174
175       endpoint(optional new endpoint address)
176               $client->endpoint('http://soap.xml.info/ newPoint')
177
178           It may be preferable to set a new endpoint without the additional
179           work of examining the new address for protocol information and
180           checking to ensure the support code is loaded and available. This
181           method allows the caller to change the endpoint that the client is
182           currently set to connect to, without reloading the relevant
183           transport code. Note that the proxy method must have been called
184           before this method is used.
185
186       service(service URL)
187               $client->service('http://svc.perl.org/Svc.wsdl');
188
189           "SOAP::Lite" offers some support for creating method stubs from
190           service descriptions. At present, only WSDL support is in place.
191           This method loads the specified WSDL schema and uses it as the
192           basis for generating stubs.
193
194       outputxml(boolean)
195               $client->outputxml('true');
196
197           When set to a true value, the raw XML is returned by the call to a
198           remote method.
199
200           The default is to return a SOAP::SOM object (false).
201
202       autotype(boolean)
203               $client->autotype(0);
204
205           This method is a shortcut for:
206
207               $client->serializer->autotype(boolean);
208
209           By default, the serializer tries to automatically deduce types for
210           the data being sent in a message. Setting a false value with this
211           method disables the behavior.
212
213       readable(boolean)
214               $client->readable(1);
215
216           This method is a shortcut for:
217
218               $client->serializer->readable(boolean);
219
220           When this is used to set a true value for this property, the
221           generated XML sent to the endpoint has extra characters (spaces and
222           new lines) added in to make the XML itself more readable to human
223           eyes (presumably for debugging).  The default is to not send any
224           additional characters.
225
226       headerattr(hash reference of attributes)
227               $obj->headerattr({ attr1 => 'value' });
228
229           Allows for the setting of arbitrary attributes on the header
230           object. Keep in mind the requirement that
231            any attributes not natively known to SOAP must be namespace-
232           qualified.  If using $session->call ($method, $callData,
233           $callHeader), SOAP::Lite serializes information as
234
235             <soap:Envelope>
236               <soap:Header>
237                 <userId>xxxxx</userId>
238                 <password>yyyyy</password>
239               </soap:Header>
240               <soap:Body>
241                 <myMethod xmlns="http://www.someuri.com">
242                   <foo />
243                 </myMethod>
244               </soap:Body>
245             </soap:Envelope>
246
247           The attributes, given to headerattr are placed into the Header as
248
249               <soap:Header attr1="value">
250
251       bodyattr(hash reference of attributes)
252               $obj->bodyattr({ attr1 => 'value' });
253
254           Allows for the setting of arbitrary attributes on the body object.
255           Keep in mind the requirement that
256            any attributes not natively known to SOAP must be namespace-
257           qualified.  See headerattr
258
259       default_ns($uri)
260           Sets the default namespace for the request to the specified uri.
261           This overrides any previous namespace declaration that may have
262           been set using a previous call to "ns()" or "default_ns()". Setting
263           the default namespace causes elements to be serialized without a
264           namespace prefix, like this:
265
266             <soap:Envelope>
267               <soap:Body>
268                 <myMethod xmlns="http://www.someuri.com">
269                   <foo />
270                 </myMethod>
271               </soap:Body>
272             </soap:Envelope>
273
274           Some .NET web services have been reported to require this XML
275           namespace idiom.
276
277       ns($uri,$prefix=undef)
278           Sets the namespace uri and optionally the namespace prefix for the
279           request to the specified values. This overrides any previous
280           namespace declaration that may have been set using a previous call
281           to "ns()" or "default_ns()".
282
283           If a prefix is not specified, one will be generated for you
284           automatically.  Setting the namespace causes elements to be
285           serialized with a declared namespace prefix, like this:
286
287             <soap:Envelope>
288               <soap:Body>
289                 <my:myMethod xmlns:my="http://www.someuri.com">
290                   <my:foo />
291                 </my:myMethod>
292               </soap:Body>
293             </soap:Envelope>
294
295       use_prefix(boolean)
296           Deprecated. Use the "ns()" and "default_ns" methods described
297           above.
298
299           Shortcut for "serializer->use_prefix()". This lets you turn on/off
300           the use of a namespace prefix for the children of the
301           /Envelope/Body element.  Default is 'true'.
302
303           When use_prefix is set to 'true', serialized XML will look like
304           this:
305
306             <SOAP-ENV:Envelope ...attributes skipped>
307               <SOAP-ENV:Body>
308                 <namesp1:mymethod xmlns:namesp1="urn:MyURI" />
309               </SOAP-ENV:Body>
310             </SOAP-ENV:Envelope>
311
312           When use_prefix is set to 'false', serialized XML will look like
313           this:
314
315             <SOAP-ENV:Envelope ...attributes skipped>
316               <SOAP-ENV:Body>
317                 <mymethod xmlns="urn:MyURI" />
318               </SOAP-ENV:Body>
319             </SOAP-ENV:Envelope>
320
321           Some .NET web services have been reported to require this XML
322           namespace idiom.
323
324       soapversion(optional value)
325               $client->soapversion('1.2');
326
327           If no parameter is given, returns the current version of SOAP that
328           is being used by the client object to encode requests. If a
329           parameter is given, the method attempts to set that as the version
330           of SOAP being used.
331
332           The value should be either 1.1 or 1.2.
333
334       envprefix(QName)
335               $client->envprefix('env');
336
337           This method is a shortcut for:
338
339               $client->serializer->envprefix(QName);
340
341           Gets or sets the namespace prefix for the SOAP namespace. The
342           default is SOAP.
343
344           The prefix itself has no meaning, but applications may wish to
345           chose one explicitly to denote different versions of SOAP or the
346           like.
347
348       encprefix(QName)
349               $client->encprefix('enc');
350
351           This method is a shortcut for:
352
353               $client->serializer->encprefix(QName);
354
355           Gets or sets the namespace prefix for the encoding rules namespace.
356           The default value is SOAP-ENC.
357
358       While it may seem to be an unnecessary operation to set a value that
359       isn't relevant to the message, such as the namespace labels for the
360       envelope and encoding URNs, the ability to set these labels explicitly
361       can prove to be a great aid in distinguishing and debugging messages on
362       the server side of operations.
363
364       encoding(encoding URN)
365               $client->encoding($soap_12_encoding_URN);
366
367           This method is a shortcut for:
368
369               $client->serializer->encoding(args);
370
371           Where the earlier method dealt with the label used for the
372           attributes related to the SOAP encoding scheme, this method
373           actually sets the URN to be specified as the encoding scheme for
374           the message. The default is to specify the encoding for SOAP 1.1,
375           so this is handy for applications that need to encode according to
376           SOAP 1.2 rules.
377
378       typelookup
379               $client->typelookup;
380
381           This method is a shortcut for:
382
383               $client->serializer->typelookup;
384
385           Gives the application access to the type-lookup table from the
386           serializer object. See the section on SOAP::Serializer.
387
388       uri(service specifier)
389           Deprecated - the "uri" subroutine is deprecated in order to provide
390           a more intuitive naming scheme for subroutines that set namespaces.
391           In the future, you will be required to use either the "ns()" or
392           "default_ns()" subroutines instead of "uri()".
393
394               $client->uri($service_uri);
395
396           This method is a shortcut for:
397
398               $client->serializer->uri(service);
399
400           The URI associated with this accessor on a client object is the
401           service-specifier for the request, often encoded for HTTP-based
402           requests as the SOAPAction header. While the names may seem
403           confusing, this method doesn't specify the endpoint itself. In most
404           circumstances, the "uri" refers to the namespace used for the
405           request.
406
407           Often times, the value may look like a valid URL. Despite this, it
408           doesn't have to point to an existing resource (and often doesn't).
409           This method sets and retrieves this value from the object. Note
410           that no transport code is triggered by this because it has no
411           direct effect on the transport of the object.
412
413       multirefinplace(boolean)
414               $client->multirefinplace(1);
415
416           This method is a shortcut for:
417
418               $client->serializer->multirefinplace(boolean);
419
420           Controls how the serializer handles values that have multiple
421           references to them. Recall from previous SOAP chapters that a value
422           may be tagged with an identifier, then referred to in several
423           places. When this is the case for a value, the serializer defaults
424           to putting the data element towards the top of the message, right
425           after the opening tag of the method-specification. It is serialized
426           as a standalone entity with an ID that is then referenced at the
427           relevant places later on. If this method is used to set a true
428           value, the behavior is different. When the multirefinplace
429           attribute is true, the data is serialized at the first place that
430           references it, rather than as a separate element higher up in the
431           body. This is more compact but may be harder to read or trace in a
432           debugging environment.
433
434       parts( ARRAY )
435           Used to specify an array of MIME::Entity's to be attached to the
436           transmitted SOAP message. Attachments that are returned in a
437           response can be accessed by "SOAP::SOM::parts()".
438
439       self
440               $ref = SOAP::Lite->self;
441
442           Returns an object reference to the default global object the
443           "SOAP::Lite" package maintains. This is the object that processes
444           many of the arguments when provided on the use line.
445
446       The following method isn't an accessor style of method but neither does
447       it fit with the group that immediately follows it:
448
449       call(arguments)
450               $client->call($method => @arguments);
451
452           As has been illustrated in previous chapters, the "SOAP::Lite"
453           client objects can manage remote calls with auto-dispatching using
454           some of Perl's more elaborate features. call is used when the
455           application wants a greater degree of control over the details of
456           the call itself. The method may be built up from a SOAP::Data
457           object, so as to allow full control over the namespace associated
458           with the tag, as well as other attributes like encoding. This is
459           also important for calling methods that contain characters not
460           allowable in Perl function names, such as A.B.C.
461
462       The next four methods used in the "SOAP::Lite" class are geared towards
463       handling the types of events than can occur during the message
464       lifecycle. Each of these sets up a callback for the event in question:
465
466       on_action(callback)
467               $client->on_action(sub { qq("$_[0]") });
468
469           Triggered when the transport object sets up the SOAPAction header
470           for an HTTP-based call. The default is to set the header to the
471           string, uri#method, in which URI is the value set by the uri method
472           described earlier, and method is the name of the method being
473           called. When called, the routine referenced (or the closure, if
474           specified as in the example) is given two arguments, uri and
475           method, in that order.
476
477           .NET web services usually expect "/" as separator for "uri" and
478           "method".  To change SOAP::Lite's behaviour to use uri/method as
479           SOAPAction header, use the following code:
480
481               $client->on_action( sub { join '/', @_ } );
482
483       on_fault(callback)
484               $client->on_fault(sub { popup_dialog($_[1]) });
485
486           Triggered when a method call results in a fault response from the
487           server.  When it is called, the argument list is first the client
488           object itself, followed by the object that encapsulates the fault.
489           In the example, the fault object is passed (without the client
490           object) to a hypothetical GUI function that presents an error
491           dialog with the text of fault extracted from the object (which is
492           covered shortly under the SOAP::SOM methods).
493
494       on_nonserialized(callback)
495               $client->on_nonserialized(sub { die "$_[0]?!?" });
496
497           Occasionally, the serializer may be given data it can't turn into
498           SOAP-savvy XML; for example, if a program bug results in a code
499           reference or something similar being passed in as a parameter to
500           method call. When that happens, this callback is activated, with
501           one argument. That argument is the data item that could not be
502           understood. It will be the only argument. If the routine returns,
503           the return value is pasted into the message as the serialization.
504           Generally, an error is in order, and this callback allows for
505           control over signaling that error.
506
507       on_debug(callback)
508               $client->on_debug(sub { print @_ });
509
510           Deprecated. Use the global +debug and +trace facilities described
511           in SOAP::Trace
512
513           Note that this method will not work as expected: Instead of
514           affecting the debugging behaviour of the object called on, it will
515           globally affect the debugging behaviour for all objects of that
516           class.
517

WRITING A SOAP CLIENT

519       This chapter guides you to writing a SOAP client by example.
520
521       The SOAP service to be accessed is a simple variation of the well-known
522       hello world program. It accepts two parameters, a name and a given
523       name, and returns "Hello $given_name $name".
524
525       We will use "Martin Kutter" as the name for the call, so all variants
526       will print the following message on success:
527
528        Hello Martin Kutter!
529
530   SOAP message styles
531       There are three common (and one less common) variants of SOAP messages.
532
533       These address the message style (positional parameters vs. specified
534       message documents) and encoding (as-is vs. typed).
535
536       The different message styles are:
537
538       ·   rpc/encoded
539
540           Typed, positional parameters. Widely used in scripting languages.
541           The type of the arguments is included in the message.  Arrays and
542           the like may be encoded using SOAP encoding rules (or others).
543
544       ·   rpc/literal
545
546           As-is, positional parameters. The type of arguments is defined by
547           some pre-exchanged interface definition.
548
549       ·   document/encoded
550
551           Specified message with typed elements. Rarely used.
552
553       ·   document/literal
554
555           Specified message with as-is elements. The message specification
556           and element types are defined by some pre-exchanged interface
557           definition.
558
559       As of 2008, document/literal has become the predominant SOAP message
560       variant. rpc/literal and rpc/encoded are still in use, mainly with
561       scripting languages, while document/encoded is hardly used at all.
562
563       You will see clients for the rpc/encoded and document/literal SOAP
564       variants in this section.
565
566   Example implementations
567       RPC/ENCODED
568
569       Rpc/encoded is most popular with scripting languages like perl, php and
570       python without the use of a WSDL. Usual method descriptions look like
571       this:
572
573        Method: sayHello(string, string)
574        Parameters:
575           name: string
576           givenName: string
577
578       Such a description usually means that you can call a method named
579       "sayHello" with two positional parameters, "name" and "givenName",
580       which both are strings.
581
582       The message corresponding to this description looks somewhat like this:
583
584        <sayHello xmlns="urn:HelloWorld">
585          <s-gensym01 xsi:type="xsd:string">Kutter</s-gensym01>
586          <s-gensym02 xsi:type="xsd:string">Martin</s-gensym02>
587        </sayHello>
588
589       Any XML tag names may be used instead of the "s-gensym01" stuff -
590       parameters are positional, the tag names have no meaning.
591
592       A client producing such a call is implemented like this:
593
594        use SOAP::Lite;
595        my $soap = SOAP::Lite->new( proxy => 'http://localhost:81/soap-wsdl-test/helloworld.pl');
596        $soap->default_ns('urn:HelloWorld');
597        my $som = $soap->call('sayHello', 'Kutter', 'Martin');
598        die $som->faultstring if ($som->fault);
599        print $som->result, "\n";
600
601       You can of course use a one-liner, too...
602
603       Sometimes, rpc/encoded interfaces are described with WSDL definitions.
604       A WSDL accepting "named" parameters with rpc/encoded looks like this:
605
606        <definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
607          xmlns:s="http://www.w3.org/2001/XMLSchema"
608          xmlns:s0="urn:HelloWorld"
609          targetNamespace="urn:HelloWorld"
610          xmlns="http://schemas.xmlsoap.org/wsdl/">
611          <types>
612            <s:schema targetNamespace="urn:HelloWorld">
613            </s:schema>
614          </types>
615          <message name="sayHello">
616            <part name="name" type="s:string" />
617            <part name="givenName" type="s:string" />
618          </message>
619          <message name="sayHelloResponse">
620            <part name="sayHelloResult" type="s:string" />
621          </message>
622
623          <portType name="Service1Soap">
624            <operation name="sayHello">
625              <input message="s0:sayHello" />
626              <output message="s0:sayHelloResponse" />
627            </operation>
628          </portType>
629
630          <binding name="Service1Soap" type="s0:Service1Soap">
631            <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
632                style="rpc" />
633            <operation name="sayHello">
634              <soap:operation soapAction="urn:HelloWorld#sayHello"/>
635              <input>
636                <soap:body use="encoded"
637                  encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
638              </input>
639              <output>
640                <soap:body use="encoded"
641                  encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
642              </output>
643            </operation>
644          </binding>
645          <service name="HelloWorld">
646            <port name="HelloWorldSoap" binding="s0:Service1Soap">
647              <soap:address location="http://localhost:81/soap-wsdl-test/helloworld.pl" />
648            </port>
649          </service>
650        </definitions>
651
652       The message corresponding to this schema looks like this:
653
654        <sayHello xmlns="urn:HelloWorld">
655          <name xsi:type="xsd:string">Kutter</name>
656          <givenName xsi:type="xsd:string">Martin</givenName>
657        </sayHello>
658
659       A web service client using this schema looks like this:
660
661        use SOAP::Lite;
662        my $soap = SOAP::Lite->service("file:say_hello_rpcenc.wsdl");
663        eval { my $result = $soap->sayHello('Kutter', 'Martin'); };
664        if ($@) {
665            die $@;
666        }
667        print $som->result();
668
669       You may of course also use the following one-liner:
670
671        perl -MSOAP::Lite -e 'print SOAP::Lite->service("file:say_hello_rpcenc.wsdl")\
672          ->sayHello('Kutter', 'Martin'), "\n";'
673
674       A web service client (without a service description) looks like this.
675
676        use SOAP::Lite;
677        my $soap = SOAP::Lite->new( proxy => 'http://localhost:81/soap-wsdl-test/helloworld.pl');
678        $soap->default_ns('urn:HelloWorld');
679        my $som = $soap->call('sayHello',
680           SOAP::Data->name('name')->value('Kutter'),
681           SOAP::Data->name('givenName')->value('Martin')
682        );
683        die $som->faultstring if ($som->fault);
684        print $som->result, "\n";
685
686       RPC/LITERAL
687
688       SOAP web services using the document/literal message encoding are
689       usually described by some Web Service Definition. Our web service has
690       the following WSDL description:
691
692        <definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
693          xmlns:s="http://www.w3.org/2001/XMLSchema"
694          xmlns:s0="urn:HelloWorld"
695          targetNamespace="urn:HelloWorld"
696          xmlns="http://schemas.xmlsoap.org/wsdl/">
697          <types>
698            <s:schema targetNamespace="urn:HelloWorld">
699              <s:complexType name="sayHello">
700                <s:sequence>
701                  <s:element minOccurs="0" maxOccurs="1" name="name"
702                     type="s:string" />
703                  <s:element minOccurs="0" maxOccurs="1" name="givenName"
704                     type="s:string" nillable="1" />
705                </s:sequence>
706              </s:complexType>
707
708              <s:complexType name="sayHelloResponse">
709                <s:sequence>
710                  <s:element minOccurs="0" maxOccurs="1" name="sayHelloResult"
711                     type="s:string" />
712                </s:sequence>
713              </s:complexType>
714            </s:schema>
715          </types>
716          <message name="sayHello">
717            <part name="parameters" type="s0:sayHello" />
718          </message>
719          <message name="sayHelloResponse">
720            <part name="parameters" type="s0:sayHelloResponse" />
721          </message>
722
723          <portType name="Service1Soap">
724            <operation name="sayHello">
725              <input message="s0:sayHello" />
726              <output message="s0:sayHelloResponse" />
727            </operation>
728          </portType>
729
730          <binding name="Service1Soap" type="s0:Service1Soap">
731            <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
732                style="rpc" />
733            <operation name="sayHello">
734              <soap:operation soapAction="urn:HelloWorld#sayHello"/>
735              <input>
736                <soap:body use="literal" namespace="urn:HelloWorld"/>
737              </input>
738              <output>
739                <soap:body use="literal" namespace="urn:HelloWorld"/>
740              </output>
741            </operation>
742          </binding>
743          <service name="HelloWorld">
744            <port name="HelloWorldSoap" binding="s0:Service1Soap">
745              <soap:address location="http://localhost:80//helloworld.pl" />
746            </port>
747          </service>
748         </definitions>
749
750       The XML message (inside the SOAP Envelope) look like this:
751
752        <ns0:sayHello xmlns:ns0="urn:HelloWorld">
753           <parameters>
754             <name>Kutter</name>
755             <givenName>Martin</givenName>
756           </parameters>
757        </ns0:sayHello>
758
759        <sayHelloResponse xmlns:ns0="urn:HelloWorld">
760           <parameters>
761               <sayHelloResult>Hello Martin Kutter!</sayHelloResult>
762           </parameters>
763        </sayHelloResponse>
764
765       This is the SOAP::Lite implementation for the web service client:
766
767        use SOAP::Lite +trace;
768        my $soap = SOAP::Lite->new( proxy => 'http://localhost:80/helloworld.pl');
769
770        $soap->on_action( sub { "urn:HelloWorld#sayHello" });
771        $soap->autotype(0)->readable(1);
772        $soap->default_ns('urn:HelloWorld');
773
774        my $som = $soap->call('sayHello', SOAP::Data->name('parameters')->value(
775           \SOAP::Data->value([
776               SOAP::Data->name('name')->value( 'Kutter' ),
777               SOAP::Data->name('givenName')->value('Martin'),
778           ]))
779       );
780
781        die $som->fault->{ faultstring } if ($som->fault);
782        print $som->result, "\n";
783
784       DOCUMENT/LITERAL
785
786       SOAP web services using the document/literal message encoding are
787       usually described by some Web Service Definition. Our web service has
788       the following WSDL description:
789
790        <definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
791           xmlns:s="http://www.w3.org/2001/XMLSchema"
792           xmlns:s0="urn:HelloWorld"
793           targetNamespace="urn:HelloWorld"
794           xmlns="http://schemas.xmlsoap.org/wsdl/">
795          <types>
796            <s:schema targetNamespace="urn:HelloWorld">
797              <s:element name="sayHello">
798                <s:complexType>
799                  <s:sequence>
800                     <s:element minOccurs="0" maxOccurs="1" name="name" type="s:string" />
801                      <s:element minOccurs="0" maxOccurs="1" name="givenName" type="s:string" nillable="1" />
802                  </s:sequence>
803                 </s:complexType>
804               </s:element>
805
806               <s:element name="sayHelloResponse">
807                 <s:complexType>
808                   <s:sequence>
809                     <s:element minOccurs="0" maxOccurs="1" name="sayHelloResult" type="s:string" />
810                   </s:sequence>
811               </s:complexType>
812             </s:element>
813           </types>
814           <message name="sayHelloSoapIn">
815             <part name="parameters" element="s0:sayHello" />
816           </message>
817           <message name="sayHelloSoapOut">
818             <part name="parameters" element="s0:sayHelloResponse" />
819           </message>
820
821           <portType name="Service1Soap">
822             <operation name="sayHello">
823               <input message="s0:sayHelloSoapIn" />
824               <output message="s0:sayHelloSoapOut" />
825             </operation>
826           </portType>
827
828           <binding name="Service1Soap" type="s0:Service1Soap">
829             <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
830                 style="document" />
831             <operation name="sayHello">
832               <soap:operation soapAction="urn:HelloWorld#sayHello"/>
833               <input>
834                 <soap:body use="literal" />
835               </input>
836               <output>
837                 <soap:body use="literal" />
838               </output>
839             </operation>
840           </binding>
841           <service name="HelloWorld">
842             <port name="HelloWorldSoap" binding="s0:Service1Soap">
843               <soap:address location="http://localhost:80//helloworld.pl" />
844             </port>
845           </service>
846        </definitions>
847
848       The XML message (inside the SOAP Envelope) look like this:
849
850        <sayHello xmlns="urn:HelloWorld">
851          <name>Kutter</name>
852          <givenName>Martin</givenName>
853        </sayHello>
854
855        <sayHelloResponse>
856          <sayHelloResult>Hello Martin Kutter!</sayHelloResult>
857        </sayHelloResponse>
858
859       You can call this web service with the following client code:
860
861        use SOAP::Lite;
862        my $soap = SOAP::Lite->new( proxy => 'http://localhost:80/helloworld.pl');
863
864        $soap->on_action( sub { "urn:HelloWorld#sayHello" });
865        $soap->autotype(0);
866        $soap->default_ns('urn:HelloWorld');
867
868        my $som = $soap->call("sayHello",
869           SOAP::Data->name('name')->value( 'Kutter' ),
870           SOAP::Data->name('givenName')->value('Martin'),
871       );
872
873        die $som->fault->{ faultstring } if ($som->fault);
874        print $som->result, "\n";
875
876   Differences between the implementations
877       You may have noticed that there's little difference between the
878       rpc/encoded, rpc/literal and the document/literal example's
879       implementation. In fact, from SOAP::Lite's point of view, the only
880       differences between rpc/literal and document/literal that parameters
881       are always named.
882
883       In our example, the rpc/encoded variant already used named parameters
884       (by using two messages), so there's no difference at all.
885
886       You may have noticed the somewhat strange idiom for passing a list of
887       named parameters in the rpc/literal example:
888
889        my $som = $soap->call('sayHello', SOAP::Data->name('parameters')->value(
890           \SOAP::Data->value([
891               SOAP::Data->name('name')->value( 'Kutter' ),
892               SOAP::Data->name('givenName')->value('Martin'),
893           ]))
894        );
895
896       While SOAP::Data provides full control over the XML generated, passing
897       hash-like structures require additional coding.
898

WRITING A SOAP SERVER

900       See SOAP::Server, or SOAP::Transport.
901

FEATURES

903   ATTACHMENTS
904       "SOAP::Lite" features support for the SOAP with Attachments
905       specification.  Currently, SOAP::Lite only supports MIME based
906       attachments. DIME based attachments are yet to be fully functional.
907
908       EXAMPLES
909
910       Client sending an attachment
911
912       "SOAP::Lite" clients can specify attachments to be sent along with a
913       request by using the "SOAP::Lite::parts()" method, which takes as an
914       argument an ARRAY of "MIME::Entity"'s.
915
916         use SOAP::Lite;
917         use MIME::Entity;
918         my $ent = build MIME::Entity
919           Type        => "image/gif",
920           Encoding    => "base64",
921           Path        => "somefile.gif",
922           Filename    => "saveme.gif",
923           Disposition => "attachment";
924         my $som = SOAP::Lite
925           ->uri($SOME_NAMESPACE)
926           ->parts([ $ent ])
927           ->proxy($SOME_HOST)
928           ->some_method(SOAP::Data->name("foo" => "bar"));
929
930       Client retrieving an attachment
931
932       A client accessing attachments that were returned in a response by
933       using the "SOAP::SOM::parts()" accessor.
934
935         use SOAP::Lite;
936         use MIME::Entity;
937         my $soap = SOAP::Lite
938           ->uri($NS)
939           ->proxy($HOST);
940         my $som = $soap->foo();
941         foreach my $part (${$som->parts}) {
942           print $part->stringify;
943         }
944
945       Server receiving an attachment
946
947       Servers, like clients, use the SOAP::SOM module to access attachments
948       transmitted to it.
949
950         package Attachment;
951         use SOAP::Lite;
952         use MIME::Entity;
953         use strict;
954         use vars qw(@ISA);
955         @ISA = qw(SOAP::Server::Parameters);
956         sub someMethod {
957           my $self = shift;
958           my $envelope = pop;
959           foreach my $part (@{$envelope->parts}) {
960             print "AttachmentService: attachment found! (".ref($part).")\n";
961           }
962           # do something
963         }
964
965       Server responding with an attachment
966
967       Servers wishing to return an attachment to the calling client need only
968       return "MIME::Entity" objects along with SOAP::Data elements, or any
969       other data intended for the response.
970
971         package Attachment;
972         use SOAP::Lite;
973         use MIME::Entity;
974         use strict;
975         use vars qw(@ISA);
976         @ISA = qw(SOAP::Server::Parameters);
977         sub someMethod {
978           my $self = shift;
979           my $envelope = pop;
980           my $ent = build MIME::Entity
981           'Id'          => "<1234>",
982           'Type'        => "text/xml",
983           'Path'        => "some.xml",
984           'Filename'    => "some.xml",
985           'Disposition' => "attachment";
986           return SOAP::Data->name("foo" => "blah blah blah"),$ent;
987         }
988
989   DEFAULT SETTINGS
990       Though this feature looks similar to autodispatch they have (almost)
991       nothing in common. This capability allows you specify default settings
992       so that all objects created after that will be initialized with the
993       proper default settings.
994
995       If you wish to provide common "proxy()" or "uri()" settings for all
996       "SOAP::Lite" objects in your application you may do:
997
998         use SOAP::Lite
999           proxy => 'http://localhost/cgi-bin/soap.cgi',
1000           uri => 'http://my.own.com/My/Examples';
1001
1002         my $soap1 = new SOAP::Lite; # will get the same proxy()/uri() as above
1003         print $soap1->getStateName(1)->result;
1004
1005         my $soap2 = SOAP::Lite->new; # same thing as above
1006         print $soap2->getStateName(2)->result;
1007
1008         # or you may override any settings you want
1009         my $soap3 = SOAP::Lite->proxy('http://localhost/');
1010         print $soap3->getStateName(1)->result;
1011
1012       Any "SOAP::Lite" properties can be propagated this way. Changes in
1013       object copies will not affect global settings and you may still change
1014       global settings with "SOAP::Lite->self" call which returns reference to
1015       global object. Provided parameter will update this object and you can
1016       even set it to "undef":
1017
1018         SOAP::Lite->self(undef);
1019
1020       The "use SOAP::Lite" syntax also lets you specify default event
1021       handlers for your code. If you have different SOAP objects and want to
1022       share the same "on_action()" (or "on_fault()" for that matter) handler.
1023       You can specify "on_action()" during initialization for every object,
1024       but you may also do:
1025
1026         use SOAP::Lite
1027           on_action => sub {sprintf '%s#%s', @_};
1028
1029       and this handler will be the default handler for all your SOAP objects.
1030       You can override it if you specify a handler for a particular object.
1031       See t/*.t for example of on_fault() handler.
1032
1033       Be warned, that since "use ..." is executed at compile time all "use"
1034       statements will be executed before script execution that can make
1035       unexpected results. Consider code:
1036
1037         use SOAP::Lite proxy => 'http://localhost/';
1038         print SOAP::Lite->getStateName(1)->result;
1039
1040         use SOAP::Lite proxy => 'http://localhost/cgi-bin/soap.cgi';
1041         print SOAP::Lite->getStateName(1)->result;
1042
1043       Both SOAP calls will go to 'http://localhost/cgi-bin/soap.cgi'. If you
1044       want to execute "use" at run-time, put it in "eval":
1045
1046         eval "use SOAP::Lite proxy => 'http://localhost/cgi-bin/soap.cgi'; 1" or die;
1047
1048       Or alternatively,
1049
1050         SOAP::Lite->self->proxy('http://localhost/cgi-bin/soap.cgi');
1051
1052   SETTING MAXIMUM MESSAGE SIZE
1053       One feature of "SOAP::Lite" is the ability to control the maximum size
1054       of a message a SOAP::Lite server will be allowed to process. To control
1055       this feature simply define $SOAP::Constants::MAX_CONTENT_SIZE in your
1056       code like so:
1057
1058         use SOAP::Transport::HTTP;
1059         use MIME::Entity;
1060         $SOAP::Constants::MAX_CONTENT_SIZE = 10000;
1061         SOAP::Transport::HTTP::CGI
1062           ->dispatch_to('TemperatureService')
1063           ->handle;
1064
1065   IN/OUT, OUT PARAMETERS AND AUTOBINDING
1066       "SOAP::Lite" gives you access to all parameters (both in/out and out)
1067       and also does some additional work for you. Lets consider following
1068       example:
1069
1070         <mehodResponse>
1071           <res1>name1</res1>
1072           <res2>name2</res2>
1073           <res3>name3</res3>
1074         </mehodResponse>
1075
1076       In that case:
1077
1078         $result = $r->result; # gives you 'name1'
1079         $paramout1 = $r->paramsout;      # gives you 'name2', because of scalar context
1080         $paramout1 = ($r->paramsout)[0]; # gives you 'name2' also
1081         $paramout2 = ($r->paramsout)[1]; # gives you 'name3'
1082
1083       or
1084
1085         @paramsout = $r->paramsout; # gives you ARRAY of out parameters
1086         $paramout1 = $paramsout[0]; # gives you 'res2', same as ($r->paramsout)[0]
1087         $paramout2 = $paramsout[1]; # gives you 'res3', same as ($r->paramsout)[1]
1088
1089       Generally, if server returns "return (1,2,3)" you will get 1 as the
1090       result and 2 and 3 as out parameters.
1091
1092       If the server returns "return [1,2,3]" you will get an ARRAY reference
1093       from "result()" and "undef" from "paramsout()".
1094
1095       Results can be arbitrary complex: they can be an array references, they
1096       can be objects, they can be anything and still be returned by
1097       "result()" . If only one parameter is returned, "paramsout()" will
1098       return "undef".
1099
1100       Furthermore, if you have in your output parameters a parameter with the
1101       same signature (name+type) as in the input parameters this parameter
1102       will be mapped into your input automatically. For example:
1103
1104       Server Code:
1105
1106         sub mymethod {
1107           shift; # object/class reference
1108           my $param1 = shift;
1109           my $param2 = SOAP::Data->name('myparam' => shift() * 2);
1110           return $param1, $param2;
1111         }
1112
1113       Client Code:
1114
1115         $a = 10;
1116         $b = SOAP::Data->name('myparam' => 12);
1117         $result = $soap->mymethod($a, $b);
1118
1119       After that, "$result == 10 and $b->value == 24"! Magic? Sort of.
1120
1121       Autobinding gives it to you. That will work with objects also with one
1122       difference: you do not need to worry about the name and the type of
1123       object parameter. Consider the "PingPong" example
1124       (examples/My/PingPong.pm and examples/pingpong.pl):
1125
1126       Server Code:
1127
1128         package My::PingPong;
1129
1130         sub new {
1131           my $self = shift;
1132           my $class = ref($self) || $self;
1133           bless {_num=>shift} => $class;
1134         }
1135
1136         sub next {
1137           my $self = shift;
1138           $self->{_num}++;
1139         }
1140
1141       Client Code:
1142
1143         use SOAP::Lite +autodispatch =>
1144           uri => 'urn:',
1145           proxy => 'http://localhost/';
1146
1147         my $p = My::PingPong->new(10); # $p->{_num} is 10 now, real object returned
1148         print $p->next, "\n";          # $p->{_num} is 11 now!, object autobinded
1149
1150   STATIC AND DYNAMIC SERVICE DEPLOYMENT
1151       Let us scrutinize the deployment process. When designing your SOAP
1152       server you can consider two kind of deployment: static and dynamic. For
1153       both, static and dynamic,  you should specify "MODULE",
1154       "MODULE::method", "method" or "PATH/" when creating "use"ing the
1155       SOAP::Lite module. The difference between static and dynamic deployment
1156       is that in case of 'dynamic', any module which is not present will be
1157       loaded on demand. See the "SECURITY" section for detailed description.
1158
1159       When statically deploying a SOAP Server, you need to know all modules
1160       handling SOAP requests before.
1161
1162       Dynamic deployment allows extending your SOAP Server's interface by
1163       just installing another module into the dispatch_to path (see below).
1164
1165       STATIC DEPLOYMENT EXAMPLE
1166
1167         use SOAP::Transport::HTTP;
1168         use My::Examples;           # module is preloaded
1169
1170         SOAP::Transport::HTTP::CGI
1171            # deployed module should be present here or client will get
1172            # 'access denied'
1173           -> dispatch_to('My::Examples')
1174           -> handle;
1175
1176       For static deployment you should specify the MODULE name directly.
1177
1178       You should also use static binding when you have several different
1179       classes in one file and want to make them available for SOAP calls.
1180
1181       DYNAMIC DEPLOYMENT EXAMPLE
1182
1183         use SOAP::Transport::HTTP;
1184         # name is unknown, module will be loaded on demand
1185
1186         SOAP::Transport::HTTP::CGI
1187           # deployed module should be present here or client will get 'access denied'
1188           -> dispatch_to('/Your/Path/To/Deployed/Modules', 'My::Examples')
1189           -> handle;
1190
1191       For dynamic deployment you can specify the name either directly (in
1192       that case it will be "require"d without any restriction) or indirectly,
1193       with a PATH. In that case, the ONLY path that will be available will be
1194       the PATH given to the dispatch_to() method). For information how to
1195       handle this situation see "SECURITY" section.
1196
1197       SUMMARY
1198
1199         dispatch_to(
1200           # dynamic dispatch that allows access to ALL modules in specified directory
1201           PATH/TO/MODULES
1202           # 1. specifies directory
1203           # -- AND --
1204           # 2. gives access to ALL modules in this directory without limits
1205
1206           # static dispatch that allows access to ALL methods in particular MODULE
1207           MODULE
1208           #  1. gives access to particular module (all available methods)
1209           #  PREREQUISITES:
1210           #    module should be loaded manually (for example with 'use ...')
1211           #    -- OR --
1212           #    you can still specify it in PATH/TO/MODULES
1213
1214           # static dispatch that allows access to particular method ONLY
1215           MODULE::method
1216           # same as MODULE, but gives access to ONLY particular method,
1217           # so there is not much sense to use both MODULE and MODULE::method
1218           # for the same MODULE
1219         );
1220
1221       In addition to this "SOAP::Lite" also supports an experimental syntax
1222       that allows you to bind a specific URL or SOAPAction to a CLASS/MODULE
1223       or object.
1224
1225       For example:
1226
1227         dispatch_with({
1228           URI => MODULE,        # 'http://www.soaplite.com/' => 'My::Class',
1229           SOAPAction => MODULE, # 'http://www.soaplite.com/method' => 'Another::Class',
1230           URI => object,        # 'http://www.soaplite.com/obj' => My::Class->new,
1231         })
1232
1233       "URI" is checked before "SOAPAction". You may use both the
1234       "dispatch_to()" and "dispatch_with()" methods in the same server, but
1235       note that "dispatch_with()" has a higher order of precedence.
1236       "dispatch_to()" will be checked only after "URI" and "SOAPAction" has
1237       been checked.
1238
1239       See also: EXAMPLE APACHE::REGISTRY USAGE, "SECURITY"
1240
1241   COMPRESSION
1242       "SOAP::Lite" provides you option to enable transparent compression over
1243       the wire. Compression can be enabled by specifying a threshold value
1244       (in the form of kilobytes) for compression on both the client and
1245       server sides:
1246
1247       Note: Compression currently only works for HTTP based servers and
1248       clients.
1249
1250       Client Code
1251
1252         print SOAP::Lite
1253           ->uri('http://localhost/My/Parameters')
1254           ->proxy('http://localhost/', options => {compress_threshold => 10000})
1255           ->echo(1 x 10000)
1256           ->result;
1257
1258       Server Code
1259
1260         my $server = SOAP::Transport::HTTP::CGI
1261           ->dispatch_to('My::Parameters')
1262           ->options({compress_threshold => 10000})
1263           ->handle;
1264
1265       For more information see COMPRESSION in HTTP::Transport.
1266

SECURITY

1268       For security reasons, the existing path for Perl modules (@INC) will be
1269       disabled once you have chosen dynamic deployment and specified your own
1270       "PATH/". If you wish to access other modules in your included package
1271       you have several options:
1272
1273       1.  Switch to static linking:
1274
1275              use MODULE;
1276              $server->dispatch_to('MODULE');
1277
1278           Which can also be useful when you want to import something specific
1279           from the deployed modules:
1280
1281              use MODULE qw(import_list);
1282
1283       2.  Change "use" to "require". The path is only unavailable during the
1284           initialization phase. It is available once more during execution.
1285           Therefore, if you utilize "require" somewhere in your package, it
1286           will work.
1287
1288       3.  Wrap "use" in an "eval" block:
1289
1290              eval 'use MODULE qw(import_list)'; die if $@;
1291
1292       4.  Set your include path in your package and then specify "use". Don't
1293           forget to put @INC in a "BEGIN{}" block or it won't work. For
1294           example,
1295
1296              BEGIN { @INC = qw(my_directory); use MODULE }
1297

INTEROPERABILITY

1299   Microsoft .NET client with SOAP::Lite Server
1300       In order to use a .NET client with a SOAP::Lite server, be sure you use
1301       fully qualified names for your return values. For example:
1302
1303         return SOAP::Data->name('myname')
1304                          ->type('string')
1305                          ->uri($MY_NAMESPACE)
1306                          ->value($output);
1307
1308       In addition see comment about default encoding in .NET Web Services
1309       below.
1310
1311   SOAP::Lite client with a .NET server
1312       If experiencing problems when using a SOAP::Lite client to call a .NET
1313       Web service, it is recommended you check, or adhere to all of the
1314       following recommendations:
1315
1316       Declare a proper soapAction in your call
1317           For example, use "on_action( sub {
1318           'http://www.myuri.com/WebService.aspx#someMethod'; } )".
1319
1320       Disable charset definition in Content-type header
1321           Some users have said that Microsoft .NET prefers the value of the
1322           Content-type header to be a mimetype exclusively, but SOAP::Lite
1323           specifies a character set in addition to the mimetype. This results
1324           in an error similar to:
1325
1326             Server found request content type to be 'text/xml; charset=utf-8',
1327             but expected 'text/xml'
1328
1329           To turn off this behavior specify use the following code:
1330
1331             use SOAP::Lite;
1332             $SOAP::Constants::DO_NOT_USE_CHARSET = 1;
1333             # The rest of your code
1334
1335       Use fully qualified name for method parameters
1336           For example, the following code is preferred:
1337
1338             SOAP::Data->name(Query  => 'biztalk')
1339                       ->uri('http://tempuri.org/')
1340
1341           As opposed to:
1342
1343             SOAP::Data->name('Query'  => 'biztalk')
1344
1345       Place method in default namespace
1346           For example, the following code is preferred:
1347
1348             my $method = SOAP::Data->name('add')
1349                                    ->attr({xmlns => 'http://tempuri.org/'});
1350             my @rc = $soap->call($method => @parms)->result;
1351
1352           As opposed to:
1353
1354             my @rc = $soap->call(add => @parms)->result;
1355             # -- OR --
1356             my @rc = $soap->add(@parms)->result;
1357
1358       Disable use of explicit namespace prefixes
1359           Some user's have reported that .NET will simply not parse messages
1360           that use namespace prefixes on anything but SOAP elements
1361           themselves. For example, the following XML would not be parsed:
1362
1363             <SOAP-ENV:Envelope ...attributes skipped>
1364               <SOAP-ENV:Body>
1365                 <namesp1:mymethod xmlns:namesp1="urn:MyURI" />
1366               </SOAP-ENV:Body>
1367             </SOAP-ENV:Envelope>
1368
1369           SOAP::Lite allows users to disable the use of explicit namespaces
1370           through the "use_prefix()" method. For example, the following code:
1371
1372             $som = SOAP::Lite->uri('urn:MyURI')
1373                              ->proxy($HOST)
1374                              ->use_prefix(0)
1375                              ->myMethod();
1376
1377           Will result in the following XML, which is more palatable by .NET:
1378
1379             <SOAP-ENV:Envelope ...attributes skipped>
1380               <SOAP-ENV:Body>
1381                 <mymethod xmlns="urn:MyURI" />
1382               </SOAP-ENV:Body>
1383             </SOAP-ENV:Envelope>
1384
1385       Modify your .NET server, if possible
1386           Stefan Pharies <stefanph@microsoft.com>:
1387
1388           SOAP::Lite uses the SOAP encoding (section 5 of the soap 1.1 spec),
1389           and the default for .NET Web Services is to use a literal encoding.
1390           So elements in the request are unqualified, but your service
1391           expects them to be qualified. .Net Web Services has a way for you
1392           to change the expected message format, which should allow you to
1393           get your interop working.  At the top of your class in the asmx,
1394           add this attribute (for Beta 1):
1395
1396             [SoapService(Style=SoapServiceStyle.RPC)]
1397
1398           Another source said it might be this attribute (for Beta 2):
1399
1400             [SoapRpcService]
1401
1402           Full Web Service text may look like:
1403
1404             <%@ WebService Language="C#" Class="Test" %>
1405             using System;
1406             using System.Web.Services;
1407             using System.Xml.Serialization;
1408
1409             [SoapService(Style=SoapServiceStyle.RPC)]
1410             public class Test : WebService {
1411               [WebMethod]
1412               public int add(int a, int b) {
1413                 return a + b;
1414               }
1415             }
1416
1417           Another example from Kirill Gavrylyuk <kirillg@microsoft.com>:
1418
1419           "You can insert [SoapRpcService()] attribute either on your class
1420           or on operation level".
1421
1422             <%@ WebService Language=CS class="DataType.StringTest"%>
1423
1424             namespace DataType {
1425
1426               using System;
1427               using System.Web.Services;
1428               using System.Web.Services.Protocols;
1429               using System.Web.Services.Description;
1430
1431              [SoapRpcService()]
1432              public class StringTest: WebService {
1433                [WebMethod]
1434                [SoapRpcMethod()]
1435                public string RetString(string x) {
1436                  return(x);
1437                }
1438              }
1439            }
1440
1441           Example from Yann Christensen <yannc@microsoft.com>:
1442
1443             using System;
1444             using System.Web.Services;
1445             using System.Web.Services.Protocols;
1446
1447             namespace Currency {
1448               [WebService(Namespace="http://www.yourdomain.com/example")]
1449               [SoapRpcService]
1450               public class Exchange {
1451                 [WebMethod]
1452                 public double getRate(String country, String country2) {
1453                   return 122.69;
1454                 }
1455               }
1456             }
1457
1458       Special thanks goes to the following people for providing the above
1459       description and details on .NET interoperability issues:
1460
1461       Petr Janata <petr.janata@i.cz>,
1462
1463       Stefan Pharies <stefanph@microsoft.com>,
1464
1465       Brian Jepson <bjepson@jepstone.net>, and others
1466

TROUBLESHOOTING

1468       SOAP::Lite serializes "18373" as an integer, but I want it to be a
1469       string!
1470           SOAP::Lite guesses datatypes from the content provided, using a set
1471           of common-sense rules. These rules are not 100% reliable, though
1472           they fit for most data.
1473
1474           You may force the type by passing a SOAP::Data object with a type
1475           specified:
1476
1477            my $proxy = SOAP::Lite->proxy('http://www.example.org/soapservice');
1478            my $som = $proxy->myMethod(
1479                SOAP::Data->name('foo')->value(12345)->type('string')
1480            );
1481
1482           You may also change the precedence of the type-guessing rules. Note
1483           that this means fiddling with SOAP::Lite's internals - this may not
1484           work as expected in future versions.
1485
1486           The example above forces everything to be encoded as string (this
1487           is because the string test is normally last and always returns
1488           true):
1489
1490             my @list = qw(-1 45 foo bar 3838);
1491             my $proxy = SOAP::Lite->uri($uri)->proxy($proxyUrl);
1492             my $lookup = $proxy->serializer->typelookup;
1493             $lookup->{string}->[0] = 0;
1494             $proxy->serializer->typelookup($lookup);
1495             $proxy->myMethod(\@list);
1496
1497           See SOAP::Serializer for more details.
1498
1499       "+autodispatch" doesn't work in Perl 5.8
1500           There is a bug in Perl 5.8's "UNIVERSAL::AUTOLOAD" functionality
1501           that prevents the "+autodispatch" functionality from working
1502           properly. The workaround is to use "dispatch_from" instead. Where
1503           you might normally do something like this:
1504
1505              use Some::Module;
1506              use SOAP::Lite +autodispatch =>
1507                  uri => 'urn:Foo'
1508                  proxy => 'http://...';
1509
1510           You would do something like this:
1511
1512              use SOAP::Lite dispatch_from(Some::Module) =>
1513                  uri => 'urn:Foo'
1514                  proxy => 'http://...';
1515
1516       Problems using SOAP::Lite's COM Interface
1517           Can't call method "server" on undefined value
1518               You probably did not register Lite.dll using "regsvr32
1519               Lite.dll"
1520
1521           Failed to load PerlCtrl Runtime
1522               It is likely that you have install Perl in two different
1523               locations and the location of ActiveState's Perl is not the
1524               first instance of Perl specified in your PATH. To rectify,
1525               rename the directory in which the non-ActiveState Perl is
1526               installed, or be sure the path to ActiveState's Perl is
1527               specified prior to any other instance of Perl in your PATH.
1528
1529       Dynamic libraries are not found
1530           If you are using the Apache web server, and you are seeing
1531           something like the following in your webserver log file:
1532
1533             Can't load '/usr/local/lib/perl5/site_perl/.../XML/Parser/Expat/Expat.so'
1534               for module XML::Parser::Expat: dynamic linker: /usr/local/bin/perl:
1535               libexpat.so.0 is NEEDED, but object does not exist at
1536               /usr/local/lib/perl5/.../DynaLoader.pm line 200.
1537
1538           Then try placing the following into your httpd.conf file and see if
1539           it fixes your problem.
1540
1541            <IfModule mod_env.c>
1542                PassEnv LD_LIBRARY_PATH
1543            </IfModule>
1544
1545       SOAP client reports "500 unexpected EOF before status line seen
1546           See "Apache is crashing with segfaults"
1547
1548       Apache is crashing with segfaults
1549           Using "SOAP::Lite" (or XML::Parser::Expat) in combination with
1550           mod_perl causes random segmentation faults in httpd processes. To
1551           fix, try configuring Apache with the following:
1552
1553            RULE_EXPAT=no
1554
1555           If you are using Apache 1.3.20 and later, try configuring Apache
1556           with the following option:
1557
1558            ./configure --disable-rule=EXPAT
1559
1560           See http://archive.covalent.net/modperl/2000/04/0185.xml for more
1561           details and lot of thanks to Robert Barta <rho@bigpond.net.au> for
1562           explaining this weird behavior.
1563
1564           If this doesn't address the problem, you may wish to try
1565           "-Uusemymalloc", or a similar option in order to instruct Perl to
1566           use the system's own "malloc".
1567
1568           Thanks to Tim Bunce <Tim.Bunce@pobox.com>.
1569
1570       CGI scripts do not work under Microsoft Internet Information Server
1571       (IIS)
1572           CGI scripts may not work under IIS unless scripts use the ".pl"
1573           extension, opposed to ".cgi".
1574
1575       Java SAX parser unable to parse message composed by SOAP::Lite
1576           In some cases SOAP messages created by "SOAP::Lite" may not be
1577           parsed properly by a SAX2/Java XML parser. This is due to a known
1578           bug in "org.xml.sax.helpers.ParserAdapter". This bug manifests
1579           itself when an attribute in an XML element occurs prior to the XML
1580           namespace declaration on which it depends. However, according to
1581           the XML specification, the order of these attributes is not
1582           significant.
1583
1584           http://www.megginson.com/SAX/index.html
1585
1586           Thanks to Steve Alpert (Steve_Alpert@idx.com) for pointing on it.
1587

PERFORMANCE

1589       Processing of XML encoded fragments
1590           "SOAP::Lite" is based on XML::Parser which is basically wrapper
1591           around James Clark's expat parser. Expat's behavior for parsing XML
1592           encoded string can affect processing messages that have lot of
1593           encoded entities, like XML fragments, encoded as strings. Providing
1594           low-level details, parser will call char() callback for every
1595           portion of processed stream, but individually for every processed
1596           entity or newline. It can lead to lot of calls and additional
1597           memory manager expenses even for small messages. By contrast, XML
1598           messages which are encoded as base64Binary, don't have this problem
1599           and difference in processing time can be significant. For XML
1600           encoded string that has about 20 lines and 30 tags, number of call
1601           could be about 100 instead of one for the same string encoded as
1602           base64Binary.
1603
1604           Since it is parser's feature there is NO fix for this behavior (let
1605           me know if you find one), especially because you need to parse
1606           message you already got (and you cannot control content of this
1607           message), however, if your are in charge for both ends of
1608           processing you can switch encoding to base64 on sender's side. It
1609           will definitely work with SOAP::Lite and it may work with other
1610           toolkits/implementations also, but obviously I cannot guarantee
1611           that.
1612
1613           If you want to encode specific string as base64, just do
1614           "SOAP::Data->type(base64 => $string)" either on client or on server
1615           side. If you want change behavior for specific instance of
1616           SOAP::Lite, you may subclass "SOAP::Serializer", override
1617           "as_string()" method that is responsible for string encoding (take
1618           a look into "as_base64Binary()") and specify new serializer class
1619           for your SOAP::Lite object with:
1620
1621             my $soap = new SOAP::Lite
1622               serializer => My::Serializer->new,
1623               ..... other parameters
1624
1625           or on server side:
1626
1627             my $server = new SOAP::Transport::HTTP::Daemon # or any other server
1628               serializer => My::Serializer->new,
1629               ..... other parameters
1630
1631           If you want to change this behavior for all instances of
1632           SOAP::Lite, just substitute "as_string()" method with
1633           "as_base64Binary()" somewhere in your code after "use SOAP::Lite"
1634           and before actual processing/sending:
1635
1636             *SOAP::Serializer::as_string = \&SOAP::XMLSchema2001::Serializer::as_base64Binary;
1637
1638           Be warned that last two methods will affect all strings and convert
1639           them into base64 encoded. It doesn't make any difference for
1640           SOAP::Lite, but it may make a difference for other toolkits.
1641

BUGS AND LIMITATIONS

1643       ·   No support for multidimensional, partially transmitted and sparse
1644           arrays (however arrays of arrays are supported, as well as any
1645           other data structures, and you can add your own implementation with
1646           SOAP::Data).
1647
1648       ·   Limited support for WSDL schema.
1649
1650       ·   XML::Parser::Lite relies on Unicode support in Perl and doesn't do
1651           entity decoding.
1652
1653       ·   Limited support for mustUnderstand and Actor attributes.
1654

PLATFORM SPECIFICS

1656       MacOS
1657           Information about XML::Parser for MacPerl could be found here:
1658
1659           http://bumppo.net/lists/macperl-modules/1999/07/msg00047.html
1660
1661           Compiled XML::Parser for MacOS could be found here:
1662
1663           http://www.perl.com/CPAN-local/authors/id/A/AS/ASANDSTRM/XML-Parser-2.27-bin-1-MacOS.tgz
1664
1666   Transport Modules
1667       SOAP::Lite allows one to add support for additional transport
1668       protocols, or server handlers, via separate modules implementing the
1669       SOAP::Transport::* interface. The following modules are available from
1670       CPAN:
1671
1672       ·   SOAP-Transport-HTTP-Nginx
1673
1674           SOAP::Transport::HTTP::Nginx provides a transport module for nginx
1675           (<http://nginx.net/>)
1676

AVAILABILITY

1678       You can download the latest version SOAP::Lite for Unix or SOAP::Lite
1679       for Win32 from the following sources:
1680
1681        * CPAN:                http://search.cpan.org/search?dist=SOAP-Lite
1682
1683       You are welcome to send e-mail to the maintainers of SOAP::Lite with
1684       your comments, suggestions, bug reports and complaints.
1685

ACKNOWLEDGEMENTS

1687       Special thanks to Randy J. Ray, author of Programming Web Services with
1688       Perl, who has contributed greatly to the documentation effort of
1689       SOAP::Lite.
1690
1691       Special thanks to O'Reilly publishing which has graciously allowed
1692       SOAP::Lite to republish and redistribute the SOAP::Lite reference
1693       manual found in Appendix B of Programming Web Services with Perl.
1694
1695       And special gratitude to all the developers who have contributed
1696       patches, ideas, time, energy, and help in a million different forms to
1697       the development of this software.
1698

HACKING

1700       Latest development takes place on GitHub.com. Come on by and fork it.
1701
1702       git@github.com:redhotpenguin/perl-soaplite.git
1703
1704       Also see the HACKING file.
1705
1706       Actively recruiting maintainers for this module. Come and get it on!
1707

REPORTING BUGS

1709       Please use rt.cpan.org or github to report bugs. Pull requests are
1710       preferred.
1711
1713       Copyright (C) 2000-2007 Paul Kulchenko. All rights reserved.
1714
1715       Copyright (C) 2007-2008 Martin Kutter
1716
1717       Copyright (C) 2013 Fred Moyer
1718

LICENSE

1720       This library is free software; you can redistribute it and/or modify it
1721       under the same terms as Perl itself.
1722
1723       This text and all associated documentation for this library is made
1724       available under the Creative Commons Attribution-NoDerivs 2.0 license.
1725       http://creativecommons.org/licenses/by-nd/2.0/
1726

AUTHORS

1728       Paul Kulchenko (paulclinger@yahoo.com)
1729
1730       Randy J. Ray (rjray@blackperl.com)
1731
1732       Byrne Reese (byrne@majordojo.com)
1733
1734       Martin Kutter (martin.kutter@fen-net.de)
1735
1736       Fred Moyer (fred@redhotpenguin.com)
1737
1738
1739
1740perl v5.32.0                      2020-07-28                     SOAP::Lite(3)
Impressum