soap::transport::http(3)

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/cgibin/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,
"0;
      $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 under
standing. 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 follow
ing code:

$server->on_action(sub {
(my $action = shift) =~ s/^("?)(.+)1$/$2/;
die "SOAPAction shall match 'uri#method'0 if $ac

tion ne join '#', @_;

});; dispatch_to()
dispatch_to lets you specify where you want to dis
patch your services to. More precisely, you can spec
ify "PATH", "MODULE", "method" or combination "MOD
ULE::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 directo
ries and enjoy its services. Easy, eh?; handle()
handle method will handle your request. You should
provide parameters with request() method, call han_ dle() 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.serv; er');
should specify proxy server for you. And if you use "HTTP_proxy_user" and "HTTP_proxy_pass" for proxy autho rization SOAP::Lite should know how to handle it properly.
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 be

tween 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 inter face.
You may also do it in one line:: $soap->proxy('http://localhost/',
cookie_jar => HTTP::Cookies->new(ig

nore_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 com pression 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 message 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 => {com

press_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
available.
The Client will send the header 'Accept-Encoding' with
value 'deflate' if the threshold is specified and the mod
ule 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 thresh
old 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,; "0;
$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 exam
ples/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/Ex; pat/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 combi
nation 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/mod
perl/2000/04/0185.xml for more details and lot of
thanks to Robert Barta <rho@bigpond.net.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@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::Trans
port::HTTP::Server LWP::UserAgent, URI for SOAP::Trans
port::HTTP::Client HTTP::Daemon for SOAP::Transport::HTTP::Dae
mon Apache, Apache::Constants for SOAP::Trans
port::HTTP::Apache

COPYRIGHT

This library is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.

AUTHOR

Paul Kulchenko (paulclinger@yahoo.com)

docs.sk

komplexný repozitár dokumentácie

Najnavštevovanejšie