1SOAP::Transport(3) User Contributed Perl Documentation SOAP::Transport(3)
2
6 SOAP::Transport - an abstract class extended by more specialized
7 transport 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
22 application directly. An application can use this to create a fresh
23 new SOAP::Transport object, which may be installed using the
24 SOAP::Lite->transport method defined earlier. No arguments are
25 recognized.
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,
33 jabber, etc.). Until this method is called the first time with a
34 URL string, the underlying code has yet to be loaded, and the
35 methods aren't available. When getting the current proxy (calling
36 with no parameters), the returned value is a reference to the
37 client object created from the protocol class that matched the
38 endpoint, not the 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
70 is subclassing another transport class) at least two methods. Any newly
71 developed transport classes are also expected to adhere to this
72 interface. Clients are expected to implement the "new" and
73 "send_receive" methods, and servers are expected to implement the "new"
74 and "handle" methods. Here they are:
75 new(optional key/value pairs)
77 $object = $class->new(%params);
78 Creates a new object instance and returns it. Like the constructors
80 for both "SOAP::Lite" and SOAP::Server classes, all arguments
81 passed in are treated as key/value pairs, where the key is expected
82 to be one of the methods the class supports, and the value is the
83 argument (or list reference of arguments) to the method.
84 send_receive(key/value pairs)
86 $client->send_recieve(%hash_table);
87 (Required for client classes only) When the SOAP::Lite objects
89 attempt to send out requests, the means for doing so is to attempt
90 to call this method on the object held within the SOAP::Transport
91 object contained within the client itself. All clients are expected
92 to provide this, and the call to this method always passes four
93 values for the hash keys:
94 action
96 The URI specifying the action being performed, usually the
97 result from the on_action hook on the client object.
98 encoding
100 The URI of the encoding scheme that governs the message being
101 sent.
102 endpoint
104 The URI specifying the endpoint to which the message is being
105 sent.
106 envelope
108 The XML content of the message to be sent. It is generally the
109 return value of the envelope method from the SOAP::Serializer
110 object instance that the client object maintains.
111 parts
113 Attachments to add to the request. Currently this only supports
114 an array of MIME::Entity objects, but in theory could support
115 attachments of any format.
116 handle
118 $server->handle;
119 (Required for server classes only.) This method is the central
121 point for the various server classes to provide an interface to
122 handling requests. The exact set and nature of parameters generally
123 varies based on the classes themselves.
124 SOAP::Transport::FTP
126 The SOAP::Transport::FTP module is automatically loaded by the
127 SOAP::Transport portion of the client structure. It is brought in when
128 an endpoint is specified via the proxy method that starts with the
129 characters, ftp://. This module provides only a client class.
130 SOAP::Transport::FTP::Client
132 Inherits from: SOAP::Client.
134 Support is provided for clients to connect to FTP servers using SOAP.
136 The methods defined within the class are just the basic new and
137 send_receive.
138 SOAP::Transport::HTTP
140 The most commonly used transport module is the HTTP implementation.
141 This is loaded whenever an endpoint is given that starts with the
142 characters, http:// or https://. This is also the most involved of the
143 transport modules, defining not only a client class but several
144 different server classes as well.
145 HTTP PROXY SETTINGS
147 Because "SOAP::Client" inherits from "LWP::UserAgent", you can use any
149 of "LWP::UserAgent"'s proxy settings. For example:
150 SOAP::Lite->proxy("http://endpoint.server/",
152 proxy => ["http" => "http://my.proxy.server"]);
153 or
155 $soap->transport->proxy("http" => "http://my.proxy.server");
157 The above code samples should specify a proxy server for you. And
159 should you use "HTTP_proxy_user" and "HTTP_proxy_pass" for proxy
160 authorization, "SOAP::Lite" will handle it properly.
161 HTTP BASIC AUTHENTICATION
163 HTTP Basic authentication is accomplished by overriding the
165 get_basic_credentials suboutine in "LWP::UserAgent" (which
166 "SOAP::Transport::HTTP::Client" is a subclass):
167 BEGIN {
169 sub SOAP::Transport::HTTP::Client::get_basic_credentials {
170 return 'username' => 'password';
171 }
172 }
173 COOKIE-BASED AUTHENTICATION
175 use HTTP::Cookies;
177 my $cookies = HTTP::Cookies->new(ignore_discard => 1);
178 # you may also add 'file' if you want to keep them between sessions
179 my $soap = SOAP::Lite->proxy('http://localhost/');
180 $soap->transport->cookie_jar($cookies);
181 Or, alternatively, you can do the above on a single line:
183 $soap->proxy('http://localhost/',
185 cookie_jar => HTTP::Cookies->new(ignore_discard => 1));
186 Cookies will be taken from the response and provided to the request.
188 You may access and manipulate cookies received, as well as add cookies
189 of your own by using the "HTTP::Cookies" interfaces.
190 SSL CERTIFICATE AUTHENTICATION
192 To get certificate authentication working you need to set three
194 environment variables: "HTTPS_CERT_FILE", "HTTPS_KEY_FILE", and
195 optionally "HTTPS_CERT_PASS". This can be done either through the
196 command line, or directly within your Perl script using the $ENV
197 variable:
198 $ENV{HTTPS_CERT_FILE} = 'client-cert.pem';
200 $ENV{HTTPS_KEY_FILE} = 'client-key.pem';
201 These settings are referrenced by "Crypt::SSLeay", the module
203 SOAP::Lite used for HTTPS support. Other options (e.g. CA peer
204 verification) can be specified in a similar way. See Crypt::SSLeay
205 documentation for more information.
206 Those who would like to use encrypted keys may find the following
208 thread in the SOAP::Lite newsgroup helpful:
209 http://groups.yahoo.com/group/soaplite/message/729
211 COMPRESSION
213 SOAP::Lite provides you with the option for enabling compression over
215 the wire using HTTP only in both the server and client contexts,
216 provided that you have Compress::Zlib installed. Compression and
217 decompression is done transparantly to your application.
218 A server will respond with an encoded/compressed message only if the
220 client has asserted that it can accept it (indicated by client sending
221 an "Accept-Encoding" HTTP header with a 'deflate' or '*' value).
222 "SOAP::Lite" clients all have fallback logic implemented so that if a
224 server doesn't understand the specified encoding (i.e. "Content-
225 Encoding: deflate") and returns the proper HTTP status code (415 NOT
226 ACCEPTABLE), the client will repeat the request without using
227 encoding/compression. The client will then store this server in a per-
228 session cache, so that all subsequent requests to that server will be
229 transmitted without encoding.
230 Compression is enabled on the client side by specifying the
232 "compress_threshold" option, and if the size of the current request
233 exceeds that threshold.
234 Client Code Sample
236 print SOAP::Lite
238 ->uri('http://localhost/My/Parameters')
239 ->proxy('http://localhost/', options => {compress_threshold => 10000})
240 ->echo(1 x 10000)
241 ->result;
242 Servers will respond with a compressed message if the
244 "compress_threshold" option has been specified, if the size of the
245 current response exceeds that threshold, and if the calling client
246 transmitted the proper "Accept-Encoding" HTTP Header.
247 Server Code Sample
249 my $server = SOAP::Transport::HTTP::CGI
251 ->dispatch_to('My::Parameters')
252 ->options({compress_threshold => 10000})
253 ->handle;
254 See also: Compress::Zlib
256 SOAP::Transport::HTTP::Client
258 Inherits from: SOAP::Client, LWP::UserAgent (from the LWP package).
260 With this class, clients are able to use HTTP for sending messages.
262 This class provides just the basic new and send_receive methods.
263 Objects of this class understand the compress_threshold option and use
264 it if the server being communicated to also understands it.
265 CHANGING THE DEFAULT USERAGENT CLASS
267 By default, "SOAP::Transport::HTTP::Client" extends "LWP::UserAgent".
269 But under some circumstances, a user may wish to change the default
270 UserAgent class with their in order to better handle persist
271 connections, or to "LWP::UserAgent::ProxyAny", for example, which has
272 better Win32/Internet Explorer interoperability.
273 One can use the code below as an example of how to change the default
275 UserAgent class.
276 use SOAP::Lite;
278 use SOAP::Transport::HTTP;
279 $SOAP::Transport::HTTP::Client::USERAGENT_CLASS = "My::UserAgent";
280 my $client = SOAP::Lite->proxy(..)->uri(..);
281 my $som = $client->myMethod();
282 There is one caveat, however. The UserAgent class you use, MUST also be
284 a subclass of "LWP::UserAgent". If it is not, then "SOAP::Lite" will
285 issue the following error: "Could not load UserAgent class <USERAGENT
286 CLASS>."
287 HTTP-KEEP-ALIVE, TIMEOUTS, AND MORE
289 Because "SOAP::Transport::HTTP::Client" extends "LWP::UserAgent", all
291 methods available "LWP::UserAgent" are also available to your SOAP
292 Clients. For example, using "LWP::UserAgent" HTTP keep alive's are
293 accomplished using the following code:
294 my $ua = LWP::UserAgent->new(
296 keep_alive => 1,
297 timeout => 30
298 );
299 Therefore, the same initialization parameters you would pass to
301 "LWP::UserAgent" can also be passed to your SOAP::Lite client's "proxy"
302 subroutine like so:
303 my $soap = SOAP::Lite
305 ->uri($uri)
306 ->proxy($proxyUrl,
307 timeout => 30,
308 keep_alive => 1,
309 );
310 This is true for all initialization parameters and methods of
312 "LWP::UserAgent".
313 METHODS
315 http_request
317 This method gives you acess to the HTTP Request object that will
318 be, or was transmitted to a SOAP Server. It returns a HTTP::Request
319 object.
320 http_response
322 This method gives you acess to the HTTP Response object that will
323 be, or was transmitted to a SOAP Server. It returns a
324 HTTP::Response object.
325 SOAP::Transport::HTTP::Server
327 Inherits from: SOAP::Server.
329 This is the most basic of the HTTP server implementations. It provides
331 the basic methods, new and handle. The handle method's behavior is
332 defined here, along with other methods specific to this class. The role
333 of this class is primarily to act as a superclass for the other HTTP-
334 based server classes.
335 handle
337 $server->handle;
338 Expects the request method to have been used to associate a
340 HTTP::Request object with the server object prior to being called.
341 This method retrieves that object reference to get at the request
342 being handled.
343 request(optional value)
345 $server->request($req_object)
346 Gets or sets the HTTP::Request object reference that the server
348 will process within the handle method.
349 response(optional value)
351 $server->response(HTTP::Response->new(...));
352 Gets or sets the HTTP::Response object reference that the server
354 has prepared for sending back to the client.
355 make_response(code, body)
357 $server->make_response(200, $body_xml);
358 Constructs and returns an object of the HTTP::Response class, using
360 the response code and content provided.
361 make_fault(fault arguments)
363 $server->response($server->make_fault(@data));
364 Creates a HTTP::Response object reference using a predefined HTTP
366 response code to signify that a fault has occurred. The arguments
367 are the same as those for the make_fault method of the SOAP::Server
368 class.
369 product_tokens
371 This method takes no arguments and simply returns a string
372 identifying the elements of the server class itself. It is similar
373 to the product_tokens methods in the HTTP::Daemon and Apache
374 classes.
375 SOAP::Transport::HTTP::CGI
377 Inherits from: SOAP::Transport::HTTP::Server.
379 This class is a direct subclass of SOAP::Transport::HTTP::Server and
381 defines no additional methods. It includes logic in its implementation
382 of the handle method that deals with the request headers and parameters
383 specific to a CGI environment.
384 EXAMPLE CGI
386 The following code sample is a CGI based Web Service that converts
388 celcius to fahrenheit:
389 #!/usr/bin/perl
391 use SOAP::Transport::HTTP;
392 SOAP::Transport::HTTP::CGI
393 ->dispatch_to('C2FService')
394 ->handle;
395 BEGIN {
396 package C2FService;
397 use vars qw(@ISA);
398 @ISA = qw(Exporter SOAP::Server::Parameters);
399 use SOAP::Lite;
400 sub c2f {
401 my $self = shift;
402 my $envelope = pop;
403 my $temp = $envelope->dataof("//c2f/temperature");
404 return SOAP::Data->name('convertedTemp' => (((9/5)*($temp->value)) + 32));
405 }
406 }
407 EXAMPLE APACHE::REGISTRY USAGE
409 Using a strictly CGI based Web Service has certain performance
411 drawbacks. Running the same CGI under the Apache::Registery system has
412 certain performance gains.
413 httpd.conf
415 Alias /mod_perl/ "/Your/Path/To/Deployed/Modules"
417 <Location /mod_perl>
418 SetHandler perl-script
419 PerlHandler Apache::Registry
420 PerlSendHeader On
421 Options +ExecCGI
422 </Location>
423 soap.cgi
425 use SOAP::Transport::HTTP;
427 SOAP::Transport::HTTP::CGI
429 ->dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method')
430 ->handle;
431 WARNING: Dynamic deployments with "Apache::Registry" will fail because
433 the module will be only loaded dynamically the first time. Subsequent
434 calls will produce "denied access" errors because once the module is
435 already in memory "SOAP::Lite" will bypass dynamic deployment. To work
436 around this, simply specify both the full PATH and MODULE name in
437 "dispatch_to()" and the module will be loaded dynamically, but will
438 then work as if under static deployment. See
439 examples/server/soap.mod_cgi as an example.
440 SOAP::Transport::HTTP::Daemon
442 Inherits from: SOAP::Transport::HTTP::Server.
444 The SOAP::Transport::HTTP::Daemon class encapsulates a reference to an
446 object of the HTTP::Daemon class (from the LWP package). The class
447 catches methods that aren't provided locally or by the superclass and
448 attempts to call them on the HTTP::Daemon object. Thus, all methods
449 defined in the documentation for that class are available to this class
450 as well. Any that conflict with methods in
451 SOAP::Transport::HTTP::Server (such as product_tokens) go to the
452 superclass. Additionally, the behavior of the handle method is specific
453 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
563 by allowing the application to configure what files or filehandles are
564 used. This module supplies only a server class.
565 SOAP::Transport::IO::Server
567 Inherits from: SOAP::Server.
569 The server class defined here inherits all methods from SOAP::Server,
571 and adds two additional methods specific to the nature of the class:
572 in
574 $server->in(IO::File->new($file));
575 Gets or sets the current filehandle being used as the input source.
577 out
579 $server->out(\*STDERR);
580 Gets or sets the filehandle being used as the output destination.
582 SOAP::Transport::JABBER
584 This class uses the Net::Jabber classes to abstract the Jabber protocol
585 away from the direct notice of the application. Besides maintaining any
586 needed objects internally, the package also uses a separate class as a
587 proxy between communication layers, SOAP::Transport::JABBER::Query. The
588 Jabber support provides both client and server classes.
589 SOAP::Transport::JABBER::Client
591 Inherits from: SOAP::Client, Net::Jabber::Client. This class provides
593 localized implementations for both the new and send_receive methods,
594 neither of which are changed in terms of interface. The only difference
595 is that the send_receive method doesn't directly use the action hash
596 key on the input it receives. In addition to these two basic methods,
597 the server class overrides the endpoint method it would otherwise
598 inherit from SOAP::Client:
599 endpoint
601 In the general sense, this still acts as a basic accessor method,
602 with the same get value/set value behavior used consistently
603 through the SOAP::Lite module. The difference between this version
604 and most others is that when the endpoint is initially set or is
605 changed, the client object makes the connection to the Jabber
606 endpoint, sending the proper authentication credentials and setting
607 up the conversation mechanism using the
608 SOAP::Transport::JABBER::Query class as a delegate. It then calls
609 the superclass endpoint method to ensure that all other related
610 elements are taken care of.
611 SOAP::Transport::JABBER::Server
613 Inherits from: SOAP::Server.
615 The server class provided for Jabber support defines a slightly
617 different interface to the constructor. The server manages the Jabber
618 communication by means of an internal Net::Jabber::Client instance. In
619 a fashion similar to that used by SOAP::Transport::HTTP::Daemon, the
620 server class catches methods that are meant for the Jabber client and
621 treats them as if the class inherits directly from that class, without
622 actually doing so. In doing so, the handle method is implemented as a
623 frontend to the Process method of the Jabber client class. The
624 difference in the interface to the constructor is:
625 new(URI, optional server key/value options)
627 $srv = SOAP::Transport::JABBER::Server-> new($uri);
628 The constructor for the class expects that the first argument will
630 be a Jabber-style URI, followed by the standard set of optional
631 key/value pairs of method names and their parameters. All the
632 method/parameter pairs are delegated to the superclass constructor;
633 only the Jabber URI is handled locally. It's used to set up the
634 Net::Jabber::Client instance that manages the actual
635 communications.
636 SOAP::Transport::LOCAL
638 The SOAP::Transport::LOCAL module is designed to provide a no-transport
639 client class for tracing and debugging communications traffic. It links
640 SOAP::Client and SOAP::Server so that the same object that "sends" the
641 request also "receives" it.
642 SOAP::Transport::LOCAL::Client
644 Inherits from: SOAP::Client, SOAP::Server. The implementations of the
646 new and send_receive methods aren't noticeably different in their
647 interface. Their behavior warrants description, however:
648 new When the constructor creates a new object of this class, it sets up
650 a few things beyond the usual SOAP::Client layout. The is_success
651 method is set to a default value of 1. The dispatch_to method
652 inherited from SOAP::Server is called with the current value of the
653 global array @INC, allowing the client to call any methods that can
654 be found in the current valid search path. And as with most of the
655 constructors in this module, the optional key/value pairs are
656 treated as method names and parameters.
657 send_receive
659 The implementation of this method simply passes the envelope
660 portion of the input data to the handle method of SOAP::Server.
661 While no network traffic results (directly) from this, it allows
662 for debug signals to be sent through the SOAP::Trace facility.
663 SOAP::Transport::MAILTO
665 This transport class manages SMTP-based sending of messages from a
666 client perspective. It doesn't provide a server class. The class gets
667 selected when a client object passes a URI to proxy or endpoint that
668 starts with the characters, mailto:.
669 SOAP::Transport::MAILTO::Client
671 Inherits from: SOAP::Client.
673 The client class for this protocol doesn't define any new methods. The
675 constructor functions in the same style as the others class
676 constructors. The functionality of the send_receive method is slightly
677 different from other classes, however.
678 When invoked, the send_receive method uses the MIME::Lite package to
680 encapsulate and transmit the message. Because mail messages are one-way
681 communications (the reply being a separate process), there is no
682 response message to be returned by the method. Instead, all the status-
683 related attributes (code, message, status, is_success) are set, and no
684 value is explicitly returned.
685 SOAP::Transport::MQ
687 This class provides implementations of both client and server
688 frameworks built on IBM's Message Queue set of classes. The SOAP
689 objects encapsulate additional objects from these classes, creating and
690 using them behind the scenes as needed.
691 SOAP::Transport::MQ::Client
693 Inherits from: SOAP::Client.
695 The client class provides two methods specific to it, as well as
697 specialized versions of the endpoint and send_receive methods. It also
698 provides a localized new method, but the interface isn't changed from
699 the superclass method. The new methods are:
700 requestqueue
702 $client->requestqueue->Put(message => $request);
703 Manages the MQSeries::Queue object the client uses for enqueuing
705 requests to the server. In general, an application shouldn't need
706 to directly access this attribute, let alone set it. If setting it,
707 the new value should be an object of (or derived from) the
708 MQSeries::Queue class.
709 replyqueue
711 $client->replyqueue(MQSeries::Queue->new(%args));
712 Manages the queue object used for receiving messages back from the
714 designated server (endpoint). It is also primarily for internal
715 use, though if the application needs to set it explicitly, the new
716 value should be an object of (or derived from) the MQSeries::Queue
717 class.
718 The two previous methods are mainly used by the localized versions of
720 the methods:
721 endpoint
723 This accessor method has the same interface as other similar
724 classes but is worth noting for the internal actions that take
725 place. When the endpoint is set or changed, the method creates a
726 queue-manager object (from the MQSeries::QueueManager class) and
727 references this object when creating queues for replies and
728 requests using the methods described earlier. The URI structure
729 used with these classes (strings beginning with the characters
730 mq://user@host:port) contains the information needed for these
731 operations.
732 send_receive
734 This method uses the same interface as other classes, but makes use
735 of only the endpoint and envelope keys in the hash-table input
736 data. The endpoint key is needed only if the client wishes to
737 switch endpoints prior to sending the message. The message (the
738 value of the envelope key) is inserted into the queue stored in the
739 requestqueue attribute. The client then waits for a reply to the
740 message to appear in the queue stored in the replyqueue attribute.
741 SOAP::Transport::MQ::Server
743 Inherits from: SOAP::Server.
745 The server class also defines requestqueue and replyqueue methods under
747 the same terms as the client class. Of course, the server reads from
748 the request queue and writes to the reply queue, the opposite of the
749 client's behavior. The methods whose functionality are worth noting
750 are:
751 new(URI, optional parameters)
753 When called, the constructor creates the MQSeries::QueueManager
754 object and the two MQSeries::Queue objects, similar to what the
755 client does inside its endpoint method. Like the Jabber server
756 described earlier, the first argument to this constructor is
757 expected to be the URI that describes the server itself. The
758 remainder of the arguments are treated as key/value pairs, as with
759 other class constructors previously described.
760 handle
762 When this method is called, it attempts to read a pending message
763 from the request-queue stored on the requestqueue attribute. The
764 message itself is passed to the handle method of the superclass,
765 and the result from that operation is enqueued to the replyqueue
766 object. This process loops until no more messages are present in
767 the request queue. The return value is the number of messages
768 processed. The reads from the request queue are done in a
769 nonblocking fashion, so if there is no message pending, the method
770 immediately returns with a value of zero.
771 SOAP::Transport::POP3
773 POP3 support is limited to a server implementation. Just as the MAILTO
774 class detailed earlier operates by sending requests without expecting
775 to process a response, the server described here accepts request
776 messages and dispatches them without regard for sending a response
777 other than that which POP3 defines for successful delivery of a
778 message.
779 SOAP::Transport::POP3::Server
781 Inherits from: SOAP::Server.
783 The new method of this class creates an object of the Net::POP3 class
785 to use internally for polling a specified POP3 server for incoming
786 messages. When an object of this class is created, it expects an
787 endpoint to be specified with a URI that begins with the characters
788 pop:// and includes user ID and password information as well as the
789 hostname itself.
790 The handle method takes the messages present in the remote mailbox and
792 passes them (one at a time) to the superclass handle method. Each
793 message is deleted after being routed. All messages in the POP3 mailbox
794 are presumed to be SOAP messages.
795 Methods for the Net::POP3 object are detected and properly routed,
797 allowing operations such as $server->ping( ).
798 This means that the endpoint string doesn't need to provide the user ID
800 and password because the login method from the POP3 API may be used
801 directly.
802 SOAP::Transport::TCP
804 The classes provided by this module implement direct TCP/IP
805 communications methods for both clients and servers.
806 The connections don't use HTTP or any other higher-level protocol.
808 These classes are selected when the client or server object being
809 created uses an endpoint URI that starts with tcp://. Both client and
810 server classes support using Secure Socket Layer if it is available. If
811 any of the parameters to a new method from either of the classes begins
812 with SSL_ (such as SSL_server in place of Server), the class attempts
813 to load the IO::Socket::SSL package and use it to create socket
814 objects.
815 Both of the following classes catch methods that are intended for the
817 socket objects and pass them along, allowing calls such as
818 $client->accept( ) without including the socket class in the
819 inheritance tree.
820 SOAP::Transport::TCP::Client
822 Inherits from: SOAP::Client.
824 The TCP client class defines only two relevant methods beyond new and
826 send_receive. These methods are:
827 SSL(optional new boolean value)
829 if ($client->SSL) # Execute only if in SSL mode
830 Reflects the attribute that denotes whether the client object is
832 using SSL sockets for communications.
833 io_socket_class
835 ($client->io_socket_class)->new(%options);
836 Returns the name of the class to use when creating socket objects
838 for internal use in communications. As implemented, it returns one
839 of IO::Socket::INET or IO::Socket::SSL, depending on the return
840 value of the previous SSL method.
841 If an application creates a subclass that inherits from this client
843 class, either method is a likely target for overloading.
844 The new method behaves identically to most other classes, except that
846 it detects the presence of SSL-targeted values in the parameter list
847 and sets the SSL method appropriately if they are present.
848 The send_receive method creates a socket of the appropriate class and
850 connects to the configured endpoint. It then sets the socket to
851 nonblocking I/O, sends the message, shuts down the client end of the
852 connection (preventing further writing), and reads the response back
853 from the server. The socket object is discarded after the response and
854 appropriate status codes are set on the client object.
855 SOAP::Transport::TCP::Server
857 Inherits from: SOAP::Server.
859 The server class also defines the same two additional methods as in the
861 client class:
862 SSL(optional new boolean value)
864 if ($client->SSL) # Execute only if in SSL mode
865 Reflects the attribute that denotes whether the client object is
867 using SSL sockets for communications.
868 io_socket_class
870 ($client->io_socket_class)->new(%options);
871 Returns the name of the class to use when creating socket objects
873 for internal use in communications. As implemented, it returns one
874 of IO::Socket::INET or IO::Socket::SSL, depending on the return
875 value of the previous SSL method. The new method also manages the
876 automatic selection of SSL in the same fashion as the client class
877 does.
878 The handle method in this server implementation isn't designed to
880 be called once with each new request. Rather, it is called with no
881 arguments, at which time it enters into an infinite loop of waiting
882 for a connection, reading the request, routing the request and
883 sending back the serialized response. This continues until the
884 process itself is interrupted by an untrapped signal or similar
885 means.
886
888 Special thanks to O'Reilly publishing which has graciously allowed
889 SOAP::Lite to republish and redistribute large excerpts from
890 Programming Web Services with Perl, mainly the SOAP::Lite reference
891 found in Appendix B.
892
894 Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.
895 This library is free software; you can redistribute it and/or modify it
897 under the same terms as Perl itself.
898
900 Paul Kulchenko (paulclinger@yahoo.com)
901 Randy J. Ray (rjray@blackperl.com)
903 Byrne Reese (byrne@majordojo.com)
905perl v5.10.1 2008-03-15 SOAP::Transport(3)