On Apache/2.0.61 (Unix) PHP/4.4.7 mod_ssl/2.0.61 OpenSSL/0.9.7e mod_fastcgi/2.4.2 DAV/2 SVN/1.4.2
Under GNU General Public License
2009-01-06 15:24 @38.103.63.57 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)
OldDocs::SOAP::Transport::HTTP(User Contributed Perl DocumentaOldDocs::SOAP::Transport::HTTP(3pm)
NAME
SOAP::Transport::HTTP - Server/Client side HTTP support for SOAP::Lite
SYNOPSIS
Client
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);
CGI server
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
;
Daemon server
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;
Apache mod_perl server
See examples/server/Apache.pm and "EXAMPLES" section for more information.
mod_soap server (.htaccess, directory-based access)
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.
DESCRIPTION
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()
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:
$server->on_action(sub {
(my $action = shift) =~ s/^("?)(.+)\1$/$2/;
die "SOAPAction shall match 'uri#method'\n" if $action ne join '#', @_;
});
dispatch_to()
dispatch_to lets you specify where you want to dispatch your services to. More pre-
cisely, you can specify "PATH", "MODULE", "method" or combination "MODULE::method".
Example:
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:
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()
handle method will handle your request. You should provide parameters with request()
method, call handle() and get it back with response() .
request()
request method gives you access to HTTP::Request object which you can provide for
Server component to handle request.
response()
response method gives you access to HTTP::Response object which you can access to get
results from Server component after request was handled.
PROXY SETTINGS
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 prop-
erly.
COOKIE-BASED AUTHENTICATION
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));
SSL CERTIFICATE AUTHENTICATION
To get certificate authentication working you need to specify three environment variables:
"HTTPS_CERT_FILE", "HTTPS_KEY_FILE", and (optionally) "HTTPS_CERT_PASS":
$ENV{HTTPS_CERT_FILE} = 'client-cert.pem';
$ENV{HTTPS_KEY_FILE} = 'client-key.pem';
Crypt::SSLeay (which is used for https support) will take care about everything else.
Other options (like CA peer verification) can be specified in a similar way. See
Crypt::SSLeay documentation for more details.
Those who would like to use encrypted keys may check
http://groups.yahoo.com/group/soaplite/message/729 for details.
COMPRESSION
SOAP::Lite provides you with the option for enabling compression on the wire (for HTTP
transport only). Both server and client should support this capability, but this should be
absolutely transparent to your application. The Server will respond with an encoded mes-
sage only if the client can accept it (indicated by client sending an Accept-Encoding
header 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 without encoding and will store
this server in a 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.
Client
print SOAP::Lite
-> uri('http://localhost/My/Parameters')
-> proxy('http://localhost/', options => {compress_threshold => 10000})
-> echo(1 x 10000)
-> result
;
Server
my $server = SOAP::Transport::HTTP::CGI
-> dispatch_to('My::Parameters')
-> options({compress_threshold => 10000})
-> handle;
Compression will be enabled on the client side if the threshold is specified and the size
of current message is bigger than the threshold and the module Compress::Zlib is avail-
able.
The Client will send the header 'Accept-Encoding' with value 'deflate' if the threshold is
specified and the module Compress::Zlib is available.
Server will accept the compressed message if the module Compress::Zlib is available, and
will respond with the compressed message only if the threshold is specified and the size
of the current message is bigger than the threshold and the module Compress::Zlib is
available and the header 'Accept-Encoding' is presented in the request.
EXAMPLES
Consider following examples of SOAP servers:
CGI:
use SOAP::Transport::HTTP;
SOAP::Transport::HTTP::CGI
-> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method')
-> handle
;
daemon:
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;
mod_perl:
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;
Apache::Registry:
httpd.conf:
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)
use SOAP::Transport::HTTP;
SOAP::Transport::HTTP::CGI
-> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method')
-> handle
;
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.
TROUBLESHOOTING
Dynamic libraries are not found
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>
Apache is crashing with segfaults (it may looks like "500 unexpected EOF before status
line seen" on client side)
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
-- OR (for Apache 1.3.20 and later) --
./configure --disable-rule=EXPAT
See http://archive.covalent.net/modperl/2000/04/0185.xml for more details and lot of
thanks to Robert Barta <rho AT bigpond.au> for explaining this weird behavior.
If it doesn't help, you may also try -Uusemymalloc (or something like that) to get
perl to use the system's own malloc. Thanks to Tim Bunce <Tim.Bunce AT pobox.com>.
CGI scripts are not running under Microsoft Internet Information Server (IIS)
CGI scripts may not work under IIS unless scripts are .pl, not .cgi.
DEPENDENCIES
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 ALSO
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
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.
AUTHOR
Paul Kulchenko (paulclinger AT yahoo.com)
perl v5.8.4 2004-10-26 OldDocs::SOAP::Transport::HTTP(3pm)
Generated by $Id: phpMan.php,v 4.49 2006/02/26 13:18:18 chedong Exp $ Author: Che Dong
On Apache/2.0.61 (Unix) PHP/4.4.7 mod_ssl/2.0.61 OpenSSL/0.9.7e mod_fastcgi/2.4.2 DAV/2 SVN/1.4.2
Under GNU General Public License
2009-01-06 15:24 @38.103.63.57 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)