SOAP::Transport::HTTP - Server/Client side HTTP support for SOAP::Lite
use SOAP::Lite uri => 'http://my.own.site.com/My/Examples', proxy => 'http://localhost/', # proxy => 'http://localhost/cgi-bin/soap.cgi', # local CGI server # proxy => 'http://localhost/', # local daemon server # proxy => 'http://localhost/soap', # local mod_perl server # proxy => 'https://localhost/soap', # local mod_perl SECURE server # proxy => 'http://login:password@localhost/cgi-bin/soap.cgi', # local CGI server with authentication ; print getStateName(1);
use SOAP::Transport::HTTP; SOAP::Transport::HTTP::CGI # specify path to My/Examples.pm here -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method') -> handle ;
use SOAP::Transport::HTTP; # change LocalPort to 81 if you want to test it with soapmark.pl my $daemon = SOAP::Transport::HTTP::Daemon -> new (LocalAddr => 'localhost', LocalPort => 80) # specify list of objects-by-reference here -> objects_by_reference(qw(My::PersistentIterator My::SessionIterator My::Chat)) # specify path to My/Examples.pm here -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method') ; print "Contact to SOAP server at ", $daemon->url, "\n"; $daemon->handle;
See examples/server/Apache.pm and "EXAMPLES" section for more information.
SetHandler perl-script PerlHandler Apache::SOAP PerlSetVar dispatch_to "/Your/Path/To/Deployed/Modules, Module::Name, Module::method" PerlSetVar options "compress_threshold => 10000"
See Apache::SOAP for more information.
This class encapsulates all HTTP related logic for a SOAP server, independent of what web server it's attached to. If you want to use this class you should follow simple guideline mentioned above.
Following methods are available:
on_action method lets you specify SOAPAction understanding. It accepts reference to subroutine that takes three parameters:
SOAPAction, method_uri and method_name.
SOAPAction is taken from HTTP header and method_uri and method_name are extracted from request's body. Default behavior is match SOAPAction if present and ignore it otherwise. You can specify you own, for example die if SOAPAction doesn't match with following code:
SOAPAction
$server->on_action(sub { (my $action = shift) =~ s/^("?)(.+)\1$/$2/; die "SOAPAction shall match 'uri#method'\n" if $action ne join '#', @_; });
dispatch_to lets you specify where you want to dispatch your services to. More precisely, you can specify PATH, MODULE, method or combination MODULE::method. Example:
PATH
MODULE
method
MODULE::method
dispatch_to( 'PATH/', # dynamic: load anything from there, any module, any method 'MODULE', # static: any method from this module 'MODULE::method', # static: specified method from this module 'method', # static: specified method from main:: );
If you specify PATH/ name of module/classes will be taken from uri as path component and converted to Perl module name with substitution '::' for '/'. Example:
PATH/
urn:My/Examples => My::Examples urn://localhost/My/Examples => My::Examples http://localhost/My/Examples => My::Examples
For consistency first '/' in the path will be ignored.
According to this scheme to deploy new class you should put this class in one of the specified directories and enjoy its services. Easy, eh?
handle method will handle your request. You should provide parameters with request() method, call handle() and get it back with response() .
request method gives you access to HTTP::Request object which you can provide for Server component to handle request.
response method gives you access to HTTP::Response object which you can access to get results from Server component after request was handled.
You can use any proxy setting you use with LWP::UserAgent modules:
SOAP::Lite->proxy('http://endpoint.server/', proxy => ['http' => 'http://my.proxy.server']);
or
$soap->transport->proxy('http' => 'http://my.proxy.server');
should specify proxy server for you. And if you use HTTP_proxy_user and HTTP_proxy_pass for proxy authorization SOAP::Lite should know how to handle it properly.
HTTP_proxy_user
HTTP_proxy_pass
use HTTP::Cookies; my $cookies = HTTP::Cookies->new(ignore_discard => 1); # you may also add 'file' if you want to keep them between sessions my $soap = SOAP::Lite->proxy('http://localhost/'); $soap->transport->cookie_jar($cookies);
Cookies will be taken from response and provided for request. You may always add another cookie (or extract what you need after response) with HTTP::Cookies interface.
You may also do it in one line:
$soap->proxy('http://localhost/', cookie_jar => HTTP::Cookies->new(ignore_discard => 1));
SOAP::Lite provides you option for enabling compression on wire (for HTTP transport only). Both server and client should support this capability, but this logic should be absolutely transparent for your application. Server will respond with encoded message only if client can accept it (client sends Accept-Encoding with 'deflate' or '*' values) and client has fallback logic, so if server doesn't understand specified encoding (Content-Encoding: deflate) and returns proper error code (415 NOT ACCEPTABLE) client will repeat the same request not encoded and will store this server in per-session cache, so all other requests will go there without encoding.
Having options on client and server side that let you specify threshold for compression you can safely enable this feature on both client and server side.
print SOAP::Lite -> uri('http://localhost/My/Parameters') -> proxy('http://localhost/', options => {compress_threshold => 10000}) -> echo(1 x 10000) -> result ;
my $server = SOAP::Transport::HTTP::CGI -> dispatch_to('My::Parameters') -> options({compress_threshold => 10000}) -> handle;
Compression will be enabled on client side IF: threshold is specified AND size of current message is bigger than threshold AND module Compress::Zlib is available. Client will send header 'Accept-Encoding' with value 'deflate' if threshold is specified AND module Compress::Zlib is available.
Server will accept compressed message if module Compress::Zlib is available, and will respond with compressed message ONLY IF: threshold is specified AND size of current message is bigger than threshold AND module Compress::Zlib is available AND header 'Accept-Encoding' is presented in request.
Consider following examples of SOAP servers:
use SOAP::Transport::HTTP; SOAP::Transport::HTTP::CGI -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method') -> handle ;
use SOAP::Transport::HTTP; my $daemon = SOAP::Transport::HTTP::Daemon -> new (LocalAddr => 'localhost', LocalPort => 80) -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method') ; print "Contact to SOAP server at ", $daemon->url, "\n"; $daemon->handle;
httpd.conf:
<Location /soap> SetHandler perl-script PerlHandler SOAP::Apache </Location>
Apache.pm:
package SOAP::Apache; use SOAP::Transport::HTTP; my $server = SOAP::Transport::HTTP::Apache -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method'); sub handler { $server->handler(@_) } 1;
Alias /mod_perl/ "/Apache/mod_perl/" <Location /mod_perl> SetHandler perl-script PerlHandler Apache::Registry PerlSendHeader On Options +ExecCGI </Location>
soap.mod_cgi (put it in /Apache/mod_perl/ directory mentioned above)
WARNING: dynamic deployment with Apache::Registry will fail, because module will be loaded dynamically only for the first time. After that it is already in the memory, that will bypass dynamic deployment and produces error about denied access. Specify both PATH/ and MODULE name in dispatch_to() and module will be loaded dynamically and then will work as under static deployment. See examples/server/soap.mod_cgi for example.
If you see in webserver's log file something like this:
Can't load '/usr/local/lib/perl5/site_perl/.../XML/Parser/Expat/Expat.so' for module XML::Parser::Expat: dynamic linker: /usr/local/bin/perl: libexpat.so.0 is NEEDED, but object does not exist at /usr/local/lib/perl5/.../DynaLoader.pm line 200.
and you are using Apache web server, try to put into your httpd.conf
<IfModule mod_env.c> PassEnv LD_LIBRARY_PATH </IfModule>
If using SOAP::Lite (or XML::Parser::Expat) in combination with mod_perl causes random segmentation faults in httpd processes try to configure Apache with:
RULE_EXPAT=no
See http://archive.covalent.net/modperl/2000/04/0185.xml for more details and lot of thanks to Robert Barta (rho@bigpond.net.au) for explaining this weird behavior.
CGI scripts may not work under IIS unless scripts are .pl, not .cgi.
Crypt::SSLeay for HTTPS/SSL SOAP::Lite, URI for SOAP::Transport::HTTP::Server LWP::UserAgent, URI for SOAP::Transport::HTTP::Client HTTP::Daemon for SOAP::Transport::HTTP::Daemon Apache, Apache::Constants for SOAP::Transport::HTTP::Apache
See ::CGI, ::Daemon and ::Apache for implementation details. See examples/server/soap.cgi as SOAP::Transport::HTTP::CGI example. See examples/server/soap.daemon as SOAP::Transport::HTTP::Daemon example. See examples/My/Apache.pm as SOAP::Transport::HTTP::Apache example.
Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Paul Kulchenko (paulclinger@yahoo.com)
To install SOAP::Lite, copy and paste the appropriate command in to your terminal.
cpanm
cpanm SOAP::Lite
CPAN shell
perl -MCPAN -e shell install SOAP::Lite
For more information on module installation, please visit the detailed CPAN module installation guide.