NAME

SOAP::Transport::HTTP - Server/Client side HTTP support for SOAP::Lite for Perl

SYNOPSIS

use SOAP::Transport::HTTP;            
my $server = SOAP::Transport::HTTP::Server->new; # create new server
# set path for deployed modules (see explanation below)
$server->dispatch_to('/Path/To/Deployed/Modules');
$server->request(new HTTP::Request); # set request object  HTTP::Request
$server->handle($content);           # handle request
$server->response;                   # get response object HTTP::Response

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 precisely, 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 peoxy authorization SOAP::Lite should know what to do with it. If not, let me know.

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.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
;

TROUBLESHOOTING

If you'll see something like this in your webserver's log file: 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 add to your httpd.conf

<IfModule mod_env.c>
    PassEnv LD_LIBRARY_PATH
</IfModule>

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/soap.cgi as SOAP::Transport::HTTP::CGI example.
See examples/soap.daemon as SOAP::Transport::HTTP::Daemon example.
See examples/My/Apache.pm as SOAP::Transport::HTTP::Apache example.

COPYRIGHT

Copyright (C) 2000 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@yahoo.com)