.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "OldDocs::SOAP::Transport::HTTP 3"
.TH OldDocs::SOAP::Transport::HTTP 3 "2006-08-16" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
SOAP::Transport::HTTP \- Server/Client side HTTP support for SOAP::Lite
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.IP "Client" 4
.IX Item "Client"
.Vb 9
\&  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
\&  ;
.Ve
.Sp
.Vb 1
\&  print getStateName(1);
.Ve
.IP "\s-1CGI\s0 server" 4
.IX Item "CGI server"
.Vb 1
\&  use SOAP::Transport::HTTP;
.Ve
.Sp
.Vb 5
\&  SOAP::Transport::HTTP::CGI
\&    # specify path to My/Examples.pm here
\&    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method') 
\&    -> handle
\&  ;
.Ve
.IP "Daemon server" 4
.IX Item "Daemon server"
.Vb 1
\&  use SOAP::Transport::HTTP;
.Ve
.Sp
.Vb 1
\&  # change LocalPort to 81 if you want to test it with soapmark.pl
.Ve
.Sp
.Vb 9
\&  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, "\en";
\&  $daemon->handle;
.Ve
.IP "Apache mod_perl server" 4
.IX Item "Apache mod_perl server"
See \fIexamples/server/Apache.pm\fR and \*(L"\s-1EXAMPLES\s0\*(R" section for more information.
.IP "mod_soap server (.htaccess, directory-based access)" 4
.IX Item "mod_soap server (.htaccess, directory-based access)"
.Vb 4
\&  SetHandler perl-script
\&  PerlHandler Apache::SOAP
\&  PerlSetVar dispatch_to "/Your/Path/To/Deployed/Modules, Module::Name, Module::method"
\&  PerlSetVar options "compress_threshold => 10000"
.Ve
.Sp
See Apache::SOAP for more information.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class encapsulates all \s-1HTTP\s0 related logic for a \s-1SOAP\s0 server,
independent of what web server it's attached to. 
If you want to use this class you should follow simple guideline
mentioned above. 
.PP
Following methods are available:
.IP "\fIon_action()\fR" 4
.IX Item "on_action()"
on_action method lets you specify SOAPAction understanding. It accepts
reference to subroutine that takes three parameters: 
.Sp
.Vb 1
\&  SOAPAction, method_uri and method_name.
.Ve
.Sp
\&\f(CW\*(C`SOAPAction\*(C'\fR is taken from \s-1HTTP\s0 header and method_uri and method_name are 
extracted from request's body. Default behavior is match \f(CW\*(C`SOAPAction\*(C'\fR if 
present and ignore it otherwise. You can specify you own, for example 
die if \f(CW\*(C`SOAPAction\*(C'\fR doesn't match with following code:
.Sp
.Vb 4
\&  $server->on_action(sub {
\&    (my $action = shift) =~ s/^("?)(.+)\e1$/$2/;
\&    die "SOAPAction shall match 'uri#method'\en" if $action ne join '#', @_;
\&  });
.Ve
.IP "\fIdispatch_to()\fR" 4
.IX Item "dispatch_to()"
dispatch_to lets you specify where you want to dispatch your services 
to. More precisely, you can specify \f(CW\*(C`PATH\*(C'\fR, \f(CW\*(C`MODULE\*(C'\fR, \f(CW\*(C`method\*(C'\fR or 
combination \f(CW\*(C`MODULE::method\*(C'\fR. Example:
.Sp
.Vb 6
\&  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:: 
\&  );
.Ve
.Sp
If you specify \f(CW\*(C`PATH/\*(C'\fR name of module/classes will be taken from uri as 
path component and converted to Perl module name with substitution 
\&'::' for '/'. Example:
.Sp
.Vb 3
\&  urn:My/Examples              => My::Examples
\&  urn://localhost/My/Examples  => My::Examples
\&  http://localhost/My/Examples => My::Examples
.Ve
.Sp
For consistency first '/' in the path will be ignored.
.Sp
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? 
.IP "\fIhandle()\fR" 4
.IX Item "handle()"
handle method will handle your request. You should provide parameters
with \fIrequest()\fR method, call \fIhandle()\fR and get it back with \fIresponse()\fR .
.IP "\fIrequest()\fR" 4
.IX Item "request()"
request method gives you access to HTTP::Request object which you
can provide for Server component to handle request.
.IP "\fIresponse()\fR" 4
.IX Item "response()"
response method gives you access to HTTP::Response object which 
you can access to get results from Server component after request was
handled.
.Sh "\s-1PROXY\s0 \s-1SETTINGS\s0"
.IX Subsection "PROXY SETTINGS"
You can use any proxy setting you use with LWP::UserAgent modules:
.PP
.Vb 2
\& SOAP::Lite->proxy('http://endpoint.server/', 
\&                   proxy => ['http' => 'http://my.proxy.server']);
.Ve
.PP
or
.PP
.Vb 1
\& $soap->transport->proxy('http' => 'http://my.proxy.server');
.Ve
.PP
should specify proxy server for you. And if you use \f(CW\*(C`HTTP_proxy_user\*(C'\fR 
and \f(CW\*(C`HTTP_proxy_pass\*(C'\fR for proxy authorization SOAP::Lite should know 
how to handle it properly. 
.Sh "COOKIE-BASED \s-1AUTHENTICATION\s0"
.IX Subsection "COOKIE-BASED AUTHENTICATION"
.Vb 1
\&  use HTTP::Cookies;
.Ve
.PP
.Vb 2
\&  my $cookies = HTTP::Cookies->new(ignore_discard => 1);
\&    # you may also add 'file' if you want to keep them between sessions
.Ve
.PP
.Vb 2
\&  my $soap = SOAP::Lite->proxy('http://localhost/');
\&  $soap->transport->cookie_jar($cookies);
.Ve
.PP
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.
.PP
You may also do it in one line:
.PP
.Vb 2
\&  $soap->proxy('http://localhost/', 
\&               cookie_jar => HTTP::Cookies->new(ignore_discard => 1));
.Ve
.Sh "\s-1SSL\s0 \s-1CERTIFICATE\s0 \s-1AUTHENTICATION\s0"
.IX Subsection "SSL CERTIFICATE AUTHENTICATION"
To get certificate authentication working you need to specify three
environment variables: \f(CW\*(C`HTTPS_CERT_FILE\*(C'\fR, \f(CW\*(C`HTTPS_KEY_FILE\*(C'\fR, and 
(optionally) \f(CW\*(C`HTTPS_CERT_PASS\*(C'\fR:
.PP
.Vb 2
\&  $ENV{HTTPS_CERT_FILE} = 'client-cert.pem';
\&  $ENV{HTTPS_KEY_FILE}  = 'client-key.pem';
.Ve
.PP
Crypt::SSLeay (which is used for https support) will take care about 
everything else. Other options (like \s-1CA\s0 peer verification) can be specified
in a similar way. See Crypt::SSLeay documentation for more details.
.PP
Those who would like to use encrypted keys may check 
http://groups.yahoo.com/group/soaplite/message/729 for details. 
.Sh "\s-1COMPRESSION\s0"
.IX Subsection "COMPRESSION"
SOAP::Lite provides you with the option for enabling compression on the 
wire (for \s-1HTTP\s0 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 \s-1NOT\s0 \s-1ACCEPTABLE\s0) 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.
.PP
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.
.IP "Client" 4
.IX Item "Client"
.Vb 6
\&  print SOAP::Lite
\&    -> uri('http://localhost/My/Parameters')
\&    -> proxy('http://localhost/', options => {compress_threshold => 10000})
\&    -> echo(1 x 10000)
\&    -> result
\&  ;
.Ve
.IP "Server" 4
.IX Item "Server"
.Vb 4
\&  my $server = SOAP::Transport::HTTP::CGI
\&    -> dispatch_to('My::Parameters')
\&    -> options({compress_threshold => 10000})
\&    -> handle;
.Ve
.PP
Compression will be enabled on the client side 
\&\fBif\fR the threshold is specified 
\&\fBand\fR the size of current message is bigger than the threshold 
\&\fBand\fR the module Compress::Zlib is available. 
.PP
The Client will send the header 'Accept\-Encoding' with value 'deflate'
\&\fBif\fR the threshold is specified 
\&\fBand\fR the module Compress::Zlib is available.
.PP
Server will accept the compressed message if the module Compress::Zlib 
is available, and will respond with the compressed message 
\&\fBonly if\fR the threshold is specified 
\&\fBand\fR the size of the current message is bigger than the threshold 
\&\fBand\fR the module Compress::Zlib is available 
\&\fBand\fR the header 'Accept\-Encoding' is presented in the request.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Consider following examples of \s-1SOAP\s0 servers:
.IP "\s-1CGI:\s0" 4
.IX Item "CGI:"
.Vb 1
\&  use SOAP::Transport::HTTP;
.Ve
.Sp
.Vb 4
\&  SOAP::Transport::HTTP::CGI
\&    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method') 
\&    -> handle
\&  ;
.Ve
.IP "daemon:" 4
.IX Item "daemon:"
.Vb 1
\&  use SOAP::Transport::HTTP;
.Ve
.Sp
.Vb 6
\&  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, "\en";
\&  $daemon->handle;
.Ve
.IP "mod_perl:" 4
.IX Item "mod_perl:"
httpd.conf:
.Sp
.Vb 4
\&  <Location /soap>
\&    SetHandler perl-script
\&    PerlHandler SOAP::Apache
\&  </Location>
.Ve
.Sp
Apache.pm:
.Sp
.Vb 1
\&  package SOAP::Apache;
.Ve
.Sp
.Vb 1
\&  use SOAP::Transport::HTTP;
.Ve
.Sp
.Vb 2
\&  my $server = SOAP::Transport::HTTP::Apache
\&    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method');
.Ve
.Sp
.Vb 1
\&  sub handler { $server->handler(@_) }
.Ve
.Sp
.Vb 1
\&  1;
.Ve
.IP "Apache::Registry:" 4
.IX Item "Apache::Registry:"
httpd.conf:
.Sp
.Vb 7
\&  Alias /mod_perl/ "/Apache/mod_perl/"
\&  <Location /mod_perl>
\&    SetHandler perl-script
\&    PerlHandler Apache::Registry
\&    PerlSendHeader On
\&    Options +ExecCGI
\&  </Location>
.Ve
.Sp
soap.mod_cgi (put it in /Apache/mod_perl/ directory mentioned above)
.Sp
.Vb 1
\&  use SOAP::Transport::HTTP;
.Ve
.Sp
.Vb 4
\&  SOAP::Transport::HTTP::CGI
\&    -> dispatch_to('/Your/Path/To/Deployed/Modules', 'Module::Name', 'Module::method') 
\&    -> handle
\&  ;
.Ve
.PP
\&\s-1WARNING:\s0 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 \s-1PATH/\s0 and \s-1MODULE\s0 name 
in \fIdispatch_to()\fR and module will be loaded dynamically and then will work 
as under static deployment. See examples/server/soap.mod_cgi for example.
.SH "TROUBLESHOOTING"
.IX Header "TROUBLESHOOTING"
.IP "Dynamic libraries are not found" 4
.IX Item "Dynamic libraries are not found"
If you see in webserver's log file something like this: 
.Sp
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 \s-1NEEDED\s0, but object does not exist at
/usr/local/lib/perl5/.../DynaLoader.pm line 200.
.Sp
and you are using Apache web server, try to put into your httpd.conf
.Sp
.Vb 3
\& <IfModule mod_env.c>
\&     PassEnv LD_LIBRARY_PATH
\& </IfModule>
.Ve
.ie n .IP "Apache is crashing with segfaults (it may looks like ""500 unexpected \s-1EOF\s0 before status line seen"" on client side)" 4
.el .IP "Apache is crashing with segfaults (it may looks like ``500 unexpected \s-1EOF\s0 before status line seen'' on client side)" 4
.IX Item "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:
.Sp
.Vb 1
\& RULE_EXPAT=no
.Ve
.Sp
\&\-\- \s-1OR\s0 (for Apache 1.3.20 and later) \*(--
.Sp
.Vb 1
\& ./configure --disable-rule=EXPAT
.Ve
.Sp
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.
.Sp
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>.
.IP "\s-1CGI\s0 scripts are not running under Microsoft Internet Information Server (\s-1IIS\s0)" 4
.IX Item "CGI scripts are not running under Microsoft Internet Information Server (IIS)"
\&\s-1CGI\s0 scripts may not work under \s-1IIS\s0 unless scripts are .pl, not .cgi.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
.Vb 5
\& 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
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.Vb 4
\& 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.
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2000\-2001 Paul Kulchenko. All rights reserved.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Kulchenko (paulclinger@yahoo.com)