1# ======================================================================
2#
3# Copyright (C) 2000-2001 Paul Kulchenko (paulclinger@yahoo.com)
4# SOAP::Lite is free software; you can redistribute it
5# and/or modify it under the same terms as Perl itself.
6#
7# $Id: HTTP.pm 414 2012-07-15 09:18:42Z kutterma $
8#
9# ======================================================================
10
11package XMLRPC::Transport::HTTP;
12
13use strict;
14
15our $VERSION = 0.715;
16
17use XMLRPC::Lite;
18
19use SOAP::Transport::HTTP;
20
21# ======================================================================
22
23package XMLRPC::Transport::HTTP::CGI;
24
25@XMLRPC::Transport::HTTP::CGI::ISA = qw(SOAP::Transport::HTTP::CGI);
26
27sub initialize; *initialize = \&XMLRPC::Server::initialize;
28
29sub make_fault {
30  local $SOAP::Constants::HTTP_ON_FAULT_CODE = 200;
31  shift->SUPER::make_fault(@_);
32}
33
34sub make_response {
35  local $SOAP::Constants::DO_NOT_USE_CHARSET = 1;
36  shift->SUPER::make_response(@_);
37}
38
39# ======================================================================
40
41package XMLRPC::Transport::HTTP::Daemon;
42
43@XMLRPC::Transport::HTTP::Daemon::ISA = qw(SOAP::Transport::HTTP::Daemon);
44
45sub initialize; *initialize = \&XMLRPC::Server::initialize;
46sub make_fault; *make_fault = \&XMLRPC::Transport::HTTP::CGI::make_fault;
47sub make_response; *make_response = \&XMLRPC::Transport::HTTP::CGI::make_response;
48
49# ======================================================================
50
51package XMLRPC::Transport::HTTP::Apache;
52
53@XMLRPC::Transport::HTTP::Apache::ISA = qw(SOAP::Transport::HTTP::Apache);
54
55sub initialize; *initialize = \&XMLRPC::Server::initialize;
56sub make_fault; *make_fault = \&XMLRPC::Transport::HTTP::CGI::make_fault;
57sub make_response; *make_response = \&XMLRPC::Transport::HTTP::CGI::make_response;
58
59# ======================================================================
60
611;
62
63__END__
64
65=head1 NAME
66
67XMLRPC::Transport::HTTP - Server/Client side HTTP support for XMLRPC::Lite
68
69=head1 SYNOPSIS
70
71=over 4
72
73=item Client
74
75  use XMLRPC::Lite
76    proxy => 'http://localhost/',
77  # proxy => 'http://localhost/cgi-bin/xmlrpc.cgi', # local CGI server
78  # proxy => 'http://localhost/',                   # local daemon server
79  # proxy => 'http://login:password@localhost/cgi-bin/xmlrpc.cgi', # local CGI server with authentication
80  ;
81
82  print getStateName(1);
83
84=item CGI server
85
86  use XMLRPC::Transport::HTTP;
87
88  my $server = XMLRPC::Transport::HTTP::CGI
89    -> dispatch_to('methodName')
90    -> handle
91  ;
92
93=item Daemon server
94
95  use XMLRPC::Transport::HTTP;
96
97  my $daemon = XMLRPC::Transport::HTTP::Daemon
98    -> new (LocalPort => 80)
99    -> dispatch_to('methodName')
100  ;
101  print "Contact to XMLRPC server at ", $daemon->url, "\n";
102  $daemon->handle;
103
104=back
105
106=head1 DESCRIPTION
107
108This class encapsulates all HTTP related logic for a XMLRPC server,
109independent of what web server it's attached to.
110If you want to use this class you should follow simple guideline
111mentioned above.
112
113=head2 PROXY SETTINGS
114
115You can use any proxy setting you use with LWP::UserAgent modules:
116
117 XMLRPC::Lite->proxy('http://endpoint.server/',
118                     proxy => ['http' => 'http://my.proxy.server']);
119
120or
121
122 $xmlrpc->transport->proxy('http' => 'http://my.proxy.server');
123
124should specify proxy server for you. And if you use C<HTTP_proxy_user>
125and C<HTTP_proxy_pass> for proxy authorization SOAP::Lite should know
126how to handle it properly.
127
128=head2 COOKIE-BASED AUTHENTICATION
129
130  use HTTP::Cookies;
131
132  my $cookies = HTTP::Cookies->new(ignore_discard => 1);
133    # you may also add 'file' if you want to keep them between sessions
134
135  my $xmlrpc = XMLRPC::Lite->proxy('http://localhost/');
136  $xmlrpc->transport->cookie_jar($cookies);
137
138Cookies will be taken from response and provided for request. You may
139always add another cookie (or extract what you need after response)
140with HTTP::Cookies interface.
141
142You may also do it in one line:
143
144  $xmlrpc->proxy('http://localhost/',
145                 cookie_jar => HTTP::Cookies->new(ignore_discard => 1));
146
147=head2 COMPRESSION
148
149XMLRPC::Lite provides you option for enabling compression on wire (for HTTP
150transport only). Both server and client should support this capability,
151but this logic should be absolutely transparent for your application.
152Server will respond with encoded message only if client can accept it
153(client sends Accept-Encoding with 'deflate' or '*' values) and client
154has fallback logic, so if server doesn't understand specified encoding
155(Content-Encoding: deflate) and returns proper error code
156(415 NOT ACCEPTABLE) client will repeat the same request not encoded and
157will store this server in per-session cache, so all other requests will
158go there without encoding.
159
160Having options on client and server side that let you specify threshold
161for compression you can safely enable this feature on both client and
162server side.
163
164Compression will be enabled on client side IF: threshold is specified AND
165size of current message is bigger than threshold AND module Compress::Zlib
166is available. Client will send header 'Accept-Encoding' with value 'deflate'
167if threshold is specified AND module Compress::Zlib is available.
168
169Server will accept compressed message if module Compress::Zlib is available,
170and will respond with compressed message ONLY IF: threshold is specified AND
171size of current message is bigger than threshold AND module Compress::Zlib
172is available AND header 'Accept-Encoding' is presented in request.
173
174=head1 DEPENDENCIES
175
176 Crypt::SSLeay             for HTTPS/SSL
177 HTTP::Daemon              for XMLRPC::Transport::HTTP::Daemon
178 Apache, Apache::Constants for XMLRPC::Transport::HTTP::Apache
179
180=head1 SEE ALSO
181
182 See ::CGI, ::Daemon and ::Apache for implementation details.
183 See examples/XMLRPC/* for examples.
184
185=head1 COPYRIGHT
186
187Copyright (C) 2000-2001 Paul Kulchenko. All rights reserved.
188
189This library is free software; you can redistribute it and/or modify
190it under the same terms as Perl itself.
191
192=head1 AUTHOR
193
194Paul Kulchenko (paulclinger@yahoo.com)
195
196=cut
197