1docs::api::Apache2::comUpsaetr(3C)ontributed Perl Documednotcast:i:oanpi::Apache2::compat(3)
2
6 Apache2::compat -- 1.0 backward compatibility functions deprecated in
7 2.0
8
10 # either add at the very beginning of startup.pl
11 use Apache2::compat;
12 # or httpd.conf
13 PerlModule Apache2::compat
14 # override and restore compat functions colliding with mp2 API
16 Apache2::compat::override_mp2_api('Apache2::Connection::local_addr');
17 my ($local_port, $local_addr) = sockaddr_in($c->local_addr);
18 Apache2::compat::restore_mp2_api('Apache2::Connection::local_addr');
19
21 "Apache2::compat" provides mod_perl 1.0 compatibility layer and can be
22 used to smooth the transition process to mod_perl 2.0.
23 It includes functions that have changed their API or were removed in
25 mod_perl 2.0. If your code uses any of those functions, you should load
26 this module at the server startup, and everything should work as it did
27 in 1.0. If it doesn't please report the bug, but before you do that
28 please make sure that your code does work properly under mod_perl 1.0.
29 However, remember, that it's implemented in pure Perl and not C, there‐
31 fore its functionality is not optimized and it's the best to try to
32 port your code not to use deprecated functions and stop using the com‐
33 patibility layer.
34
36 Most of the functions provided by Apache2::compat don't interfere with
37 mod_perl 2.0 API. However there are several functions which have the
38 same name in the mod_perl 1.0 and mod_perl 2.0 API, accept the same
39 number of arguments, but either the arguments themselves aren't the
40 same or the return values are different. For example the mod_perl 1.0
41 code:
42 require Socket;
44 my $sockaddr_in = $c->local_addr;
45 my ($local_port, $local_addr) = Socket::sockaddr_in($sockaddr_in);
46 should be adjusted to be:
48 require Apache2::Connection;
50 require APR::SockAddr;
51 my $sockaddr = $c->local_addr;
52 my ($local_port, $local_addr) = ($sockaddr->port, $sockaddr->ip_get);
53 to work under mod_perl 2.0.
55 As you can see in mod_perl 1.0 API local_addr() was returning a SOCK‐
57 ADDR_IN object (see the Socket perl manpage), in mod_perl 2.0 API it
58 returns an "APR::SockAddr" object, which is a totally different beast.
59 If Apache2::compat overrides the function "local_addr()" to be back-
60 compatible with mod_perl 1.0 API. Any code that relies on this function
61 to work as it should under mod_perl 2.0 will be broken. Therefore the
62 solution is not to override "local_addr()" by default. Instead a spe‐
63 cial API is provided which overrides colliding functions only when
64 needed and which can be restored when no longer needed. So for example
65 if you have code from mod_perl 1.0:
66 my ($local_port, $local_addr) = Socket::sockaddr_in($c->local_addr);
68 and you aren't ready to port it to to use the mp2 API:
70 my ($local_port, $local_addr) = ($c->local_addr->port,
72 $c->local_addr->ip_get);
73 you could do the following:
75 Apache2::compat::override_mp2_api('Apache2::Connection::local_addr');
77 my ($local_port, $local_addr) = Socket::sockaddr_in($c->local_addr);
78 Apache2::compat::restore_mp2_api('Apache2::Connection::local_addr');
79 Notice that you need to restore the API as soon as possible.
81 Both "override_mp2_api()" and "restore_mp2_api()" accept a list of
83 functions to operate on.
84 Available Overridable Functions
86 At the moment the following colliding functions are available for over‐
88 riding:
89 * "Apache2::RequestRec::notes"
91 * "Apache2::RequestRec::filename"
92 * "Apache2::RequestRec::finfo"
93 * "Apache2::Connection::local_addr"
94 * "Apache2::Connection::remote_addr"
95 * "Apache2::Util::ht_time"
96 * "APR::URI::unparse"
97
99 The short answer: Do not use "Apache2::compat" in CPAN modules.
100 The long answer:
102 "Apache2::compat" is useful during the mod_perl 1.0 code porting.
104 Though remember that it's implemented in pure Perl. In certain cases it
105 overrides mod_perl 2.0 methods, because their API is very different and
106 doesn't map 1:1 to mod_perl 1.0. So if anything, not under user's con‐
107 trol, loads "Apache2::compat" user's code is forced to use the poten‐
108 tially slower method. Which is quite bad.
109 Some users may choose to keep using "Apache2::compat" in production and
111 it may perform just fine. Other users will choose not to use that mod‐
112 ule, by porting their code to use mod_perl 2.0 API. However it should
113 be users' choice whether to load this module or not and not to be
114 enforced by CPAN modules.
115 If you port your CPAN modules to work with mod_perl 2.0, you should
117 follow the porting Perl and XS module guidelines.
118 Users that are stuck with CPAN modules preloading "Apache2::compat",
120 can prevent this from happening by adding
121 $INC{'Apache2/compat.pm'} = __FILE__;
123 at the very beginning of their startup.pl. But this will most certainly
125 break the module that needed this module.
126
128 You should be reading the mod_perl 1.0 API docs for usage of the meth‐
129 ods and functions in this package, since what this module is doing is
130 providing a backwards compatibility and it makes no sense to duplicate
131 documentation.
132 Another important document to read is: Migrating from mod_perl 1.0 to
134 mod_perl 2.0 which covers all mod_perl 1.0 constants, functions and
135 methods that have changed in mod_perl 2.0.
136
138 mod_perl 2.0 documentation.
139
141 mod_perl 2.0 and its core modules are copyrighted under The Apache
142 Software License, Version 2.0.
143
145 The mod_perl development team and numerous contributors.
146perl v5.8.8 2006-11-19 docs::api::Apache2::compat(3)