1SOAP::Lite(3) User Contributed Perl Documentation SOAP::Lite(3)
2
6 SOAP::Lite - Perl's Web Services Toolkit
7
9 SOAP::Lite is a collection of Perl modules which provides a simple and
10 lightweight interface to the Simple Object Access Protocol (SOAP) both
11 on client and server side.
12
14 lib/SOAP/Lite.pm
15 SOAP::Lite - Main class provides all logic
16 SOAP::Transport - Supports transport architecture
18 SOAP::Data - Provides extensions for serialization architecture
20 SOAP::Header - Provides extensions for header serialization
22 SOAP::Parser - Parses XML file into object tree
24 SOAP::Serializer - Serializes data structures to SOAP package
26 SOAP::Deserializer - Deserializes results of SOAP::Parser into
28 objects
29 SOAP::SOM - Provides access to deserialized object tree
31 SOAP::Constants - Provides access to common constants
33 SOAP::Trace - Provides tracing facilities
35 SOAP::Schema - Provides access and stub(s) for schema(s)
37 SOAP::Schema::WSDL - WSDL implementation for SOAP::Schema
39 SOAP::Server - Handles requests on server side
41 SOAP::Server::Object - Handles objects-by-reference
43 SOAP::Fault - Provides support for Faults on server side
45 SOAP::Utils - A set of private and public utility subroutines
47 lib/SOAP/Packager.pm
49 SOAP::Packager - Provides an abstract class for implementing custom
50 packagers.
51 SOAP::Packager::MIME - Provides MIME support to SOAP::Lite
53 SOAP::Packager::DIME - Provides DIME support to SOAP::Lite
55 lib/SOAP/Transport/HTTP.pm
57 SOAP::Transport::HTTP::Client - Client interface to HTTP transport
58 SOAP::Transport::HTTP::Server - Server interface to HTTP transport
60 SOAP::Transport::HTTP::CGI - CGI implementation of server interface
62 SOAP::Transport::HTTP::Daemon - Daemon implementation of server
64 interface
65 SOAP::Transport::HTTP::Apache - mod_perl implementation of server
67 interface
68 lib/SOAP/Transport/POP3.pm
70 SOAP::Transport::POP3::Server - Server interface to POP3 protocol
71 lib/SOAP/Transport/MAILTO.pm
73 SOAP::Transport::MAILTO::Client - Client interface to SMTP/sendmail
74 lib/SOAP/Transport/LOCAL.pm
76 SOAP::Transport::LOCAL::Client - Client interface to local trans‐
77 port
78 lib/SOAP/Transport/TCP.pm
80 SOAP::Transport::TCP::Server - Server interface to TCP protocol
81 SOAP::Transport::TCP::Client - Client interface to TCP protocol
83 lib/SOAP/Transport/IO.pm
85 SOAP::Transport::IO::Server - Server interface to IO transport
86
88 The first group of methods presented are the constructor and the acces‐
89 sor methods. All accessor methods share the trait of returning the cur‐
90 rent appropriate value when called with no arguments, while returning
91 the object reference itself when called with a new value for the field
92 in question. This allows the set-attribute calls to be chained
93 together.
94 new(optional key/value pairs)
96 $client = SOAP::Lite->new(proxy => $endpoint)
97 This is the constructor of the class. Many of the accessor methods
99 defined here may be initialized at creation by providing their name
100 as a key, followed by the desired value. The example provides the
101 value for the proxy element of the client.
102 transport(optional transport object)
104 $transp = $client->transport( );
105 Provides access to the transport object that the client has allo‐
107 cated to manage the communication layer operations. You can set
108 this by passing a new object that derives from "SOAP::Transport",
109 but this is generally not needed or recommended. Several of the
110 following methods are shortcuts to this object's accessors.
111 serializer(optional serializer object)
113 $serial = $client->serializer( )
114 Provides access to the "SOAP::Serializer" object that the client
116 uses to transform the elements and data of a request into an XML
117 document for the sake of transport. As with transport, this may be
118 set by providing a new object reference, but it is generally not
119 needed.
120 packager(optional packager object)
122 $packager = $client->packager( )
123 Provides access to the "SOAP::Packager" object that the client uses
125 to manage the use of attachments. The default packager is a MIME
126 packager, but unless you specify parts to send, no MIME formatting
127 will be done.
128 See also: SOAP::Packager.
130 proxy(endpoint, optional extra arguments)
132 $client->proxy('http://soap.xml.info/ endPoint');
133 The proxy is the server or endpoint to which the client is going to
135 connect. It shouldn't be confused with the uri method discussed
136 later, which refers to a different element of the conversation.
137 This method allows the setting of the endpoint, along with any
138 extra information that the transport object may need when communi‐
139 cating the request. Indeed, this method is actually an alias to the
140 proxy method of SOAP::Transport. It is the same as typing:
141 $client->transport( )->proxy(...arguments);
143 When extra information is needed, it is also passed in the call to
145 this method. Connecting to a server that uses browser cookies for
146 authentication can be done by creating an instance of the
147 HTTP::Cookies class (from the LWP package) and passing it as the
148 value following a key of cookie_jar. The value for sockettime-outs
149 may also be set this way. The full range of options vary by trans‐
150 port method. One common theme is that the endpoint string is always
151 the first argument, with all additional arguments following it.
152 The following is a list of optional arguments that may be passed to
154 "proxy()":
155 options( HASH )
157 This is for SOAP::Lite specific options. Currently the only
158 option one is allowed to set is the "compress_threshold"
159 option. See COMPRESSION in HTTP::Transport.
160 All initialization options from LWP::UserAgent
162 For example, if you wish to set the HTTP timeout for a SOAP::Lite
164 client to 5 seconds, use the following code:
165 my $soap = SOAP::Lite
167 ->uri($uri)
168 ->proxy($proxyUrl, timeout => 5 );
169 See LWP::UserAgent.
171 endpoint(optional new endpoint address)
173 $client->endpoint('http://soap.xml.info/ newPoint')
174 It may be preferable to set a new endpoint without the additional
176 work of examining the new address for protocol information and
177 checking to ensure the support code is loaded and available. This
178 method allows the caller to change the endpoint that the client is
179 currently set to connect to, without reloading the relevant trans‐
180 port code. Note that the proxy method must have already been called
181 before this method is used.
182 service(service URL)
184 $client->service('http://svc.perl.org/Svc.wsdl');
185 "SOAP::Lite" offers some support for creating method stubs from
187 service descriptions. At present, only WSDL support is in place.
188 This method loads the specified WSDL schema and uses it as the
189 basis for generating stubs.
190 outputxml(boolean)
192 $client->outputxml('true');
193 Controls whether the returned information from a remote method call
195 is the raw XML from the server. The default is to process the data
196 from the server and present it to the caller as an object of the
197 SOAP::SOM class. If the application prefers to use a different
198 parser or do something else entirely with the results, this method
199 may be used to inhibit the parsing of the returned information.
200 autotype(boolean)
202 $client->autotype(0);
203 This method is a shortcut for:
205 $client->serializer->autotype(boolean);
207 By default, the serializer tries to automatically deduce types for
209 the data being sent in a message. Setting a false value with this
210 method disables the behavior.
211 readable(boolean)
213 $client->readable(1);
214 This method is a shortcut for:
216 $client->serializer->readable(boolean);
218 When this is used to set a true value for this property, the gener‐
220 ated XML sent to the endpoint has extra characters (spaces and new
221 lines) added in to make the XML itself more readable to human eyes
222 (presumably for debugging). The default is to not send any addi‐
223 tional characters.
224 default_ns($uri)
226 Sets the default namespace for the request to the specified uri.
227 This overrides any previous namespace declaration that may have
228 been set using a previous call to "ns()" or "default_ns()". Setting
229 the default namespace causes elements to be serialized without a
230 namespace prefix, like so:
231 <soap:Envelope>
233 <soap:Body>
234 <myMethod xmlns="http://www.someuri.com">
235 <foo />
236 </myMethod>
237 </soap:Body>
238 </soap:Envelope>
239 ns($uri,$prefix=undef)
241 Sets the namespace uri and optionally the namespace prefix for the
242 request to the specified values. This overrides any previous names‐
243 pace declaration that may have been set using a previous call to
244 "ns()" or "default_ns()". If a prefix is not specified, one will be
245 generated for you automatically. Setting the namespace causes ele‐
246 ments to be serialized with a declared namespace prefix, like so:
247 <soap:Envelope>
249 <soap:Body>
250 <my:myMethod xmlns:my="http://www.someuri.com">
251 <my:foo />
252 </my:myMethod>
253 </soap:Body>
254 </soap:Envelope>
255 use_prefix(boolean)
257 Deprecated - the "use_prefix()" subroutine has been deprecated in
258 order to provide a more intuitive naming scheme for subroutines
259 that set namespaces. "use_prefix()" was originally added to allow
260 users to turn on or off the use of a default namespace. This func‐
261 tionality is being replaced by "ns()" and "default_ns()".
262 Shortcut for "serializer->use_prefix()". This lets you turn on/off
264 the use of a namespace prefix for the children of the /Enve‐
265 lope/Body element. Default is 'true'. (This was introduced in 0.61
266 for better .NET compatibility)
267 When use_prefix is set to 'true', serialized XML will look like
269 this:
270 <SOAP-ENV:Envelope ...attributes skipped>
272 <SOAP-ENV:Body>
273 <namesp1:mymethod xmlns:namesp1="urn:MyURI" />
274 </SOAP-ENV:Body>
275 </SOAP-ENV:Envelope>
276 When use_prefix is set to 'true', serialized XML will look like
278 this:
279 <SOAP-ENV:Envelope ...attributes skipped>
281 <SOAP-ENV:Body>
282 <mymethod xmlns="urn:MyURI" />
283 </SOAP-ENV:Body>
284 </SOAP-ENV:Envelope>
285 soapversion(optional value)
287 $client->soapversion('1.2');
288 If no parameter is given, returns the current version of SOAP that
290 is being used by the client object to encode requests. If a parame‐
291 ter is given, the method attempts to set that as the version of
292 SOAP being used. The value should be either 1.1 or 1.2.
293 envprefix(QName)
295 $client->envprefix('env');
296 This method is a shortcut for:
298 $client->serializer->envprefix(QName);
300 The namespace label used for the main SOAP namespace elements (such
302 as Envelope, Body, and the attributes) defaults to SOAP-ENV. As has
303 been discussed in earlier chapters, the label itself isn't impor‐
304 tant. But applications that wish to explicitly choose a different
305 one (such as env to denote a SOAP 1.2 message) may do so with this
306 method.
307 encprefix(QName)
309 $client->encprefix('enc');
310 This method is a shortcut for:
312 $client->serializer->encprefix(QName);
314 As with the envprefix method, this gets or sets the label used for
316 the namespace of the encoding rules. The default value is SOAP-ENC,
317 as is generally used in SOAP 1.1 messages, though the label itself
318 has no actual meaning.
319 While it may seem to be an unnecessary operation to set a value that
321 isn't relevant to the message, such as the namespace labels for the
322 envelope and encoding URNs, the ability to set these labels explicitly
323 can prove to be a great aid in distinguishing and debugging messages on
324 the server side of operations.
325 encoding(encoding URN)
327 $client->encoding($soap_12_encoding_URN);
328 This method is a shortcut for:
330 $client->serializer->encoding(args);
332 Where the earlier method dealt with the label used for the
334 attributes related to the SOAP encoding scheme, this method actu‐
335 ally sets the URN to be specified as the encoding scheme for the
336 message. The default is to specify the encoding for SOAP 1.1, so
337 this is handy for applications that need to encode according to
338 SOAP 1.2 rules.
339 typelookup
341 $client->typelookup;
342 This method is a shortcut for:
344 $client->serializer->typelookup;
346 Gives the application access to the type-lookup table from the
348 serializer object. See the section on SOAP::Serializer.
349 uri(service specifier)
351 Deprecated - the "uri" subroutine has been deprecated in order to
352 provide a more intuitive naming scheme for subroutines that set
353 namespaces. In the future, you will be required to use either the
354 "ns()" or "default_ns()" subroutines in lieu of "uri()".
355 $client->uri($service_uri);
357 This method is a shortcut for:
359 $client->serializer->uri(service);
361 The URI associated with this accessor on a client object is the
363 service-specifier for the request, often encoded for HTTP-based
364 requests as the SOAPAction header. While the names may seem confus‐
365 ing, this method doesn't specify the endpoint itself. In most cir‐
366 cumstances, the "uri" refers to the namespace used for the request.
367 Often times, the value may look like a valid URL. Despite this, it
369 doesn't have to point to an existing resource (and often doesn't).
370 This method sets and retrieves this value from the object. Note
371 that no transport code is triggered by this because it has no
372 direct effect on the transport of the object.
373 multirefinplace(boolean)
375 $client->multirefinplace(1);
376 This method is a shortcut for:
378 $client->serializer->multirefinplace(boolean);
380 Controls how the serializer handles values that have multiple ref‐
382 erences to them. Recall from previous SOAP chapters that a value
383 may be tagged with an identifier, then referred to in several
384 places. When this is the case for a value, the serializer defaults
385 to putting the data element towards the top of the message, right
386 after the opening tag of the method-specification. It is serialized
387 as a standalone entity with an ID that is then referenced at the
388 relevant places later on. If this method is used to set a true
389 value, the behavior is different. When the multirefinplace
390 attribute is true, the data is serialized at the first place that
391 references it, rather than as a separate element higher up in the
392 body. This is more compact but may be harder to read or trace in a
393 debugging environment.
394 parts( ARRAY )
396 Used to specify an array of MIME::Entity's to be attached to the
397 transmitted SOAP message. Attachments that are returned in a
398 response can be accessed by "SOAP::SOM::parts()".
399 self
401 $ref = SOAP::Lite->self;
402 Returns an object reference to the default global object the
404 "SOAP::Lite" package maintains. This is the object that processes
405 many of the arguments when provided on the use line.
406 The following method isn't an accessor style of method but neither does
408 it fit with the group that immediately follows it:
409 call(arguments)
411 $client->call($method => @arguments);
412 As has been illustrated in previous chapters, the "SOAP::Lite"
414 client objects can manage remote calls with auto-dispatching using
415 some of Perl's more elaborate features. call is used when the
416 application wants a greater degree of control over the details of
417 the call itself. The method may be built up from a SOAP::Data
418 object, so as to allow full control over the namespace associated
419 with the tag, as well as other attributes like encoding. This is
420 also important for calling methods that contain characters not
421 allowable in Perl function names, such as A.B.C.
422 The next four methods used in the "SOAP::Lite" class are geared towards
424 handling the types of events than can occur during the message lifecy‐
425 cle. Each of these sets up a callback for the event in question:
426 on_action(callback)
428 $client->on_action(sub { qq("$_[0]") });
429 Triggered when the transport object sets up the SOAPAction header
431 for an HTTP-based call. The default is to set the header to the
432 string, uri#method, in which URI is the value set by the uri method
433 described earlier, and method is the name of the method being
434 called. When called, the routine referenced (or the closure, if
435 specified as in the example) is given two arguments, uri and
436 method, in that order.
437 on_fault(callback)
439 $client->on_fault(sub { popup_dialog($_[1]) });
440 Triggered when a method call results in a fault response from the
442 server. When it is called, the argument list is first the client
443 object itself, followed by the object that encapsulates the fault.
444 In the example, the fault object is passed (without the client
445 object) to a hypothetical GUI function that presents an error dia‐
446 log with the text of fault extracted from the object (which is cov‐
447 ered shortly under the SOAP::SOM methods).
448 on_nonserialized(callback)
450 $client->on_nonserialized(sub { die "$_[0]?!?" });
451 Occasionally, the serializer may be given data it can't turn into
453 SOAP-savvy XML; for example, if a program bug results in a code
454 reference or something similar being passed in as a parameter to
455 method call. When that happens, this callback is activated, with
456 one argument. That argument is the data item that could not be
457 understood. It will be the only argument. If the routine returns,
458 the return value is pasted into the message as the serialization.
459 Generally, an error is in order, and this callback allows for con‐
460 trol over signaling that error.
461 on_debug(callback)
463 $client->on_debug(sub { print @_ });
464 This is kept for backwards-compatibility with earlier versions of
466 the toolkit. Each method has a trace step built in, which is called
467 at routine entry. This specifies a callback to be used when these
468 trace statements are reached. Because this is deprecated, it is
469 recommended that applications use the +debug and +trace facilities
470 described later under SOAP::Trace. Note also that debugging isn't
471 handled on a per-object basis; if this method is used on a given
472 object, it sets debugging behavior for all objects of the class.
473
475 TODO - soap client example
476
478 See SOAP::Server, or SOAP::Transport.
479
481 ATTACHMENTS
482 "SOAP::Lite" features support for the SOAP with Attachments specifica‐
484 tion. Currently, SOAP::Lite only supports MIME based attachments. DIME
485 based attachments are yet to be fully functional.
486 EXAMPLES
488 Client sending an attachment
490 "SOAP::Lite" clients can specify attachments to be sent along with a
492 request by using the "SOAP::Lite::parts()" method, which takes as an
493 argument an ARRAY of "MIME::Entity"'s.
494 use SOAP::Lite;
496 use MIME::Entity;
497 my $ent = build MIME::Entity
498 Type => "image/gif",
499 Encoding => "base64",
500 Path => "somefile.gif",
501 Filename => "saveme.gif",
502 Disposition => "attachment";
503 my $som = SOAP::Lite
504 ->uri($SOME_NAMESPACE)
505 ->parts([ $ent ])
506 ->proxy($SOME_HOST)
507 ->some_method(SOAP::Data->name("foo" => "bar"));
508 Client retrieving an attachment
510 A client accessing attachments that were returned in a response by
512 using the "SOAP::SOM::parts()" accessor.
513 use SOAP::Lite;
515 use MIME::Entity;
516 my $soap = SOAP::Lite
517 ->uri($NS)
518 ->proxy($HOST);
519 my $som = $soap->foo();
520 foreach my $part (${$som->parts}) {
521 print $part->stringify;
522 }
523 Server receiving an attachment
525 Servers, like clients, use the SOAP::SOM module to access attachments
527 trasmitted to it.
528 package Attachment;
530 use SOAP::Lite;
531 use MIME::Entity;
532 use strict;
533 use vars qw(@ISA);
534 @ISA = qw(SOAP::Server::Parameters);
535 sub someMethod {
536 my $self = shift;
537 my $envelope = pop;
538 foreach my $part (@{$envelope->parts}) {
539 print "AttachmentService: attachment found! (".ref($part).")\n";
540 }
541 # do something
542 }
543 Server responding with an attachment
545 Servers wishing to return an attachment to the calling client need only
547 return "MIME::Entity" objects along with SOAP::Data elements, or any
548 other data intended for the response.
549 package Attachment;
551 use SOAP::Lite;
552 use MIME::Entity;
553 use strict;
554 use vars qw(@ISA);
555 @ISA = qw(SOAP::Server::Parameters);
556 sub someMethod {
557 my $self = shift;
558 my $envelope = pop;
559 my $ent = build MIME::Entity
560 'Id' => "<1234>",
561 'Type' => "text/xml",
562 'Path' => "some.xml",
563 'Filename' => "some.xml",
564 'Disposition' => "attachment";
565 return SOAP::Data->name("foo" => "blah blah blah"),$ent;
566 }
567 DEFAULT SETTINGS
569 Though this feature looks similar to autodispatch they have (almost)
571 nothing in common. This capability allows you specify default settings
572 so that all objects created after that will be initialized with the
573 proper default settings.
574 If you wish to provide common "proxy()" or "uri()" settings for all
576 "SOAP::Lite" objects in your application you may do:
577 use SOAP::Lite
579 proxy => 'http://localhost/cgi-bin/soap.cgi',
580 uri => 'http://my.own.com/My/Examples';
581 my $soap1 = new SOAP::Lite; # will get the same proxy()/uri() as above
583 print $soap1->getStateName(1)->result;
584 my $soap2 = SOAP::Lite->new; # same thing as above
586 print $soap2->getStateName(2)->result;
587 # or you may override any settings you want
589 my $soap3 = SOAP::Lite->proxy('http://localhost/');
590 print $soap3->getStateName(1)->result;
591 Any "SOAP::Lite" properties can be propagated this way. Changes in
593 object copies will not affect global settings and you may still change
594 global settings with "SOAP::Lite->self" call which returns reference to
595 global object. Provided parameter will update this object and you can
596 even set it to "undef":
597 SOAP::Lite->self(undef);
599 The "use SOAP::Lite" syntax also lets you specify default event han‐
601 dlers for your code. If you have different SOAP objects and want to
602 share the same "on_action()" (or "on_fault()" for that matter) handler.
603 You can specify "on_action()" during initialization for every object,
604 but you may also do:
605 use SOAP::Lite
607 on_action => sub {sprintf '%s#%s', @_};
608 and this handler will be the default handler for all your SOAP objects.
610 You can override it if you specify a handler for a particular object.
611 See t/*.t for example of on_fault() handler.
612 Be warned, that since "use ..." is executed at compile time all "use"
614 statements will be executed before script execution that can make unex‐
615 pected results. Consider code:
616 use SOAP::Lite proxy => 'http://localhost/';
618 print SOAP::Lite->getStateName(1)->result;
619 use SOAP::Lite proxy => 'http://localhost/cgi-bin/soap.cgi';
621 print SOAP::Lite->getStateName(1)->result;
622 Both SOAP calls will go to 'http://localhost/cgi-bin/soap.cgi'. If you
624 want to execute "use" at run-time, put it in "eval":
625 eval "use SOAP::Lite proxy => 'http://localhost/cgi-bin/soap.cgi'; 1" or die;
627 Or alternatively,
629 SOAP::Lite->self->proxy('http://localhost/cgi-bin/soap.cgi');
631 SETTING MAXIMUM MESSAGE SIZE
633 One feature of "SOAP::Lite" is the ability to control the maximum size
635 of a message a SOAP::Lite server will be allowed to process. To control
636 this feature simply define $SOAP::Constants::MAX_CONTENT_SIZE in your
637 code like so:
638 use SOAP::Transport::HTTP;
640 use MIME::Entity;
641 $SOAP::Constants::MAX_CONTENT_SIZE = 10000;
642 SOAP::Transport::HTTP::CGI
643 ->dispatch_to('TemperatureService')
644 ->handle;
645 IN/OUT, OUT PARAMETERS AND AUTOBINDING
647 "SOAP::Lite" gives you access to all parameters (both in/out and out)
649 and also does some additional work for you. Lets consider following
650 example:
651 <mehodResponse>
653 <res1>name1</res1>
654 <res2>name2</res2>
655 <res3>name3</res3>
656 </mehodResponse>
657 In that case:
659 $result = $r->result; # gives you 'name1'
661 $paramout1 = $r->paramsout; # gives you 'name2', because of scalar context
662 $paramout1 = ($r->paramsout)[0]; # gives you 'name2' also
663 $paramout2 = ($r->paramsout)[1]; # gives you 'name3'
664 or
666 @paramsout = $r->paramsout; # gives you ARRAY of out parameters
668 $paramout1 = $paramsout[0]; # gives you 'res2', same as ($r->paramsout)[0]
669 $paramout2 = $paramsout[1]; # gives you 'res3', same as ($r->paramsout)[1]
670 Generally, if server returns "return (1,2,3)" you will get 1 as the
672 result and 2 and 3 as out parameters.
673 If the server returns "return [1,2,3]" you will get an ARRAY from
675 "result()" and "undef" from "paramsout()".
676 Results can be arbitrary complex: they can be an array, they can be
678 objects, they can be anything and still be returned by "result()" . If
679 only one parameter is returned, "paramsout()" will return "undef".
680 Furthermore, if you have in your output parameters a parameter with the
682 same signature (name+type) as in the input parameters this parameter
683 will be mapped into your input automatically. For example:
684 Server Code:
686 sub mymethod {
688 shift; # object/class reference
689 my $param1 = shift;
690 my $param2 = SOAP::Data->name('myparam' => shift() * 2);
691 return $param1, $param2;
692 }
693 Client Code:
695 $a = 10;
697 $b = SOAP::Data->name('myparam' => 12);
698 $result = $soap->mymethod($a, $b);
699 After that, "$result == 10 and $b->value == 24"! Magic? Sort of. Auto‐
701 binding gives it to you. That will work with objects also with one dif‐
702 ference: you do not need to worry about the name and the type of object
703 parameter. Consider the "PingPong" example (examples/My/PingPong.pm and
704 examples/pingpong.pl):
705 Server Code:
707 package My::PingPong;
709 sub new {
711 my $self = shift;
712 my $class = ref($self) ⎪⎪ $self;
713 bless {_num=>shift} => $class;
714 }
715 sub next {
717 my $self = shift;
718 $self->{_num}++;
719 }
720 Client Code:
722 use SOAP::Lite +autodispatch =>
724 uri => 'urn:',
725 proxy => 'http://localhost/';
726 my $p = My::PingPong->new(10); # $p->{_num} is 10 now, real object returned
728 print $p->next, "\n"; # $p->{_num} is 11 now!, object autobinded
729 STATIC AND DYNAMIC SERVICE DEPLOYMENT
731 Let us scrutinize the deployment process. When designing your SOAP
733 server you can consider two kind of deployment: static and dynamic. For
734 both, static and dynamic, you should specify "MODULE", "MOD‐
735 ULE::method", "method" or "PATH/" when creating "use"ing the SOAP::Lite
736 module. The difference between static and dynamic deployment is that in
737 case of 'dynamic', any module which is not present will be loaded on
738 demand. See the "SECURITY" section for detailed description.
739 STATIC DEPLOYMENT EXAMPLE
741 use SOAP::Transport::HTTP;
743 use My::Examples; # module is preloaded
744 SOAP::Transport::HTTP::CGI
746 # deployed module should be present here or client will get 'access denied'
747 -> dispatch_to('My::Examples')
748 -> handle;
749 For static deployment you should specify the MODULE name directly.
751 You should also use static binding when you have several different
753 classes in one file and want to make them available for SOAP calls.
754 DYNAMIC DEPLOYMENT EXAMPLE
756 use SOAP::Transport::HTTP;
758 # name is unknown, module will be loaded on demand
759 SOAP::Transport::HTTP::CGI
761 # deployed module should be present here or client will get 'access denied'
762 -> dispatch_to('/Your/Path/To/Deployed/Modules', 'My::Examples')
763 -> handle;
764 For dynamic deployment you can specify the name either directly (in
766 that case it will be "require"d without any restriction) or indirectly,
767 with a PATH. In that case, the ONLY path that will be available will be
768 the PATH given to the dispatch_to() method). For information how to
769 handle this situation see "SECURITY" section.
770 SUMMARY
772 dispatch_to(
774 # dynamic dispatch that allows access to ALL modules in specified directory
775 PATH/TO/MODULES
776 # 1. specifies directory
777 # -- AND --
778 # 2. gives access to ALL modules in this directory without limits
779 # static dispatch that allows access to ALL methods in particular MODULE
781 MODULE
782 # 1. gives access to particular module (all available methods)
783 # PREREQUISITES:
784 # module should be loaded manually (for example with 'use ...')
785 # -- OR --
786 # you can still specify it in PATH/TO/MODULES
787 # static dispatch that allows access to particular method ONLY
789 MODULE::method
790 # same as MODULE, but gives access to ONLY particular method,
791 # so there is not much sense to use both MODULE and MODULE::method
792 # for the same MODULE
793 )
794 In addition to this "SOAP::Lite" also supports an experimental syntax
796 that allows you to bind a specific URL or SOAPAction to a CLASS/MODULE
797 or object. For example:
798 dispatch_with({
800 URI => MODULE, # 'http://www.soaplite.com/' => 'My::Class',
801 SOAPAction => MODULE, # 'http://www.soaplite.com/method' => 'Another::Class',
802 URI => object, # 'http://www.soaplite.com/obj' => My::Class->new,
803 })
804 "URI" is checked before "SOAPAction". You may use both the "dis‐
806 patch_to()" and "dispatch_with()" methods in the same server, but note
807 that "dispatch_with()" has a higher order of precedence. "dis‐
808 patch_to()" will be checked only after "URI" and "SOAPAction" has been
809 checked. See t/03-server.t for more information and examples.
810 See also: EXAMPLE APACHE::REGISTRY USAGE, "SECURITY"
812 COMPRESSION
814 "SOAP::Lite" provides you option to enable transparent compression over
816 the wire. Compression can be enabled by specifying a threshold value
817 (in the form of kilobytes) for compression on both the client and
818 server sides:
819 Note: Compression currently only works for HTTP based servers and
821 clients.
822 Client Code
824 print SOAP::Lite
826 ->uri('http://localhost/My/Parameters')
827 ->proxy('http://localhost/', options => {compress_threshold => 10000})
828 ->echo(1 x 10000)
829 ->result;
830 Server Code
832 my $server = SOAP::Transport::HTTP::CGI
834 ->dispatch_to('My::Parameters')
835 ->options({compress_threshold => 10000})
836 ->handle;
837 For more information see COMPRESSION in HTTP::Transport.
839
841 For security reasons, the exisiting path for Perl modules (@INC) will
842 be disabled once you have chosen dynamic deployment and specified your
843 own "PATH/". If you wish to access other modules in your included pack‐
844 age you have several options:
845 1 Switch to static linking:
847 use MODULE;
849 $server->dispatch_to('MODULE');
850 Which can also be useful when you want to import something specific
852 from the deployed modules:
853 use MODULE qw(import_list);
855 2 Change "use" to "require". The path is only unavailable during the
857 initialization phase. It is available once more during execution.
858 Therefore, if you utilize "require" somewhere in your package, it
859 will work.
860 3 Wrap "use" in an "eval" block:
862 eval 'use MODULE qw(import_list)'; die if $@;
864 4 Set your include path in your package and then specify "use". Don't
866 forget to put @INC in a "BEGIN{}" block or it won't work. For exam‐
867 ple,
868 BEGIN { @INC = qw(my_directory); use MODULE }
870
872 Microsoft .NET client with SOAP::Lite Server
873 In order to use a .NET client with a SOAP::Lite server, be sure you use
875 fully qualified names for your return values. For example:
876 return SOAP::Data->name('myname')
878 ->type('string')
879 ->uri($MY_NAMESPACE)
880 ->value($output);
881 In addition see comment about default incoding in .NET Web Services
883 below.
884 SOAP::Lite client with a .NET server
886 If experiencing problems when using a SOAP::Lite client to call a .NET
888 Web service, it is recommended you check, or adhere to all of the fol‐
889 lowing recommendations:
890 Declare a proper soapAction in your call
892 For example, use "on_action( sub { 'http://www.myuri.com/WebSer‐
893 vice.aspx#someMethod'; } )".
894 Disable charset definition in Content-type header
896 Some users have said that Microsoft .NET prefers the value of the
897 Content-type header to be a mimetype exclusively, but SOAP::Lite
898 specifies a character set in addition to the mimetype. This results
899 in an error similar to:
900 Server found request content type to be 'text/xml; charset=utf-8',
902 but expected 'text/xml'
903 To turn off this behavior specify use the following code:
905 use SOAP::Lite;
907 $SOAP::Constants::DO_NOT_USE_CHARSET = 1;
908 # The rest of your code
909 Use fully qualified name for method parameters
911 For example, the following code is preferred:
912 SOAP::Data->name(Query => 'biztalk')
914 ->uri('http://tempuri.org/')
915 As opposed to:
917 SOAP::Data->name('Query' => 'biztalk')
919 Place method in default namespace
921 For example, the following code is preferred:
922 my $method = SOAP::Data->name('add')
924 ->attr({xmlns => 'http://tempuri.org/'});
925 my @rc = $soap->call($method => @parms)->result;
926 As opposed to:
928 my @rc = $soap->call(add => @parms)->result;
930 # -- OR --
931 my @rc = $soap->add(@parms)->result;
932 Disable use of explicit namespace prefixes
934 Some user's have reported that .NET will simply not parse messages
935 that use namespace prefixes on anything but SOAP elements them‐
936 selves. For example, the following XML would not be parsed:
937 <SOAP-ENV:Envelope ...attributes skipped>
939 <SOAP-ENV:Body>
940 <namesp1:mymethod xmlns:namesp1="urn:MyURI" />
941 </SOAP-ENV:Body>
942 </SOAP-ENV:Envelope>
943 SOAP::Lite allows users to disable the use of explicit namespaces
945 through the "use_prefix()" method. For example, the following code:
946 $som = SOAP::Lite->uri('urn:MyURI')
948 ->proxy($HOST)
949 ->use_prefix(0)
950 ->myMethod();
951 Will result in the following XML, which is more pallatable by .NET:
953 <SOAP-ENV:Envelope ...attributes skipped>
955 <SOAP-ENV:Body>
956 <mymethod xmlns="urn:MyURI" />
957 </SOAP-ENV:Body>
958 </SOAP-ENV:Envelope>
959 Modify your .NET server, if possible
961 Stefan Pharies <stefanph@microsoft.com>:
962 SOAP::Lite uses the SOAP encoding (section 5 of the soap 1.1 spec),
964 and the default for .NET Web Services is to use a literal encoding.
965 So elements in the request are unqualified, but your service
966 expects them to be qualified. .Net Web Services has a way for you
967 to change the expected message format, which should allow you to
968 get your interop working. At the top of your class in the asmx,
969 add this attribute (for Beta 1):
970 [SoapService(Style=SoapServiceStyle.RPC)]
972 Another source said it might be this attribute (for Beta 2):
974 [SoapRpcService]
976 Full Web Service text may look like:
978 <%@ WebService Language="C#" Class="Test" %>
980 using System;
981 using System.Web.Services;
982 using System.Xml.Serialization;
983 [SoapService(Style=SoapServiceStyle.RPC)]
985 public class Test : WebService {
986 [WebMethod]
987 public int add(int a, int b) {
988 return a + b;
989 }
990 }
991 Another example from Kirill Gavrylyuk <kirillg@microsoft.com>:
993 "You can insert [SoapRpcService()] attribute either on your class
995 or on operation level".
996 <%@ WebService Language=CS class="DataType.StringTest"%>
998 namespace DataType {
1000 using System;
1002 using System.Web.Services;
1003 using System.Web.Services.Protocols;
1004 using System.Web.Services.Description;
1005 [SoapRpcService()]
1007 public class StringTest: WebService {
1008 [WebMethod]
1009 [SoapRpcMethod()]
1010 public string RetString(string x) {
1011 return(x);
1012 }
1013 }
1014 }
1015 Example from Yann Christensen <yannc@microsoft.com>:
1017 using System;
1019 using System.Web.Services;
1020 using System.Web.Services.Protocols;
1021 namespace Currency {
1023 [WebService(Namespace="http://www.yourdomain.com/example")]
1024 [SoapRpcService]
1025 public class Exchange {
1026 [WebMethod]
1027 public double getRate(String country, String country2) {
1028 return 122.69;
1029 }
1030 }
1031 }
1032 Special thanks goes to the following people for providing the above
1034 description and details on .NET interoperability issues:
1035 Petr Janata <petr.janata@i.cz>,
1037 Stefan Pharies <stefanph@microsoft.com>,
1039 Brian Jepson <bjepson@jepstone.net>, and others
1041
1043 SOAP::Lite serializes "18373" as an integer, but I want it to be a
1044 string!
1045 Because Perl is loosely typed, there is no 100% reliable way to
1046 predict what the *intended* type of a variable is. So SOAP::Lite
1047 has a system of guessing what a type is. But it is not 100% reli‐
1048 able. You do however, have the control to override this autotyping
1049 behavior with your own.
1050 Suppose you wanted to case every element of an array as a string.
1052 Then the following code will change the precedence of SOAP::Seri‐
1053 ailizer's is-a-string test to be the first test run. Because the
1054 is-a-string test always returns "true" every element will be deter‐
1055 mined to be a string.
1056 my @list = qw(-1 45 foo bar 3838);
1058 my $proxy = SOAP::Lite->uri($uri)->proxy($proxyUrl);
1059 $proxy->serializer->typelookup->{string}->[0] = 0;
1060 $proxy->myMethod(\@list);
1061 Alternatively, you can build the XML data structure manually...
1063 See SOAP::Serializer.
1065 "+autodispatch" doesn't work in Perl 5.8
1067 There is a bug in Perl 5.8's "UNIVERSAL::AUTOLOAD" functionality
1068 that prevents the "+autodispatch" functionality from working prop‐
1069 erly. The workaround is to use "dispatch_from" instead. Where you
1070 might normally do something like this:
1071 use Some::Module;
1073 use SOAP::Lite +autodispatch =>
1074 uri => 'urn:Foo'
1075 proxy => 'http://...';
1076 You would do something like this:
1078 use SOAP::Lite dispatch_from(Some::Module) =>
1080 uri => 'urn:Foo'
1081 proxy => 'http://...';
1082 Problems using SOAP::Lite's COM Interface
1084 Can't call method "server" on undefined value
1085 You probably did not register Lite.dll using "regsvr32
1086 Lite.dll"
1087 Failed to load PerlCtrl Runtime
1089 It is likely that you have install Perl in two different loca‐
1090 tions and the location of ActiveState's Perl is not the first
1091 instance of Perl specified in your PATH. To rectify, rename the
1092 directory in which the non-ActiveState Perl is installed, or be
1093 sure the path to ActiveState's Perl is specified prior to any
1094 other instance of Perl in your PATH.
1095 Dynamic libraries are not found
1097 If you are using the Apache web server, and you are seeing some‐
1098 thing like the following in your webserver log file:
1099 Can't load '/usr/local/lib/perl5/site_perl/.../XML/Parser/Expat/Expat.so'
1101 for module XML::Parser::Expat: dynamic linker: /usr/local/bin/perl:
1102 libexpat.so.0 is NEEDED, but object does not exist at
1103 /usr/local/lib/perl5/.../DynaLoader.pm line 200.
1104 Then try placing the following into your httpd.conf file and see if
1106 it fixes your problem.
1107 <IfModule mod_env.c>
1109 PassEnv LD_LIBRARY_PATH
1110 </IfModule>
1111 SOAP client reports "500 unexpected EOF before status line seen
1113 See "Apache is crashing with segfaults"
1114 Apache is crashing with segfaults
1116 Using "SOAP::Lite" (or XML::Parser::Expat) in combination with
1117 mod_perl causes random segmentation faults in httpd processes. To
1118 fix, try configuring Apache with the following:
1119 RULE_EXPAT=no
1121 If you are using Apache 1.3.20 and later, try configuring Apache
1123 with the following option:
1124 ./configure --disable-rule=EXPAT
1126 See http://archive.covalent.net/modperl/2000/04/0185.xml for more
1128 details and lot of thanks to Robert Barta <rho@bigpond.net.au> for
1129 explaining this weird behavior.
1130 If this doesn't address the problem, you may wish to try "-Uusemy‐
1132 malloc", or a similar option in order to instruct Perl to use the
1133 system's own "malloc".
1134 Thanks to Tim Bunce <Tim.Bunce@pobox.com>.
1136 CGI scripts do not work under Microsoft Internet Information Server
1138 (IIS)
1139 CGI scripts may not work under IIS unless scripts use the ".pl"
1140 extension, opposed to ".cgi".
1141 Java SAX parser unable to parse message composed by SOAP::Lite
1143 In some cases SOAP messages created by "SOAP::Lite" may not be
1144 parsed properly by a SAX2/Java XML parser. This is due to a known
1145 bug in "org.xml.sax.helpers.ParserAdapter". This bug manifests
1146 itself when an attribute in an XML element occurs prior to the XML
1147 namespace declaration on which it depends. However, according to
1148 the XML specification, the order of these attributes is not signif‐
1149 icant.
1150 http://www.megginson.com/SAX/index.html
1152 Thanks to Steve Alpert (Steve_Alpert@idx.com) for pointing on it.
1154
1156 Processing of XML encoded fragments
1157 "SOAP::Lite" is based on XML::Parser which is basically wrapper
1158 around James Clark's expat parser. Expat's behavior for parsing XML
1159 encoded string can affect processing messages that have lot of
1160 encoded entities, like XML fragments, encoded as strings. Providing
1161 low-level details, parser will call char() callback for every por‐
1162 tion of processed stream, but individually for every processed
1163 entity or newline. It can lead to lot of calls and additional mem‐
1164 ory manager expenses even for small messages. By contrast, XML mes‐
1165 sages which are encoded as base64Binary, don't have this problem
1166 and difference in processing time can be significant. For XML
1167 encoded string that has about 20 lines and 30 tags, number of call
1168 could be about 100 instead of one for the same string encoded as
1169 base64Binary.
1170 Since it is parser's feature there is NO fix for this behavior (let
1172 me know if you find one), especially because you need to parse mes‐
1173 sage you already got (and you cannot control content of this mes‐
1174 sage), however, if your are in charge for both ends of processing
1175 you can switch encoding to base64 on sender's side. It will defi‐
1176 nitely work with SOAP::Lite and it may work with other tool‐
1177 kits/implementations also, but obviously I cannot guarantee that.
1178 If you want to encode specific string as base64, just do
1180 "SOAP::Data->type(base64 => $string)" either on client or on server
1181 side. If you want change behavior for specific instance of
1182 SOAP::Lite, you may subclass "SOAP::Serializer", override
1183 "as_string()" method that is responsible for string encoding (take
1184 a look into "as_base64Binary()") and specify new serializer class
1185 for your SOAP::Lite object with:
1186 my $soap = new SOAP::Lite
1188 serializer => My::Serializer->new,
1189 ..... other parameters
1190 or on server side:
1192 my $server = new SOAP::Transport::HTTP::Daemon # or any other server
1194 serializer => My::Serializer->new,
1195 ..... other parameters
1196 If you want to change this behavior for all instances of
1198 SOAP::Lite, just substitute "as_string()" method with
1199 "as_base64Binary()" somewhere in your code after "use SOAP::Lite"
1200 and before actual processing/sending:
1201 *SOAP::Serializer::as_string = \&SOAP::Serializer::as_base64Binary;
1203 Be warned that last two methods will affect all strings and convert
1205 them into base64 encoded. It doesn't make any difference for
1206 SOAP::Lite, but it may make a difference for other toolkits.
1207
1209 · No support for multidimensional, partially transmitted and sparse
1210 arrays (however arrays of arrays are supported, as well as any
1211 other data structures, and you can add your own implementation with
1212 SOAP::Data).
1213 · Limited support for WSDL schema.
1215 · XML::Parser::Lite relies on Unicode support in Perl and doesn't do
1217 entity decoding.
1218 · Limited support for mustUnderstand and Actor attributes.
1220
1222 MacOS
1223 Information about XML::Parser for MacPerl could be found here:
1224 http://bumppo.net/lists/macperl-modules/1999/07/msg00047.html
1226 Compiled XML::Parser for MacOS could be found here:
1228 http://www.perl.com/CPAN-local/authors/id/A/AS/ASAND‐
1230 STRM/XML-Parser-2.27-bin-1-MacOS.tgz
1231
1233 You can download the latest version SOAP::Lite for Unix or SOAP::Lite
1234 for Win32 from the following sources:
1235 * SOAP::Lite Homepage: http://soaplite.com/
1237 * CPAN: http://search.cpan.org/search?dist=SOAP-Lite
1238 * Sourceforge: http://sourceforge.net/projects/soaplite/
1239 You are welcome to send e-mail to the maintainers of SOAP::Lite with
1241 your with your comments, suggestions, bug reports and complaints.
1242
1244 Special thanks to Randy J. Ray, author of Programming Web Services with
1245 Perl, who has contributed greatly to the documentation effort of
1246 SOAP::Lite.
1247 Special thanks to O'Reilly publishing which has graciously allowed
1249 SOAP::Lite to republish and redistribute the SOAP::Lite reference man‐
1250 ual found in Appendix B of Programming Web Services with Perl.
1251 And special gratitude to all the developers who have contributed
1253 patches, ideas, time, energy, and help in a million different forms to
1254 the development of this software.
1255
1257 Please report all suspected SOAP::Lite bugs using Sourceforge. This
1258 ensures proper tracking of the issue and allows you the reporter to
1259 know when something gets fixed.
1260 http://sourceforge.net/tracker/?group_id=66000&atid=513017
1262 If under dire circumstances you need immediate assistance with the res‐
1264 olution of an issue, you are welcome to contact Byrne Reese at <byrne
1265 at majordojo dot com>.
1266
1268 Copyright (C) 2000-2005 Paul Kulchenko. All rights reserved.
1269 This library is free software; you can redistribute it and/or modify it
1271 under the same terms as Perl itself.
1272 This text and all associated documentation for this library is made
1274 available under the Creative Commons Attribution-NoDerivs 2.0 license.
1275 http://creativecommons.org/licenses/by-nd/2.0/
1276
1278 Paul Kulchenko (paulclinger@yahoo.com)
1279 Randy J. Ray (rjray@blackperl.com)
1281 Byrne Reese (byrne@majordojo.com)
1283perl v5.8.8 2006-06-15 SOAP::Lite(3)