1# ====================================================================== 2# 3# Copyright (C) 2000-2003 Paul Kulchenko (paulclinger@yahoo.com) 4# SOAP::Lite is free software; you can redistribute it 5# and/or modify it under the same terms as Perl itself. 6# 7# $Id: Transport.pm,v 1.3 2004/10/22 22:23:44 byrnereese Exp $ 8# 9# ====================================================================== 10 11=pod 12 13=head1 NAME 14 15SOAP::Transport - an abstract class extended by more specialized transport modules 16 17=head1 DESCRIPTION 18 19Objects of the SOAP::Transport class manage two roles: they manage both the parameters related to transport as set through the containing SOAP::Lite object, and they abstract the selection and loading of an appropriate transport module. This is done with an AUTOLOAD function within the class that intercepts all methods beyond the two defined next and reroutes them to the underlying transport implementation code. 20 21=head1 METHODS 22 23=over 24 25=item new 26 27 $trans = SOAP::Transport->new; 28 29This is the constructor, which isn't usually called by an application directly. An application can use this to create a fresh new SOAP::Transport object, which may be installed using the SOAP::Lite->transport method defined earlier. No arguments are recognized. 30 31=item proxy(optional URL string) 32 33 $trans->proxy('http://www.blackperl.com/SOAP'); 34 35Gets or sets the proxy (endpoint). This method must be called before any other methods are called. The proper transport code is loaded based on the scheme specified by the URL itself (http, jabber, etc.). Until this method is called the first time with a URL string, the underlying code has yet to be loaded, and the methods aren't available. When getting the current proxy (calling with no parameters), the returned value is a reference to the client object created from the protocol class that matched the endpoint, not the endpoint itself. 36 37=back 38 39=head1 SOAP Transport Sub-Classes 40 41Because the bulk of the work is done within the C<SOAP::Lite> module itself, many of the transport-level modules are very simple in their implementations. Transport modules are expected to define both client and server classes within their files. If a module defines only one of the types, it is assumed that the transport protocol itself supports only that side of the conversation. An example is L<SOAP::Transport::FTP>, which provides only a C<SOAP::Transport::FTP::Client> class. 42 43L</"SOAP::Transport::FTP"> - Client class only 44 45L</"SOAP::Transport::HTTP"> - Client, and server classes for CGI, FCGI, Daemon and mod_perl 46 47L</"SOAP::Transport::IO"> - Server class only 48 49L</"SOAP::Transport::JABBER"> - Server and Client classes 50 51L</"SOAP::Transport::LOCAL"> - Client class only 52 53L</"SOAP::Transport::MAILTO"> - Client class only 54 55L</"SOAP::Transport::MQ"> - Server and Client classes 56 57L</"SOAP::Transport::POP3"> - Server class only 58 59L</"SOAP::Transport::TCP"> - Server and Client classes 60 61=head2 METHODS 62 63Each SOAP::Transport sub-class is expected to define (or inherit, if it is subclassing another transport class) at least two methods. Any newly developed transport classes are also expected to adhere to this interface. Clients are expected to implement the C<new> and C<send_receive> methods, and servers are expected to implement the C<new> and C<handle> methods. Here they are: 64 65=over 66 67=item new(optional key/value pairs) 68 69 $object = $class->new(%params); 70 71Creates a new object instance and returns it. Like the constructors for both C<SOAP::Lite> and L<SOAP::Server> classes, all arguments passed in are treated as key/value pairs, where the key is expected to be one of the methods the class supports, and the value is the argument (or list reference of arguments) to the method. 72 73=item send_receive(key/value pairs) 74 75 $client->send_recieve(%hash_table); 76 77(Required for client classes only) When the SOAP::Lite objects attempt to send out requests, the means for doing so is to attempt to call this method on the object held within the SOAP::Transport object contained within the client itself. All clients are expected to provide this, and the call to this method always passes four values for the hash keys: 78 79=over 80 81=item action 82 83The URI specifying the action being performed, usually the result from the on_action hook on the client object. 84 85=item encoding 86 87The URI of the encoding scheme that governs the message being sent. 88 89=item endpoint 90 91The URI specifying the endpoint to which the message is being sent. 92 93=item envelope 94 95The XML content of the message to be sent. It is generally the return value of the envelope method from the L<SOAP::Serializer> object instance that the client object maintains. 96 97=item parts 98 99Attachments to add to the request. Currently this only supports an array of MIME::Entity objects, but in theory could support attachments of any format. 100 101=back 102 103=item handle 104 105 $server->handle; 106 107(Required for server classes only.) This method is the central point for the various server classes to provide an interface to handling requests. The exact set and nature of parameters generally varies based on the classes themselves. 108 109=back 110 111=head2 SOAP::Transport::FTP 112 113The SOAP::Transport::FTP module is automatically loaded by the SOAP::Transport portion of the client structure. It is brought in when an endpoint is specified via the proxy method that starts with the characters, ftp://. This module provides only a client class. 114 115=head3 SOAP::Transport::FTP::Client 116 117Inherits from: L<SOAP::Client>. 118 119Support is provided for clients to connect to FTP servers using SOAP. The methods defined within the class are just the basic new and send_receive. 120 121=head2 SOAP::Transport::HTTP 122 123The most commonly used transport module is the HTTP implementation. This is loaded whenever an endpoint is given that starts with the characters, http:// or https://. This is also the most involved of the transport modules, defining not only a client class but several different server classes as well. 124 125=head3 HTTP PROXY SETTINGS 126 127Because C<SOAP::Client> inherits from C<LWP::UserAgent>, you can use any of C<LWP::UserAgent>'s proxy settings. For example: 128 129 SOAP::Lite->proxy("http://endpoint.server/", 130 proxy => ["http" => "http://my.proxy.server"]); 131 132or 133 134 $soap->transport->proxy("http" => "http://my.proxy.server"); 135 136The above code samples should specify a proxy server for you. And should you use C<HTTP_proxy_user> 137and C<HTTP_proxy_pass> for proxy authorization, C<SOAP::Lite> will handle it properly. 138 139=head3 HTTP BASIC AUTHENTICATION 140 141HTTP Basic authentication is accomplished by overriding the get_basic_credentials suboutine in C<LWP::UserAgent> (which C<SOAP::Transport::HTTP::Client> is a subclass): 142 143 BEGIN { 144 sub SOAP::Transport::HTTP::Client::get_basic_credentials { 145 return 'username' => 'password'; 146 } 147 } 148 149=head3 COOKIE-BASED AUTHENTICATION 150 151 use HTTP::Cookies; 152 my $cookies = HTTP::Cookies->new(ignore_discard => 1); 153 # you may also add 'file' if you want to keep them between sessions 154 my $soap = SOAP::Lite->proxy('http://localhost/'); 155 $soap->transport->cookie_jar($cookies); 156 157Or, alternatively, you can do the above on a single line: 158 159 $soap->proxy('http://localhost/', 160 cookie_jar => HTTP::Cookies->new(ignore_discard => 1)); 161 162Cookies will be taken from the response and provided to the request. You may access and manipulate cookies received, as well as add cookies of your own by using the C<HTTP::Cookies> interfaces. 163 164=head3 SSL CERTIFICATE AUTHENTICATION 165 166To get certificate authentication working you need to set three environment variables: C<HTTPS_CERT_FILE>, C<HTTPS_KEY_FILE>, and optionally C<HTTPS_CERT_PASS>. This can be done either through the command line, or directly within your Perl script using the C<$ENV> variable: 167 168 $ENV{HTTPS_CERT_FILE} = 'client-cert.pem'; 169 $ENV{HTTPS_KEY_FILE} = 'client-key.pem'; 170 171These settings are referrenced by C<Crypt::SSLeay>, the module SOAP::Lite used for HTTPS support. Other options (e.g. CA peer verification) can be specified in a similar way. See L<Crypt::SSLeay> documentation for more information. 172 173Those who would like to use encrypted keys may find the following thread in the SOAP::Lite newsgroup helpful: 174 175http://groups.yahoo.com/group/soaplite/message/729 176 177=head3 COMPRESSION 178 179SOAP::Lite provides you with the option for enabling compression over the wire using HTTP I<only> in both the server and client contexts, provided that you have L<Compress::Zlib> installed. Compression and decompression is done transparantly to your application. 180 181A server will respond with an encoded/compressed message only if the client has asserted that it can accept it (indicated by client sending an C<Accept-Encoding> HTTP header with a 'deflate' or '*' value). 182 183C<SOAP::Lite> clients all have fallback logic implemented so that if a server doesn't understand the specified encoding (i.e. "Content-Encoding: deflate") and returns the proper HTTP status code (415 NOT ACCEPTABLE), the client will repeat the request without using encoding/compression. The client will then store this server in a per-session cache, so that all subsequent requests to that server will be transmitted without encoding. 184 185Compression is enabled on the client side by specifying the C<compress_threshold> option, and if the size of the current request exceeds that threshold. 186 187B<Client Code Sample> 188 189 print SOAP::Lite 190 ->uri('http://localhost/My/Parameters') 191 ->proxy('http://localhost/', options => {compress_threshold => 10000}) 192 ->echo(1 x 10000) 193 ->result; 194 195Servers will respond with a compressed message if the C<compress_threshold> option has been specified, if the size of the current response exceeds that threshold, and if the calling client transmitted the proper C<Accept-Encoding> HTTP Header. 196 197B<Server Code Sample> 198 199 my $server = SOAP::Transport::HTTP::CGI 200 ->dispatch_to('My::Parameters') 201 ->options({compress_threshold => 10000}) 202 ->handle; 203 204See also: L<Compress::Zlib> 205 206=head3 SOAP::Transport::HTTP::Client 207 208Inherits from: L<SOAP::Client>, L<LWP::UserAgent> (from the LWP package). 209 210With this class, clients are able to use HTTP for sending messages. This class provides just the basic new and send_receive methods. Objects of this class understand the compress_threshold option and use it if the server being communicated to also understands it. 211 212=head4 CHANGING THE DEFAULT USERAGENT CLASS 213 214By default, C<SOAP::Transport::HTTP::Client> extends C<LWP::UserAgent>. 215But under some circumstances, a user may wish to change the default 216UserAgent class with their in order to better handle persist connections, or 217to C<LWP::UserAgent::ProxyAny>, for example, which has better Win32/Internet 218Explorer interoperability. 219 220One can use the code below as an example of how to change the default UserAgent class. 221 222 use SOAP::Lite; 223 use SOAP::Transport::HTTP; 224 $SOAP::Transport::HTTP::Client::USERAGENT_CLASS = "My::UserAgent"; 225 my $client = SOAP::Lite->proxy(..)->uri(..); 226 my $som = $client->myMethod(); 227 228There is one caveat, however. The UserAgent class you use, I<MUST> also be a subclass of C<LWP::UserAgent>. If it is not, then C<SOAP::Lite> will issue the following error: "Could not load UserAgent class <USERAGENT CLASS>." 229 230=head4 HTTP-KEEP-ALIVE, TIMEOUTS, AND MORE 231 232Because C<SOAP::Transport::HTTP::Client> extends C<LWP::UserAgent>, all methods available C<LWP::UserAgent> are also available to your SOAP Clients. For example, using C<LWP::UserAgent> HTTP keep alive's are accomplished using the following code: 233 234 my $ua = LWP::UserAgent->new( 235 keep_alive => 1, 236 timeout => 30 237 ); 238 239Therefore, the same initialization parameters you would pass to C<LWP::UserAgent> can also be passed to your SOAP::Lite client's C<proxy> subroutine like so: 240 241 my $soap = SOAP::Lite 242 ->uri($uri) 243 ->proxy($proxyUrl, 244 timeout => 30, 245 keep_alive => 1, 246 ); 247 248This is true for all initialization parameters and methods of C<LWP::UserAgent>. 249 250=head4 METHODS 251 252=over 253 254=item http_request 255 256This method gives you acess to the HTTP Request object that will be, or was transmitted to a SOAP Server. It returns a L<HTTP::Request> object. 257 258=item http_response 259 260This method gives you acess to the HTTP Response object that will be, or was transmitted to a SOAP Server. It returns a L<HTTP::Response> object. 261 262=back 263 264=head3 SOAP::Transport::HTTP::Server 265 266Inherits from: L<SOAP::Server>. 267 268This is the most basic of the HTTP server implementations. It provides the basic methods, new and handle. The handle method's behavior is defined here, along with other methods specific to this class. The role of this class is primarily to act as a superclass for the other HTTP-based server classes. 269 270=over 271 272=item handle 273 274 $server->handle; 275 276Expects the request method to have been used to associate a HTTP::Request object with the server object prior to being called. This method retrieves that object reference to get at the request being handled. 277 278=item request(I<optional value>) 279 280 $server->request($req_object) 281 282Gets or sets the HTTP::Request object reference that the server will process within the handle method. 283 284=item response(I<optional value>) 285 286 $server->response(HTTP::Response->new(...)); 287 288Gets or sets the HTTP::Response object reference that the server has prepared for sending back to the client. 289 290=item make_response(I<code>, I<body>) 291 292 $server->make_response(200, $body_xml); 293 294Constructs and returns an object of the HTTP::Response class, using the response code and content provided. 295 296=item make_fault(I<fault arguments>) 297 298 $server->response($server->make_fault(@data)); 299 300Creates a HTTP::Response object reference using a predefined HTTP response code to signify that a fault has occurred. The arguments are the same as those for the make_fault method of the SOAP::Server class. 301 302=item product_tokens 303 304This method takes no arguments and simply returns a string identifying the elements of the server class itself. It is similar to the product_tokens methods in the HTTP::Daemon and Apache classes. 305 306=back 307 308=head3 SOAP::Transport::HTTP::CGI 309 310Inherits from: L<SOAP::Transport::HTTP::Server>. 311 312This class is a direct subclass of SOAP::Transport::HTTP::Server and defines no additional methods. It includes logic in its implementation of the handle method that deals with the request headers and parameters specific to a CGI environment. 313 314=head4 EXAMPLE CGI 315 316The following code sample is a CGI based Web Service that converts celcius to fahrenheit: 317 318 #!/usr/bin/perl 319 use SOAP::Transport::HTTP; 320 SOAP::Transport::HTTP::CGI 321 ->dispatch_to('C2FService') 322 ->handle; 323 BEGIN { 324 package C2FService; 325 use vars qw(@ISA); 326 @ISA = qw(Exporter SOAP::Server::Parameters); 327 use SOAP::Lite; 328 sub c2f { 329 my $self = shift; 330 my $envelope = pop; 331 my $temp = $envelope->dataof("//c2f/temperature"); 332 return SOAP::Data->name('convertedTemp' => (((9/5)*($temp->value)) + 32)); 333 } 334 } 335 336=head4 EXAMPLE APACHE::REGISTRY USAGE 337 338Using a strictly CGI based Web Service has certain performance drawbacks. Running the same CGI under the Apache::Registery system has certain performance gains. 339 340B<httpd.conf> 341 342 Alias /mod_perl/ "/Your/Path/To/Deployed/Modules" 343 <Location /mod_perl> 344 SetHandler perl-script 345 PerlHandler Apache::Registry 346 PerlSendHeader On 347 Options +ExecCGI 348 </Location> 349 350B<soap.cgi> 351 352 use SOAP::Transport::HTTP; 353 354 SOAP::Transport::HTTP::CGI 355 ->dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method') 356 ->handle; 357 358I<WARNING: Dynamic deployments with C<Apache::Registry> will fail because the module will be only loaded dynamically the first time. Subsequent calls will produce "denied access" errors because once the module is already in memory C<SOAP::Lite> will bypass dynamic deployment. To work around this, simply specify both the full PATH and MODULE name in C<dispatch_to()> and the module will be loaded dynamically, but will then work as if under static deployment. See F<examples/server/soap.mod_cgi> as an example.> 359 360=head3 SOAP::Transport::HTTP::Daemon 361 362Inherits from: L<SOAP::Transport::HTTP::Server>. 363 364The SOAP::Transport::HTTP::Daemon class encapsulates a reference to an object of the HTTP::Daemon class (from the LWP package). The class catches methods that aren't provided locally or by the superclass and attempts to call them on the HTTP::Daemon object. Thus, all methods defined in the documentation for that class are available to this class as well. Any that conflict with methods in SOAP::Transport::HTTP::Server (such as product_tokens) go to the superclass. Additionally, the behavior of the handle method is specific to this class: 365 366=over 367 368=item handle 369 370When invoked, this method enters into the typical accept loop in which it waits for a request on the socket that the daemon object maintains and deals with the content of the request. When all requests from the connection returned by the accept method of the HTTP::Daemon object have been processed, this method returns. 371 372=back 373 374=head4 REUSING SOCKETS ON RESTART 375 376Often when implementing an HTTP daemon, sockets will get tied up when you try to restart the daemon server. This prevents the server from restarting. Often users will see an error like "Cannot start server: port already in use." To circumvent this, instruct SOAP::Lite to reuse open sockets using C<< Reuse => 1 >>: 377 378 my $daemon = SOAP::Transport::HTTP::Daemon 379 -> new (LocalPort => 80000, Reuse => 1) 380 381=head4 EXAMPLE DAEMON SERVER 382 383 use SOAP::Transport::HTTP; 384 # change LocalPort to 81 if you want to test it with soapmark.pl 385 my $daemon = SOAP::Transport::HTTP::Daemon 386 -> new (LocalAddr => 'localhost', LocalPort => 80) 387 # specify list of objects-by-reference here 388 -> objects_by_reference(qw(My::PersistentIterator My::SessionIterator My::Chat)) 389 # specify path to My/Examples.pm here 390 -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method') 391 ; 392 print "Contact to SOAP server at ", $daemon->url, "\n"; 393 $daemon->handle; 394 395=head3 SOAP::Transport::HTTP::Apache 396 397Inherits from: L<SOAP::Transport::HTTP::Server>. 398 399This class provides an integration of the SOAP::Server base class with the mod_perl extension for Apache. To work as a location handler, the package provides a method called handler, for which handle is made an alias. The new method isn't functionally different from the superclass. Here are the other methods provided by this class: 400 401=over 402 403=item handler(I<Apache request>) 404 405 $server->handler($r) 406 407Defines the basis for a location handler in the mod_perl fashion. The method expects an Apache request object as the parameter, from which it pulls the body of the request and calls the superclass handle method. 408 409Note that in this class, the local method named handle is aliased to this method. 410 411=item configure(I<Apache request>) 412 413 $server->configure(Apache->request); 414 415Per-location configuration information can be provided to the server object using the Apache DirConfig directive and calling this method on the object itself. When invoked, the method reads the directory configuration information from Apache and looks for lines of the form: 416 417 method => param 418 419Each line that matches the pattern is regarded as a potential method to call on the server object, with the remaining token taken as the parameter to the method. Methods that take hash references as arguments may be specified as: 420 421 method => key => param, key => param 422 423The key/value pairs will be made into a hash reference on demand. If the server object doesn't recognize the named method as valid, it ignores the line. 424 425=back 426 427=head4 EXAMPLE APACHE MOD_PERL SERVER 428 429See F<examples/server/Apache.pm> and L<Apache::SOAP> for more information. 430 431B<httpd.conf> 432 433 <Location /soap> 434 SetHandler perl-script 435 PerlHandler SOAP::Apache 436 PerlSetVar options "compress_threshold => 10000" 437 </Location> 438 439B<SOAP::Apache.pm> 440 441 package SOAP::Apache; 442 use SOAP::Transport::HTTP; 443 my $server = SOAP::Transport::HTTP::Apache 444 ->dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method'); 445 sub handler { $server->handler(@_) } 446 1; 447 448See also L<Apache::SOAP>. 449 450=head3 SOAP::Transport::HTTP::FCGI 451 452Inherits from: L<SOAP::Transport::HTTP::CGI>. 453 454This is an extension of the SOAP::Transport::HTTP::CGI that implements the differences needed for the FastCGI protocol. None of the methods are functionally different. 455 456=head2 SOAP::Transport::IO 457 458The SOAP::Transport::IO-based class allows for a sort of I/O proxying by allowing the application to configure what files or filehandles are used. This module supplies only a server class. 459 460=head3 SOAP::Transport::IO::Server 461 462Inherits from: L<SOAP::Server>. 463 464The server class defined here inherits all methods from SOAP::Server, and adds two additional methods specific to the nature of the class: 465 466=over 467 468=item in 469 470 $server->in(IO::File->new($file)); 471 472Gets or sets the current filehandle being used as the input source. 473 474=item out 475 476 $server->out(\*STDERR); 477 478Gets or sets the filehandle being used as the output destination. 479 480=back 481 482=head2 SOAP::Transport::JABBER 483 484This class uses the Net::Jabber classes to abstract the Jabber protocol away from the direct notice of the application. Besides maintaining any needed objects internally, the package also uses a separate class as a proxy between communication layers, SOAP::Transport::JABBER::Query. The Jabber support provides both client and server classes. 485 486=head3 SOAP::Transport::JABBER::Client 487 488Inherits from: L<SOAP::Client>, L<Net::Jabber::Client>. 489This class provides localized implementations for both the new and send_receive methods, neither of which are changed in terms of interface. The only difference is that the send_receive method doesn't directly use the action hash key on the input it receives. In addition to these two basic methods, the server class overrides the endpoint 490method it would otherwise inherit from SOAP::Client: 491 492=over 493 494=item endpoint 495 496In the general sense, this still acts as a basic accessor method, with the same get value/set value behavior used consistently through the SOAP::Lite module. The difference between this version and most others is that when the endpoint is initially set or is changed, the client object makes the connection to the Jabber endpoint, sending the proper authentication credentials and setting up the conversation mechanism using the SOAP::Transport::JABBER::Query class as a delegate. It then calls the superclass endpoint method to ensure that all other related elements are taken care of. 497 498=back 499 500=head3 SOAP::Transport::JABBER::Server 501 502Inherits from: L<SOAP::Server>. 503 504The server class provided for Jabber support defines a slightly different interface to the constructor. The server manages the Jabber communication by means of an internal Net::Jabber::Client instance. In a fashion similar to that used by SOAP::Transport::HTTP::Daemon, the server class catches methods that are meant for the Jabber client and treats them as if the class inherits directly from that class, without actually doing so. In doing so, the handle method is implemented as a frontend to the Process method of the Jabber client class. The difference in the interface to the constructor is: 505 506=over 507 508=item new(I<URI>, I<optional server key/value options>) 509 510 $srv = SOAP::Transport::JABBER::Server-> new($uri); 511 512The constructor for the class expects that the first argument will be a Jabber-style URI, followed by the standard set of optional key/value pairs of method names and their parameters. All the method/parameter 513pairs are delegated to the superclass constructor; only the Jabber URI is handled locally. It's used to set up the Net::Jabber::Client instance that manages the actual communications. 514 515=back 516 517=head2 SOAP::Transport::LOCAL 518 519The SOAP::Transport::LOCAL module is designed to provide a no-transport client class for tracing and debugging communications traffic. It links SOAP::Client and SOAP::Server so that the same object that "sends" the request also "receives" it. 520 521=head3 SOAP::Transport::LOCAL::Client 522 523Inherits from: L<SOAP::Client>, L<SOAP::Server>. 524The implementations of the new and send_receive methods aren't noticeably different in their interface. Their behavior warrants description, however: 525 526=over 527 528=item new 529 530When the constructor creates a new object of this class, it sets up a few things beyond the usual SOAP::Client layout. The is_success method is set to a default value of 1. The dispatch_to method inherited from SOAP::Server is called with the current value of the global array @INC, allowing the client to call any methods that can be found in the current valid search path. And as with most of the constructors in this module, the optional key/value pairs are treated as method names and parameters. 531 532=item send_receive 533 534The implementation of this method simply passes the envelope portion of the input data to the handle method of SOAP::Server. While no network traffic results (directly) from this, it allows for debug signals to be sent through the SOAP::Trace facility. 535 536=back 537 538=head2 SOAP::Transport::MAILTO 539 540This transport class manages SMTP-based sending of messages from a client perspective. It doesn't provide a server class. The class gets selected when a client object passes a URI to proxy or endpoint that starts with the characters, mailto:. 541 542=head3 SOAP::Transport::MAILTO::Client 543 544Inherits from: L<SOAP::Client>. 545 546The client class for this protocol doesn't define any new methods. The constructor functions in the same style as the others class constructors. The functionality of the send_receive method is slightly different from other classes, however. 547 548When invoked, the send_receive method uses the MIME::Lite package to encapsulate and transmit the message. Because mail messages are one-way communications (the reply being a separate process), there is no response message to be returned by the method. Instead, all the status-related attributes (code, message, status, is_success) are set, and no value is explicitly returned. 549 550=head2 SOAP::Transport::MQ 551 552This class provides implementations of both client and server frameworks built on IBM's Message Queue set of classes. The SOAP objects encapsulate additional objects from these classes, creating and using them behind the scenes as needed. 553 554=head3 SOAP::Transport::MQ::Client 555 556Inherits from: L<SOAP::Client>. 557 558The client class provides two methods specific to it, as well as specialized versions of the endpoint and send_receive methods. It also provides a localized new method, but the interface isn't changed from the superclass method. The new methods are: 559 560=over 561 562=item requestqueue 563 564 $client->requestqueue->Put(message => $request); 565 566Manages the MQSeries::Queue object the client uses for enqueuing requests to the server. In general, an application shouldn't need to directly access this attribute, let alone set it. If setting it, the new value should be an object of (or derived from) the MQSeries::Queue class. 567 568=item replyqueue 569 570 $client->replyqueue(MQSeries::Queue->new(%args)); 571 572Manages the queue object used for receiving messages back from the designated server (endpoint). It is also primarily for internal use, though if the application needs to set it explicitly, the new value should be an object of (or derived from) the MQSeries::Queue class. 573 574=back 575 576The two previous methods are mainly used by the localized versions of the methods: 577 578=over 579 580=item endpoint 581 582This accessor method has the same interface as other similar classes but is worth noting for the internal actions that take place. When the endpoint is set or changed, the method creates a queue-manager object (from the MQSeries::QueueManager class) and references this object when creating queues for replies and requests using the methods described earlier. The URI structure used with these classes (strings beginning with the characters mq://user@host:port) contains the information needed for these operations. 583 584=item send_receive 585 586This method uses the same interface as other classes, but makes use of only the endpoint and envelope keys in the hash-table input data. The endpoint key is needed only if the client wishes to switch endpoints prior to sending the message. The message (the value of the envelope key) is inserted into the queue stored in the requestqueue attribute. The client then waits for a reply to the message to appear in the queue stored in the replyqueue attribute. 587 588=back 589 590=head3 SOAP::Transport::MQ::Server 591 592Inherits from: L<SOAP::Server>. 593 594The server class also defines requestqueue and replyqueue methods under the same terms as the client class. Of course, the server reads from the request queue and writes to the reply queue, the opposite of the client's behavior. 595The methods whose functionality are worth noting are: 596 597=over 598 599=item new(URI, optional parameters) 600 601When called, the constructor creates the MQSeries::QueueManager object and the two MQSeries::Queue objects, similar to what the client does inside its endpoint method. Like the Jabber server described earlier, the first argument to this constructor is expected to be the URI that describes the server itself. The remainder of the arguments are treated as key/value pairs, as with other class constructors previously described. 602 603=item handle 604 605When this method is called, it attempts to read a pending message from the request-queue stored on the requestqueue attribute. The message itself is passed to the handle method of the superclass, and the result from that operation is enqueued to the replyqueue object. This process loops until no more messages are present in the request queue. The return value is the number of messages processed. The reads from the request queue are done in a nonblocking fashion, so if there is no message pending, the method immediately returns with a value of zero. 606 607=back 608 609=head2 SOAP::Transport::POP3 610 611POP3 support is limited to a server implementation. Just as the MAILTO class detailed earlier operates by sending requests without expecting to process a response, the server described here accepts request messages and dispatches them without regard for sending a response other than that which POP3 defines for successful delivery of a message. 612 613=head3 SOAP::Transport::POP3::Server 614 615Inherits from: L<SOAP::Server>. 616 617The new method of this class creates an object of the Net::POP3 class to use internally for polling a specified POP3 server for incoming messages. When an object of this class is created, it expects an endpoint to be specified with a URI that begins with the characters pop:// and includes user ID and password information as well as the hostname itself. 618 619The handle method takes the messages present in the remote mailbox and passes them (one at a time) to the superclass handle method. Each message is deleted after being routed. All messages in the POP3 mailbox are presumed to be SOAP messages. 620 621Methods for the Net::POP3 object are detected and properly routed, allowing operations such as $server->ping( ). 622 623This means that the endpoint string doesn't need to provide the user ID and password because the login method from the POP3 API may be used directly. 624 625=head2 SOAP::Transport::TCP 626 627The classes provided by this module implement direct TCP/IP communications methods for both clients and servers. 628 629The connections don't use HTTP or any other higher-level protocol. These classes are selected when the client or server object being created uses an endpoint URI that starts with tcp://. Both client and server classes support using Secure Socket Layer if it is available. If any of the parameters to a new method from either of the classes begins with SSL_ (such as SSL_server in place of Server), the class attempts to load the IO::Socket::SSL package and use it to create socket objects. 630 631Both of the following classes catch methods that are intended for the socket objects and pass them along, allowing calls such as $client->accept( ) without including the socket class in the inheritance tree. 632 633=head3 SOAP::Transport::TCP::Client 634 635Inherits from: L<SOAP::Client>. 636 637The TCP client class defines only two relevant methods beyond new and send_receive. These methods are: 638 639=over 640 641=item SSL(I<optional new boolean value>) 642 643 if ($client->SSL) # Execute only if in SSL mode 644 645Reflects the attribute that denotes whether the client object is using SSL sockets for communications. 646 647=item io_socket_class 648 649 ($client->io_socket_class)->new(%options); 650 651Returns the name of the class to use when creating socket objects for internal use in communications. As implemented, it returns one of IO::Socket::INET or IO::Socket::SSL, depending on the return value of the previous SSL method. 652 653=back 654 655If an application creates a subclass that inherits from this client class, either method is a likely target for overloading. 656 657The new method behaves identically to most other classes, except that it detects the presence of SSL-targeted values in the parameter list and sets the SSL method appropriately if they are present. 658 659The send_receive method creates a socket of the appropriate class and connects to the configured endpoint. It then sets the socket to nonblocking I/O, sends the message, shuts down the client end of the connection (preventing further writing), and reads the response back from the server. The socket object is discarded after the response and 660appropriate status codes are set on the client object. 661 662=head3 SOAP::Transport::TCP::Server 663 664Inherits from: L<SOAP::Server>. 665 666The server class also defines the same two additional methods as in the client class: 667 668=over 669 670=item SSL(I<optional new boolean value>) 671 672 if ($client->SSL) # Execute only if in SSL mode 673 674Reflects the attribute that denotes whether the client object is using SSL sockets for communications. 675 676=item io_socket_class 677 678 ($client->io_socket_class)->new(%options); 679 680Returns the name of the class to use when creating socket objects for internal use in communications. As implemented, it returns one of IO::Socket::INET or IO::Socket::SSL, depending on the return value of the previous SSL method. The new method also manages the automatic selection of SSL in the same fashion as the client class does. 681 682The handle method in this server implementation isn't designed to be called once with each new request. Rather, it is called with no arguments, at which time it enters into an infinite loop of waiting for a connection, reading the request, routing the request and sending back the serialized response. This continues until the process itself is interrupted by an untrapped signal or similar means. 683 684=back 685 686=head1 ACKNOWLEDGEMENTS 687 688Special thanks to O'Reilly publishing which has graciously allowed SOAP::Lite to republish and redistribute large excerpts from I<Programming Web Services with Perl>, mainly the SOAP::Lite reference found in Appendix B. 689 690=head1 COPYRIGHT 691 692Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved. 693 694This library is free software; you can redistribute it and/or modify 695it under the same terms as Perl itself. 696 697=head1 AUTHORS 698 699Paul Kulchenko (paulclinger@yahoo.com) 700 701Randy J. Ray (rjray@blackperl.com) 702 703Byrne Reese (byrne@majordojo.com) 704 705=cut 706