1SOAP::Transport(3) User Contributed Perl Documentation SOAP::Transport(3)
2
6 SOAP::Transport - an abstract class extended by more specialized trans‐
7 port modules
8
10 Objects of the SOAP::Transport class manage two roles: they manage both
11 the parameters related to transport as set through the containing
12 SOAP::Lite object, and they abstract the selection and loading of an
13 appropriate transport module. This is done with an AUTOLOAD function
14 within the class that intercepts all methods beyond the two defined
15 next and reroutes them to the underlying transport implementation code.
16
18 new
19 $trans = SOAP::Transport->new;
20 This is the constructor, which isn't usually called by an applica‐
22 tion directly. An application can use this to create a fresh new
23 SOAP::Transport object, which may be installed using the
24 SOAP::Lite->transport method defined earlier. No arguments are rec‐
25 ognized.
26 proxy(optional URL string)
28 $trans->proxy('http://www.blackperl.com/SOAP');
29 Gets or sets the proxy (endpoint). This method must be called
31 before any other methods are called. The proper transport code is
32 loaded based on the scheme specified by the URL itself (http, jab‐
33 ber, etc.). Until this method is called the first time with a URL
34 string, the underlying code has yet to be loaded, and the methods
35 aren't available. When getting the current proxy (calling with no
36 parameters), the returned value is a reference to the client object
37 created from the protocol class that matched the endpoint, not the
38 endpoint itself.
39
41 Because the bulk of the work is done within the "SOAP::Lite" module
42 itself, many of the transport-level modules are very simple in their
43 implementations. Transport modules are expected to define both client
44 and server classes within their files. If a module defines only one of
45 the types, it is assumed that the transport protocol itself supports
46 only that side of the conversation. An example is SOAP::Transport::FTP,
47 which provides only a "SOAP::Transport::FTP::Client" class.
48 "SOAP::Transport::FTP" - Client class only
50 "SOAP::Transport::HTTP" - Client, and server classes for CGI, FCGI,
52 Daemon and mod_perl
53 "SOAP::Transport::IO" - Server class only
55 "SOAP::Transport::JABBER" - Server and Client classes
57 "SOAP::Transport::LOCAL" - Client class only
59 "SOAP::Transport::MAILTO" - Client class only
61 "SOAP::Transport::MQ" - Server and Client classes
63 "SOAP::Transport::POP3" - Server class only
65 "SOAP::Transport::TCP" - Server and Client classes
67 METHODS
69 Each SOAP::Transport sub-class is expected to define (or inherit, if it
71 is subclassing another transport class) at least two methods. Any newly
72 developed transport classes are also expected to adhere to this inter‐
73 face. Clients are expected to implement the "new" and "send_receive"
74 methods, and servers are expected to implement the "new" and "handle"
75 methods. Here they are:
76 new(optional key/value pairs)
78 $object = $class->new(%params);
79 Creates a new object instance and returns it. Like the constructors
81 for both "SOAP::Lite" and SOAP::Server classes, all arguments
82 passed in are treated as key/value pairs, where the key is expected
83 to be one of the methods the class supports, and the value is the
84 argument (or list reference of arguments) to the method.
85 send_receive(key/value pairs)
87 $client->send_recieve(%hash_table);
88 (Required for client classes only) When the SOAP::Lite objects
90 attempt to send out requests, the means for doing so is to attempt
91 to call this method on the object held within the SOAP::Transport
92 object contained within the client itself. All clients are expected
93 to provide this, and the call to this method always passes four
94 values for the hash keys:
95 action
97 The URI specifying the action being performed, usually the
98 result from the on_action hook on the client object.
99 encoding
101 The URI of the encoding scheme that governs the message being
102 sent.
103 endpoint
105 The URI specifying the endpoint to which the message is being
106 sent.
107 envelope
109 The XML content of the message to be sent. It is generally the
110 return value of the envelope method from the SOAP::Serializer
111 object instance that the client object maintains.
112 parts
114 Attachments to add to the request. Currently this only supports
115 an array of MIME::Entity objects, but in theory could support
116 attachments of any format.
117 handle
119 $server->handle;
120 (Required for server classes only.) This method is the central
122 point for the various server classes to provide an interface to
123 handling requests. The exact set and nature of parameters generally
124 varies based on the classes themselves.
125 SOAP::Transport::FTP
127 The SOAP::Transport::FTP module is automatically loaded by the
129 SOAP::Transport portion of the client structure. It is brought in when
130 an endpoint is specified via the proxy method that starts with the
131 characters, ftp://. This module provides only a client class.
132 SOAP::Transport::FTP::Client
134 Inherits from: SOAP::Client.
136 Support is provided for clients to connect to FTP servers using SOAP.
138 The methods defined within the class are just the basic new and
139 send_receive.
140 SOAP::Transport::HTTP
142 The most commonly used transport module is the HTTP implementation.
144 This is loaded whenever an endpoint is given that starts with the char‐
145 acters, http:// or https://. This is also the most involved of the
146 transport modules, defining not only a client class but several differ‐
147 ent server classes as well.
148 HTTP PROXY SETTINGS
150 Because "SOAP::Client" inherits from "LWP::UserAgent", you can use any
152 of "LWP::UserAgent"'s proxy settings. For example:
153 SOAP::Lite->proxy("http://endpoint.server/",
155 proxy => ["http" => "http://my.proxy.server"]);
156 or
158 $soap->transport->proxy("http" => "http://my.proxy.server");
160 The above code samples should specify a proxy server for you. And
162 should you use "HTTP_proxy_user" and "HTTP_proxy_pass" for proxy autho‐
163 rization, "SOAP::Lite" will handle it properly.
164 HTTP BASIC AUTHENTICATION
166 HTTP Basic authentication is accomplished by overriding the
168 get_basic_credentials suboutine in "LWP::UserAgent" (which
169 "SOAP::Transport::HTTP::Client" is a subclass):
170 BEGIN {
172 sub SOAP::Transport::HTTP::Client::get_basic_credentials {
173 return 'username' => 'password';
174 }
175 }
176 COOKIE-BASED AUTHENTICATION
178 use HTTP::Cookies;
180 my $cookies = HTTP::Cookies->new(ignore_discard => 1);
181 # you may also add 'file' if you want to keep them between sessions
182 my $soap = SOAP::Lite->proxy('http://localhost/');
183 $soap->transport->cookie_jar($cookies);
184 Or, alternatively, you can do the above on a single line:
186 $soap->proxy('http://localhost/',
188 cookie_jar => HTTP::Cookies->new(ignore_discard => 1));
189 Cookies will be taken from the response and provided to the request.
191 You may access and manipulate cookies received, as well as add cookies
192 of your own by using the "HTTP::Cookies" interfaces.
193 SSL CERTIFICATE AUTHENTICATION
195 To get certificate authentication working you need to set three envi‐
197 ronment variables: "HTTPS_CERT_FILE", "HTTPS_KEY_FILE", and optionally
198 "HTTPS_CERT_PASS". This can be done either through the command line, or
199 directly within your Perl script using the $ENV variable:
200 $ENV{HTTPS_CERT_FILE} = 'client-cert.pem';
202 $ENV{HTTPS_KEY_FILE} = 'client-key.pem';
203 These settings are referrenced by "Crypt::SSLeay", the module
205 SOAP::Lite used for HTTPS support. Other options (e.g. CA peer verifi‐
206 cation) can be specified in a similar way. See Crypt::SSLeay documenta‐
207 tion for more information.
208 Those who would like to use encrypted keys may find the following
210 thread in the SOAP::Lite newsgroup helpful:
211 http://groups.yahoo.com/group/soaplite/message/729
213 COMPRESSION
215 SOAP::Lite provides you with the option for enabling compression over
217 the wire using HTTP only in both the server and client contexts, pro‐
218 vided that you have Compress::Zlib installed. Compression and decom‐
219 pression is done transparantly to your application.
220 A server will respond with an encoded/compressed message only if the
222 client has asserted that it can accept it (indicated by client sending
223 an "Accept-Encoding" HTTP header with a 'deflate' or '*' value).
224 "SOAP::Lite" clients all have fallback logic implemented so that if a
226 server doesn't understand the specified encoding (i.e. "Content-Encod‐
227 ing: deflate") and returns the proper HTTP status code (415 NOT ACCEPT‐
228 ABLE), the client will repeat the request without using encoding/com‐
229 pression. The client will then store this server in a per-session
230 cache, so that all subsequent requests to that server will be transmit‐
231 ted without encoding.
232 Compression is enabled on the client side by specifying the "com‐
234 press_threshold" option, and if the size of the current request exceeds
235 that threshold.
236 Client Code Sample
238 print SOAP::Lite
240 ->uri('http://localhost/My/Parameters')
241 ->proxy('http://localhost/', options => {compress_threshold => 10000})
242 ->echo(1 x 10000)
243 ->result;
244 Servers will respond with a compressed message if the "compress_thresh‐
246 old" option has been specified, if the size of the current response
247 exceeds that threshold, and if the calling client transmitted the
248 proper "Accept-Encoding" HTTP Header.
249 Server Code Sample
251 my $server = SOAP::Transport::HTTP::CGI
253 ->dispatch_to('My::Parameters')
254 ->options({compress_threshold => 10000})
255 ->handle;
256 See also: Compress::Zlib
258 SOAP::Transport::HTTP::Client
260 Inherits from: SOAP::Client, LWP::UserAgent (from the LWP package).
262 With this class, clients are able to use HTTP for sending messages.
264 This class provides just the basic new and send_receive methods.
265 Objects of this class understand the compress_threshold option and use
266 it if the server being communicated to also understands it.
267 CHANGING THE DEFAULT USERAGENT CLASS
269 By default, "SOAP::Transport::HTTP::Client" extends "LWP::UserAgent".
271 But under some circumstances, a user may wish to change the default
272 UserAgent class with their in order to better handle persist connec‐
273 tions, or to "LWP::UserAgent::ProxyAny", for example, which has better
274 Win32/Internet Explorer interoperability.
275 One can use the code below as an example of how to change the default
277 UserAgent class.
278 use SOAP::Lite;
280 use SOAP::Transport::HTTP;
281 $SOAP::Transport::HTTP::Client::USERAGENT_CLASS = "My::UserAgent";
282 my $client = SOAP::Lite->proxy(..)->uri(..);
283 my $som = $client->myMethod();
284 There is one caveat, however. The UserAgent class you use, MUST also be
286 a subclass of "LWP::UserAgent". If it is not, then "SOAP::Lite" will
287 issue the following error: "Could not load UserAgent class <USERAGENT
288 CLASS>."
289 HTTP-KEEP-ALIVE, TIMEOUTS, AND MORE
291 Because "SOAP::Transport::HTTP::Client" extends "LWP::UserAgent", all
293 methods available "LWP::UserAgent" are also available to your SOAP
294 Clients. For example, using "LWP::UserAgent" HTTP keep alive's are
295 accomplished using the following code:
296 my $ua = LWP::UserAgent->new(
298 keep_alive => 1,
299 timeout => 30
300 );
301 Therefore, the same initialization parameters you would pass to
303 "LWP::UserAgent" can also be passed to your SOAP::Lite client's "proxy"
304 subroutine like so:
305 my $soap = SOAP::Lite
307 ->uri($uri)
308 ->proxy($proxyUrl,
309 timeout => 30,
310 keep_alive => 1,
311 );
312 This is true for all initialization parameters and methods of
314 "LWP::UserAgent".
315 METHODS
317 http_request
319 This method gives you acess to the HTTP Request object that will
320 be, or was transmitted to a SOAP Server. It returns a HTTP::Request
321 object.
322 http_response
324 This method gives you acess to the HTTP Response object that will
325 be, or was transmitted to a SOAP Server. It returns a
326 HTTP::Response object.
327 SOAP::Transport::HTTP::Server
329 Inherits from: SOAP::Server.
331 This is the most basic of the HTTP server implementations. It provides
333 the basic methods, new and handle. The handle method's behavior is
334 defined here, along with other methods specific to this class. The role
335 of this class is primarily to act as a superclass for the other HTTP-
336 based server classes.
337 handle
339 $server->handle;
340 Expects the request method to have been used to associate a
342 HTTP::Request object with the server object prior to being called.
343 This method retrieves that object reference to get at the request
344 being handled.
345 request(optional value)
347 $server->request($req_object)
348 Gets or sets the HTTP::Request object reference that the server
350 will process within the handle method.
351 response(optional value)
353 $server->response(HTTP::Response->new(...));
354 Gets or sets the HTTP::Response object reference that the server
356 has prepared for sending back to the client.
357 make_response(code, body)
359 $server->make_response(200, $body_xml);
360 Constructs and returns an object of the HTTP::Response class, using
362 the response code and content provided.
363 make_fault(fault arguments)
365 $server->response($server->make_fault(@data));
366 Creates a HTTP::Response object reference using a predefined HTTP
368 response code to signify that a fault has occurred. The arguments
369 are the same as those for the make_fault method of the SOAP::Server
370 class.
371 product_tokens
373 This method takes no arguments and simply returns a string identi‐
374 fying the elements of the server class itself. It is similar to the
375 product_tokens methods in the HTTP::Daemon and Apache classes.
376 SOAP::Transport::HTTP::CGI
378 Inherits from: SOAP::Transport::HTTP::Server.
380 This class is a direct subclass of SOAP::Transport::HTTP::Server and
382 defines no additional methods. It includes logic in its implementation
383 of the handle method that deals with the request headers and parameters
384 specific to a CGI environment.
385 EXAMPLE CGI
387 The following code sample is a CGI based Web Service that converts cel‐
389 cius to fahrenheit:
390 #!/usr/bin/perl
392 use SOAP::Transport::HTTP;
393 SOAP::Transport::HTTP::CGI
394 ->dispatch_to('C2FService')
395 ->handle;
396 BEGIN {
397 package C2FService;
398 use vars qw(@ISA);
399 @ISA = qw(Exporter SOAP::Server::Parameters);
400 use SOAP::Lite;
401 sub c2f {
402 my $self = shift;
403 my $envelope = pop;
404 my $temp = $envelope->dataof("//c2f/temperature");
405 return SOAP::Data->name('convertedTemp' => (((9/5)*($temp->value)) + 32));
406 }
407 }
408 EXAMPLE APACHE::REGISTRY USAGE
410 Using a strictly CGI based Web Service has certain performance draw‐
412 backs. Running the same CGI under the Apache::Registery system has cer‐
413 tain performance gains.
414 httpd.conf
416 Alias /mod_perl/ "/Your/Path/To/Deployed/Modules"
418 <Location /mod_perl>
419 SetHandler perl-script
420 PerlHandler Apache::Registry
421 PerlSendHeader On
422 Options +ExecCGI
423 </Location>
424 soap.cgi
426 use SOAP::Transport::HTTP;
428 SOAP::Transport::HTTP::CGI
430 ->dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method')
431 ->handle;
432 WARNING: Dynamic deployments with "Apache::Registry" will fail because
434 the module will be only loaded dynamically the first time. Subsequent
435 calls will produce "denied access" errors because once the module is
436 already in memory "SOAP::Lite" will bypass dynamic deployment. To work
437 around this, simply specify both the full PATH and MODULE name in "dis‐
438 patch_to()" and the module will be loaded dynamically, but will then
439 work as if under static deployment. See examples/server/soap.mod_cgi as
440 an example.
441 SOAP::Transport::HTTP::Daemon
443 Inherits from: SOAP::Transport::HTTP::Server.
445 The SOAP::Transport::HTTP::Daemon class encapsulates a reference to an
447 object of the HTTP::Daemon class (from the LWP package). The class
448 catches methods that aren't provided locally or by the superclass and
449 attempts to call them on the HTTP::Daemon object. Thus, all methods
450 defined in the documentation for that class are available to this class
451 as well. Any that conflict with methods in SOAP::Trans‐
452 port::HTTP::Server (such as product_tokens) go to the superclass. Addi‐
453 tionally, the behavior of the handle method is specific to this class:
454 handle
456 When invoked, this method enters into the typical accept loop in
457 which it waits for a request on the socket that the daemon object
458 maintains and deals with the content of the request. When all
459 requests from the connection returned by the accept method of the
460 HTTP::Daemon object have been processed, this method returns.
461 REUSING SOCKETS ON RESTART
463 Often when implementing an HTTP daemon, sockets will get tied up when
465 you try to restart the daemon server. This prevents the server from
466 restarting. Often users will see an error like "Cannot start server:
467 port already in use." To circumvent this, instruct SOAP::Lite to reuse
468 open sockets using "Reuse => 1":
469 my $daemon = SOAP::Transport::HTTP::Daemon
471 -> new (LocalPort => 80000, Reuse => 1)
472 EXAMPLE DAEMON SERVER
474 use SOAP::Transport::HTTP;
476 # change LocalPort to 81 if you want to test it with soapmark.pl
477 my $daemon = SOAP::Transport::HTTP::Daemon
478 -> new (LocalAddr => 'localhost', LocalPort => 80)
479 # specify list of objects-by-reference here
480 -> objects_by_reference(qw(My::PersistentIterator My::SessionIterator My::Chat))
481 # specify path to My/Examples.pm here
482 -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method')
483 ;
484 print "Contact to SOAP server at ", $daemon->url, "\n";
485 $daemon->handle;
486 SOAP::Transport::HTTP::Apache
488 Inherits from: SOAP::Transport::HTTP::Server.
490 This class provides an integration of the SOAP::Server base class with
492 the mod_perl extension for Apache. To work as a location handler, the
493 package provides a method called handler, for which handle is made an
494 alias. The new method isn't functionally different from the superclass.
495 Here are the other methods provided by this class:
496 handler(Apache request)
498 $server->handler($r)
499 Defines the basis for a location handler in the mod_perl fashion.
501 The method expects an Apache request object as the parameter, from
502 which it pulls the body of the request and calls the superclass
503 handle method.
504 Note that in this class, the local method named handle is aliased
506 to this method.
507 configure(Apache request)
509 $server->configure(Apache->request);
510 Per-location configuration information can be provided to the
512 server object using the Apache DirConfig directive and calling this
513 method on the object itself. When invoked, the method reads the
514 directory configuration information from Apache and looks for lines
515 of the form:
516 method => param
518 Each line that matches the pattern is regarded as a potential
520 method to call on the server object, with the remaining token taken
521 as the parameter to the method. Methods that take hash references
522 as arguments may be specified as:
523 method => key => param, key => param
525 The key/value pairs will be made into a hash reference on demand.
527 If the server object doesn't recognize the named method as valid,
528 it ignores the line.
529 EXAMPLE APACHE MOD_PERL SERVER
531 See examples/server/Apache.pm and Apache::SOAP for more information.
533 httpd.conf
535 <Location /soap>
537 SetHandler perl-script
538 PerlHandler SOAP::Apache
539 PerlSetVar options "compress_threshold => 10000"
540 </Location>
541 SOAP::Apache.pm
543 package SOAP::Apache;
545 use SOAP::Transport::HTTP;
546 my $server = SOAP::Transport::HTTP::Apache
547 ->dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method');
548 sub handler { $server->handler(@_) }
549 1;
550 See also Apache::SOAP.
552 SOAP::Transport::HTTP::FCGI
554 Inherits from: SOAP::Transport::HTTP::CGI.
556 This is an extension of the SOAP::Transport::HTTP::CGI that implements
558 the differences needed for the FastCGI protocol. None of the methods
559 are functionally different.
560 SOAP::Transport::IO
562 The SOAP::Transport::IO-based class allows for a sort of I/O proxying
564 by allowing the application to configure what files or filehandles are
565 used. This module supplies only a server class.
566 SOAP::Transport::IO::Server
568 Inherits from: SOAP::Server.
570 The server class defined here inherits all methods from SOAP::Server,
572 and adds two additional methods specific to the nature of the class:
573 in
575 $server->in(IO::File->new($file));
576 Gets or sets the current filehandle being used as the input source.
578 out
580 $server->out(\*STDERR);
581 Gets or sets the filehandle being used as the output destination.
583 SOAP::Transport::JABBER
585 This class uses the Net::Jabber classes to abstract the Jabber protocol
587 away from the direct notice of the application. Besides maintaining any
588 needed objects internally, the package also uses a separate class as a
589 proxy between communication layers, SOAP::Transport::JABBER::Query. The
590 Jabber support provides both client and server classes.
591 SOAP::Transport::JABBER::Client
593 Inherits from: SOAP::Client, Net::Jabber::Client. This class provides
595 localized implementations for both the new and send_receive methods,
596 neither of which are changed in terms of interface. The only difference
597 is that the send_receive method doesn't directly use the action hash
598 key on the input it receives. In addition to these two basic methods,
599 the server class overrides the endpoint method it would otherwise
600 inherit from SOAP::Client:
601 endpoint
603 In the general sense, this still acts as a basic accessor method,
604 with the same get value/set value behavior used consistently
605 through the SOAP::Lite module. The difference between this version
606 and most others is that when the endpoint is initially set or is
607 changed, the client object makes the connection to the Jabber end‐
608 point, sending the proper authentication credentials and setting up
609 the conversation mechanism using the SOAP::Transport::JABBER::Query
610 class as a delegate. It then calls the superclass endpoint method
611 to ensure that all other related elements are taken care of.
612 SOAP::Transport::JABBER::Server
614 Inherits from: SOAP::Server.
616 The server class provided for Jabber support defines a slightly differ‐
618 ent interface to the constructor. The server manages the Jabber commu‐
619 nication by means of an internal Net::Jabber::Client instance. In a
620 fashion similar to that used by SOAP::Transport::HTTP::Daemon, the
621 server class catches methods that are meant for the Jabber client and
622 treats them as if the class inherits directly from that class, without
623 actually doing so. In doing so, the handle method is implemented as a
624 frontend to the Process method of the Jabber client class. The differ‐
625 ence in the interface to the constructor is:
626 new(URI, optional server key/value options)
628 $srv = SOAP::Transport::JABBER::Server-> new($uri);
629 The constructor for the class expects that the first argument will
631 be a Jabber-style URI, followed by the standard set of optional
632 key/value pairs of method names and their parameters. All the
633 method/parameter pairs are delegated to the superclass constructor;
634 only the Jabber URI is handled locally. It's used to set up the
635 Net::Jabber::Client instance that manages the actual communica‐
636 tions.
637 SOAP::Transport::LOCAL
639 The SOAP::Transport::LOCAL module is designed to provide a no-transport
641 client class for tracing and debugging communications traffic. It links
642 SOAP::Client and SOAP::Server so that the same object that "sends" the
643 request also "receives" it.
644 SOAP::Transport::LOCAL::Client
646 Inherits from: SOAP::Client, SOAP::Server. The implementations of the
648 new and send_receive methods aren't noticeably different in their
649 interface. Their behavior warrants description, however:
650 new When the constructor creates a new object of this class, it sets up
652 a few things beyond the usual SOAP::Client layout. The is_success
653 method is set to a default value of 1. The dispatch_to method
654 inherited from SOAP::Server is called with the current value of the
655 global array @INC, allowing the client to call any methods that can
656 be found in the current valid search path. And as with most of the
657 constructors in this module, the optional key/value pairs are
658 treated as method names and parameters.
659 send_receive
661 The implementation of this method simply passes the envelope por‐
662 tion of the input data to the handle method of SOAP::Server. While
663 no network traffic results (directly) from this, it allows for
664 debug signals to be sent through the SOAP::Trace facility.
665 SOAP::Transport::MAILTO
667 This transport class manages SMTP-based sending of messages from a
669 client perspective. It doesn't provide a server class. The class gets
670 selected when a client object passes a URI to proxy or endpoint that
671 starts with the characters, mailto:.
672 SOAP::Transport::MAILTO::Client
674 Inherits from: SOAP::Client.
676 The client class for this protocol doesn't define any new methods. The
678 constructor functions in the same style as the others class construc‐
679 tors. The functionality of the send_receive method is slightly differ‐
680 ent from other classes, however.
681 When invoked, the send_receive method uses the MIME::Lite package to
683 encapsulate and transmit the message. Because mail messages are one-way
684 communications (the reply being a separate process), there is no
685 response message to be returned by the method. Instead, all the status-
686 related attributes (code, message, status, is_success) are set, and no
687 value is explicitly returned.
688 SOAP::Transport::MQ
690 This class provides implementations of both client and server frame‐
692 works built on IBM's Message Queue set of classes. The SOAP objects
693 encapsulate additional objects from these classes, creating and using
694 them behind the scenes as needed.
695 SOAP::Transport::MQ::Client
697 Inherits from: SOAP::Client.
699 The client class provides two methods specific to it, as well as spe‐
701 cialized versions of the endpoint and send_receive methods. It also
702 provides a localized new method, but the interface isn't changed from
703 the superclass method. The new methods are:
704 requestqueue
706 $client->requestqueue->Put(message => $request);
707 Manages the MQSeries::Queue object the client uses for enqueuing
709 requests to the server. In general, an application shouldn't need
710 to directly access this attribute, let alone set it. If setting it,
711 the new value should be an object of (or derived from) the
712 MQSeries::Queue class.
713 replyqueue
715 $client->replyqueue(MQSeries::Queue->new(%args));
716 Manages the queue object used for receiving messages back from the
718 designated server (endpoint). It is also primarily for internal
719 use, though if the application needs to set it explicitly, the new
720 value should be an object of (or derived from) the MQSeries::Queue
721 class.
722 The two previous methods are mainly used by the localized versions of
724 the methods:
725 endpoint
727 This accessor method has the same interface as other similar
728 classes but is worth noting for the internal actions that take
729 place. When the endpoint is set or changed, the method creates a
730 queue-manager object (from the MQSeries::QueueManager class) and
731 references this object when creating queues for replies and
732 requests using the methods described earlier. The URI structure
733 used with these classes (strings beginning with the characters
734 mq://user@host:port) contains the information needed for these
735 operations.
736 send_receive
738 This method uses the same interface as other classes, but makes use
739 of only the endpoint and envelope keys in the hash-table input
740 data. The endpoint key is needed only if the client wishes to
741 switch endpoints prior to sending the message. The message (the
742 value of the envelope key) is inserted into the queue stored in the
743 requestqueue attribute. The client then waits for a reply to the
744 message to appear in the queue stored in the replyqueue attribute.
745 SOAP::Transport::MQ::Server
747 Inherits from: SOAP::Server.
749 The server class also defines requestqueue and replyqueue methods under
751 the same terms as the client class. Of course, the server reads from
752 the request queue and writes to the reply queue, the opposite of the
753 client's behavior. The methods whose functionality are worth noting
754 are:
755 new(URI, optional parameters)
757 When called, the constructor creates the MQSeries::QueueManager
758 object and the two MQSeries::Queue objects, similar to what the
759 client does inside its endpoint method. Like the Jabber server
760 described earlier, the first argument to this constructor is
761 expected to be the URI that describes the server itself. The
762 remainder of the arguments are treated as key/value pairs, as with
763 other class constructors previously described.
764 handle
766 When this method is called, it attempts to read a pending message
767 from the request-queue stored on the requestqueue attribute. The
768 message itself is passed to the handle method of the superclass,
769 and the result from that operation is enqueued to the replyqueue
770 object. This process loops until no more messages are present in
771 the request queue. The return value is the number of messages pro‐
772 cessed. The reads from the request queue are done in a nonblocking
773 fashion, so if there is no message pending, the method immediately
774 returns with a value of zero.
775 SOAP::Transport::POP3
777 POP3 support is limited to a server implementation. Just as the MAILTO
779 class detailed earlier operates by sending requests without expecting
780 to process a response, the server described here accepts request mes‐
781 sages and dispatches them without regard for sending a response other
782 than that which POP3 defines for successful delivery of a message.
783 SOAP::Transport::POP3::Server
785 Inherits from: SOAP::Server.
787 The new method of this class creates an object of the Net::POP3 class
789 to use internally for polling a specified POP3 server for incoming mes‐
790 sages. When an object of this class is created, it expects an endpoint
791 to be specified with a URI that begins with the characters pop:// and
792 includes user ID and password information as well as the hostname
793 itself.
794 The handle method takes the messages present in the remote mailbox and
796 passes them (one at a time) to the superclass handle method. Each mes‐
797 sage is deleted after being routed. All messages in the POP3 mailbox
798 are presumed to be SOAP messages.
799 Methods for the Net::POP3 object are detected and properly routed,
801 allowing operations such as $server->ping( ).
802 This means that the endpoint string doesn't need to provide the user ID
804 and password because the login method from the POP3 API may be used
805 directly.
806 SOAP::Transport::TCP
808 The classes provided by this module implement direct TCP/IP communica‐
810 tions methods for both clients and servers.
811 The connections don't use HTTP or any other higher-level protocol.
813 These classes are selected when the client or server object being cre‐
814 ated uses an endpoint URI that starts with tcp://. Both client and
815 server classes support using Secure Socket Layer if it is available. If
816 any of the parameters to a new method from either of the classes begins
817 with SSL_ (such as SSL_server in place of Server), the class attempts
818 to load the IO::Socket::SSL package and use it to create socket
819 objects.
820 Both of the following classes catch methods that are intended for the
822 socket objects and pass them along, allowing calls such as
823 $client->accept( ) without including the socket class in the inheri‐
824 tance tree.
825 SOAP::Transport::TCP::Client
827 Inherits from: SOAP::Client.
829 The TCP client class defines only two relevant methods beyond new and
831 send_receive. These methods are:
832 SSL(optional new boolean value)
834 if ($client->SSL) # Execute only if in SSL mode
835 Reflects the attribute that denotes whether the client object is
837 using SSL sockets for communications.
838 io_socket_class
840 ($client->io_socket_class)->new(%options);
841 Returns the name of the class to use when creating socket objects
843 for internal use in communications. As implemented, it returns one
844 of IO::Socket::INET or IO::Socket::SSL, depending on the return
845 value of the previous SSL method.
846 If an application creates a subclass that inherits from this client
848 class, either method is a likely target for overloading.
849 The new method behaves identically to most other classes, except that
851 it detects the presence of SSL-targeted values in the parameter list
852 and sets the SSL method appropriately if they are present.
853 The send_receive method creates a socket of the appropriate class and
855 connects to the configured endpoint. It then sets the socket to non‐
856 blocking I/O, sends the message, shuts down the client end of the con‐
857 nection (preventing further writing), and reads the response back from
858 the server. The socket object is discarded after the response and
859 appropriate status codes are set on the client object.
860 SOAP::Transport::TCP::Server
862 Inherits from: SOAP::Server.
864 The server class also defines the same two additional methods as in the
866 client class:
867 SSL(optional new boolean value)
869 if ($client->SSL) # Execute only if in SSL mode
870 Reflects the attribute that denotes whether the client object is
872 using SSL sockets for communications.
873 io_socket_class
875 ($client->io_socket_class)->new(%options);
876 Returns the name of the class to use when creating socket objects
878 for internal use in communications. As implemented, it returns one
879 of IO::Socket::INET or IO::Socket::SSL, depending on the return
880 value of the previous SSL method. The new method also manages the
881 automatic selection of SSL in the same fashion as the client class
882 does.
883 The handle method in this server implementation isn't designed to
885 be called once with each new request. Rather, it is called with no
886 arguments, at which time it enters into an infinite loop of waiting
887 for a connection, reading the request, routing the request and
888 sending back the serialized response. This continues until the
889 process itself is interrupted by an untrapped signal or similar
890 means.
891
893 Special thanks to O'Reilly publishing which has graciously allowed
894 SOAP::Lite to republish and redistribute large excerpts from Program‐
895 ming Web Services with Perl, mainly the SOAP::Lite reference found in
896 Appendix B.
897
899 Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.
900 This library is free software; you can redistribute it and/or modify it
902 under the same terms as Perl itself.
903
905 Paul Kulchenko (paulclinger@yahoo.com)
906 Randy J. Ray (rjray@blackperl.com)
908 Byrne Reese (byrne@majordojo.com)
910perl v5.8.8 2006-06-15 SOAP::Transport(3)