You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-cvs@perl.apache.org by ra...@apache.org on 2005/04/03 01:32:21 UTC
svn commit: r159848 [1/2] - in
perl/modperl/docs/trunk/src/docs/2.0/user/handlers: filters.pod http.pod
intro.pod protocols.pod server.pod
Author: randyk
Date: Sat Apr 2 15:32:19 2005
New Revision: 159848
URL: http://svn.apache.org/viewcvs?view=rev&rev=159848
Log:
s/Apache/Apache2/
Modified:
perl/modperl/docs/trunk/src/docs/2.0/user/handlers/filters.pod
perl/modperl/docs/trunk/src/docs/2.0/user/handlers/http.pod
perl/modperl/docs/trunk/src/docs/2.0/user/handlers/intro.pod
perl/modperl/docs/trunk/src/docs/2.0/user/handlers/protocols.pod
perl/modperl/docs/trunk/src/docs/2.0/user/handlers/server.pod
Modified: perl/modperl/docs/trunk/src/docs/2.0/user/handlers/filters.pod
URL: http://svn.apache.org/viewcvs/perl/modperl/docs/trunk/src/docs/2.0/user/handlers/filters.pod?view=diff&r1=159847&r2=159848
==============================================================================
--- perl/modperl/docs/trunk/src/docs/2.0/user/handlers/filters.pod (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/user/handlers/filters.pod Sat Apr 2 15:32:19 2005
@@ -7,8 +7,8 @@
This chapter discusses mod_perl's input and output filter handlers.
If all you need is to lookup the filtering API proceed directly to the
-C<L<Apache::Filter|docs::2.0::api::Apache::Filter>> and
-C<L<Apache::FilterRec|docs::2.0::api::Apache::FilterRec>> manpages.
+C<L<Apache2::Filter|docs::2.0::api::Apache2::Filter>> and
+C<L<Apache2::FilterRec|docs::2.0::api::Apache2::FilterRec>> manpages.
=head1 Your First Filter
@@ -102,18 +102,18 @@
And here is the filter handler code:
- #file:MyApache/FilterObfuscate.pm
+ #file:MyApache2/FilterObfuscate.pm
#--------------------------------
- package MyApache::FilterObfuscate;
+ package MyApache2::FilterObfuscate;
use strict;
use warnings;
- use Apache::Filter ();
- use Apache::RequestRec ();
+ use Apache2::Filter ();
+ use Apache2::RequestRec ();
use APR::Table ();
- use Apache::Const -compile => qw(OK);
+ use Apache2::Const -compile => qw(OK);
use constant BUFF_LEN => 1024;
@@ -130,20 +130,20 @@
$f->print($buffer);
}
- return Apache::OK;
+ return Apache2::OK;
}
1;
-Next we configure Apache to apply the C<MyApache::FilterObfuscate>
+Next we configure Apache to apply the C<MyApache2::FilterObfuscate>
filter to all requests that get mapped to files with an I<".html">
extension:
<Files ~ "\.html">
- PerlOutputFilterHandler MyApache::FilterObfuscate
+ PerlOutputFilterHandler MyApache2::FilterObfuscate
</Files>
Filter handlers are similar to HTTP handlers, they are expected to
-return C<Apache::OK> or C<Apache::DECLINED>, but instead of receiving
+return C<Apache2::OK> or C<Apache2::DECLINED>, but instead of receiving
C<$r> (the request object) as the first argument, they receive C<$f>
(the filter object).
@@ -184,12 +184,12 @@
the C<unset()> call will be made only on the first filter call for
each request. Of course you can store any kind of a Perl data
-structure in C<L<$f-E<gt>ctx|docs::2.0::api::Apache::Filter/C_ctx_>>
+structure in C<L<$f-E<gt>ctx|docs::2.0::api::Apache2::Filter/C_ctx_>>
and retrieve it later in subsequent filter invocations of the same
request. We will show plenty of examples using this method in the
following sections.
-Of course the C<MyApache::FilterObfuscate> filter logic should take
+Of course the C<MyApache2::FilterObfuscate> filter logic should take
into account situations where removing new line characters will break
the correct rendering, as is the case if there are multi-line
C<E<lt>preE<gt>>...C<E<lt>/preE<gt>> entries, but since it escalates
@@ -316,7 +316,7 @@
META: EOS buckets are valid for Request filters. For Connection
filters, you will get one only in the response filters only at the end
of the connection. See the trick how to workaround this in
-C<Apache::Filter::HTTPHeadersFixup>. Need to mention that in a few
+C<Apache2::Filter::HTTPHeadersFixup>. Need to mention that in a few
other places in this doc.
Notice that the EOS bucket may come attached to the last bucket
@@ -357,7 +357,7 @@
finalize($f);
}
- return Apache::OK;
+ return Apache2::OK;
}
sub init { ... }
sub process { ... }
@@ -388,7 +388,7 @@
}
When the filter is invoked for the first time
-C<L<$f-E<gt>ctx|docs::2.0::api::Apache::Filter/C_ctx_>> returns
+C<L<$f-E<gt>ctx|docs::2.0::api::Apache2::Filter/C_ctx_>> returns
C<undef> and the custom function init() is called. This function
could, for example, retrieve some configuration data, set in
I<httpd.conf> or initialize some datastructure to its default value.
@@ -411,13 +411,13 @@
$f->ctx($ctx);
warn "filter was invoked $ctx->{invoked} times\n";
- return Apache::DECLINED;
+ return Apache2::DECLINED;
}
Since this filter handler doesn't consume the data from the upstream
-filter, it's important that this handler returns C<Apache::DECLINED>,
+filter, it's important that this handler returns C<Apache2::DECLINED>,
in which case mod_perl passes the current bucket brigade to the next
-filter. If this handler returns C<Apache::OK>, the data will be simply
+filter. If this handler returns C<Apache2::OK>, the data will be simply
lost. And if that data included a special EOS token, this may wreck
havoc.
@@ -526,11 +526,11 @@
Here is a code for a transparent input filter:
- #file:MyApache/FilterTransparent.pm (first part)
+ #file:MyApache2/FilterTransparent.pm (first part)
#-----------------------------------------------
- package MyApache::FilterTransparent;
+ package MyApache2::FilterTransparent;
- use Apache::Const -compile => qw(OK);
+ use Apache2::Const -compile => qw(OK);
use APR::Const -compile => ':common';
sub in {
@@ -539,7 +539,7 @@
my $rv = $f->next->get_brigade($bb, $mode, $block, $readbytes);
return $rv unless $rv == APR::SUCCESS;
- return Apache::OK;
+ return Apache2::OK;
}
When the input filter I<in()> is invoked, it first asks the upstream
@@ -598,7 +598,7 @@
Here is an example of a transparent output filter:
- #file:MyApache/FilterTransparent.pm (continued)
+ #file:MyApache2/FilterTransparent.pm (continued)
#-----------------------------------------------
sub out {
my ($f, $bb) = @_;
@@ -606,7 +606,7 @@
my $rv = $f->next->pass_brigade($bb);
return $rv unless $rv == APR::SUCCESS;
- return Apache::OK;
+ return Apache2::OK;
}
1;
@@ -699,7 +699,7 @@
C<L<AutoLoad|docs::2.0::user::config::config/C_AutoLoad_>>ed, using
the C<-> prefix. For example:
- PerlInputFilterHandler -MyApache::FilterTest::lc
+ PerlInputFilterHandler -MyApache2::FilterTest::lc
The following sections include several examples that use the
C<PerlInputFilterHandler> handler.
@@ -735,10 +735,10 @@
To mix mod_perl and non-mod_perl input filters of the L<same
priority|/Filter_Priority_Types> nothing special should be done. For
example if we have an imaginary Apache filter C<FILTER_FOO> and
-mod_perl filter C<MyApache::FilterInputFoo>, this configuration:
+mod_perl filter C<MyApache2::FilterInputFoo>, this configuration:
SetInputFilter FILTER_FOO
- PerlInputFilterHandler MyApache::FilterInputFoo
+ PerlInputFilterHandler MyApache2::FilterInputFoo
will add both filters, however the order of their invocation might be
not the one that you've expected. To make the invocation order the
@@ -746,11 +746,11 @@
C<PerlSetInputFilter>, like so:
PerlSetInputFilter FILTER_FOO
- PerlInputFilterHandler MyApache::FilterInputFoo
+ PerlInputFilterHandler MyApache2::FilterInputFoo
now C<FILTER_FOO> filter will be always executed before the
-C<MyApache::FilterInputFoo> filter, since it was configured before
-C<MyApache::FilterInputFoo> (i.e., it'll apply its transformations on
+C<MyApache2::FilterInputFoo> filter, since it was configured before
+C<MyApache2::FilterInputFoo> (i.e., it'll apply its transformations on
the incoming data last). Here is a diagram input filters chain and the
data flow from the network to the response handler for the presented
configuration:
@@ -761,7 +761,7 @@
FILTER_FOO
/\
||
- MyApache::FilterInputFoo
+ MyApache2::FilterInputFoo
/\
||
core input filters
@@ -772,20 +772,20 @@
As explained in the section L<Filter Priority
Types|/Filter_Priority_Types> this directive won't affect filters of
different priority. For example assuming that
-C<MyApache::FilterInputFoo> is a C<FilterRequestHandler> filter, the
+C<MyApache2::FilterInputFoo> is a C<FilterRequestHandler> filter, the
configurations:
- PerlInputFilterHandler MyApache::FilterInputFoo
+ PerlInputFilterHandler MyApache2::FilterInputFoo
PerlSetInputFilter DEFLATE
and
PerlSetInputFilter DEFLATE
- PerlInputFilterHandler MyApache::FilterInputFoo
+ PerlInputFilterHandler MyApache2::FilterInputFoo
are equivalent, because mod_deflate's C<DEFLATE> filter has a higher
-priority than C<MyApache::FilterInputFoo>, thefore it'll always be
-inserted into the filter chain after C<MyApache::FilterInputFoo>,
+priority than C<MyApache2::FilterInputFoo>, thefore it'll always be
+inserted into the filter chain after C<MyApache2::FilterInputFoo>,
(i.e. the C<DEFLATE> filter will apply its transformations on the
incoming data first). Here is a diagram input filters chain and the
data flow from the network to the response handler for the presented
@@ -794,7 +794,7 @@
response handler
/\
||
- MyApache::FilterInputFoo
+ MyApache2::FilterInputFoo
/\
||
DEFLATE
@@ -808,10 +808,10 @@
C<SetInputFilter>'s C<;> semantics are supported as well. For
example, in the following configuration:
- PerlInputFilterHandler MyApache::FilterInputFoo
+ PerlInputFilterHandler MyApache2::FilterInputFoo
PerlSetInputFilter FILTER_FOO;FILTER_BAR
-C<MyApache::FilterOutputFoo> will be executed first, followed by
+C<MyApache2::FilterOutputFoo> will be executed first, followed by
C<FILTER_FOO> and finally by C<FILTER_BAR> (again, assuming that all
three filters have the same priority).
@@ -834,7 +834,7 @@
be done. This configuration:
SetOutputFilter INCLUDES
- PerlOutputFilterHandler MyApache::FilterOutputFoo
+ PerlOutputFilterHandler MyApache2::FilterOutputFoo
will add all two filters to the filter chain, however the order of
their invocation might be not the one that you've expected. To
@@ -842,10 +842,10 @@
C<PerlSetOutputFilter>, like so:
PerlSetOutputFilter INCLUDES
- PerlOutputFilterHandler MyApache::FilterOutputFoo
+ PerlOutputFilterHandler MyApache2::FilterOutputFoo
now mod_include's C<INCLUDES> filter will be always executed before
-the C<MyApache::FilterOutputFoo> filter. Here is a diagram input
+the C<MyApache2::FilterOutputFoo> filter. Here is a diagram input
filters chain and the data flow from the response handler to the
network for the presented configuration:
@@ -855,7 +855,7 @@
INCLUDES
||
\/
- MyApache::FilterOutputFoo
+ MyApache2::FilterOutputFoo
||
\/
core output filters
@@ -866,10 +866,10 @@
C<SetOutputFilter>'s C<;> semantics are supported as well. For
example, in the following configuration:
- PerlOutputFilterHandler MyApache::FilterOutputFoo
+ PerlOutputFilterHandler MyApache2::FilterOutputFoo
PerlSetOutputFilter INCLUDES;FILTER_FOO
-C<MyApache::FilterOutputFoo> will be executed first, followed by
+C<MyApache2::FilterOutputFoo> will be executed first, followed by
C<INCLUDES> and finally by C<FILTER_FOO> (again, assuming that all
three filters have the same priority).
@@ -879,10 +879,10 @@
PerlSetOutputFilter DEFLATE
PerlSetOutputFilter INCLUDES
- PerlOutputFilterHandler MyApache::FilterOutputFoo
+ PerlOutputFilterHandler MyApache2::FilterOutputFoo
mod_include's C<INCLUDES> filter will be always executed before the
-C<MyApache::FilterOutputFoo> filter. The latter will be followed by
+C<MyApache2::FilterOutputFoo> filter. The latter will be followed by
mod_deflate's C<DEFLATE> filter, even though it was configured before
the other two filters. This is because it has a L<higher
priority|/Filter_Priority_Types>. And the corresponding diagram looks
@@ -894,7 +894,7 @@
INCLUDES
||
\/
- MyApache::FilterOutputFoo
+ MyApache2::FilterOutputFoo
||
\/
DEFLATE
@@ -919,34 +919,34 @@
filter during the Fixup phase:
<Files *\.html >
- PerlFixupHandler MyApache::AddFilterDyn
+ PerlFixupHandler MyApache2::AddFilterDyn
</Files>
And the corresponding module:
- #file:MyApache/AddFilterDyn.pm
- package MyApache::AddFilterDyn;
+ #file:MyApache2/AddFilterDyn.pm
+ package MyApache2::AddFilterDyn;
- use Apache::Const -compile => qw(OK);
- use Apache::Filter;
- use MyApache::FilterObfuscate;
+ use Apache2::Const -compile => qw(OK);
+ use Apache2::Filter;
+ use MyApache2::FilterObfuscate;
sub handler {
my $r = shift;
- $r->add_output_filter(\&MyApache::FilterObfuscate::handler);
+ $r->add_output_filter(\&MyApache2::FilterObfuscate::handler);
- return Apache::OK;
+ return Apache2::OK;
}
1;
You can also add connection filters dynamically. For more information
-referer to the C<L<Apache::Filter|docs::2.0::api::Apache::Filter>>
+referer to the C<L<Apache2::Filter|docs::2.0::api::Apache2::Filter>>
manpage:
-C<L<add_input_filter|docs::2.0::api::Apache::Filter/C_add_input_filter_>>
+C<L<add_input_filter|docs::2.0::api::Apache2::Filter/C_add_input_filter_>>
and
-C<L<add_output_filter|docs::2.0::api::Apache::Filter/C_add_output_filter_>>.
+C<L<add_output_filter|docs::2.0::api::Apache2::Filter/C_add_output_filter_>>.
@@ -962,8 +962,8 @@
C<FilterRequestHandler> attribute. Consider the following request
input and output filters skeleton:
- package MyApache::FilterRequestFoo;
- use base qw(Apache::Filter);
+ package MyApache2::FilterRequestFoo;
+ use base qw(Apache2::Filter);
sub input : FilterRequestHandler {
my($f, $bb, $mode, $block, $readbytes) = @_;
@@ -979,20 +979,20 @@
If the attribute is not specified, the default C<FilterRequestHandler>
attribute is assumed. Filters specifying subroutine attributes must
-subclass C<Apache::Filter>, others only need to:
+subclass C<Apache2::Filter>, others only need to:
- use Apache::Filter ();
+ use Apache2::Filter ();
The request filters are usually configured in the
C<E<lt>LocationE<gt>> or equivalent sections:
- PerlModule MyApache::FilterRequestFoo
- PerlModule MyApache::NiceResponse
+ PerlModule MyApache2::FilterRequestFoo
+ PerlModule MyApache2::NiceResponse
<Location /filter_foo>
SetHandler modperl
- PerlResponseHandler MyApache::NiceResponse
- PerlInputFilterHandler MyApache::FilterRequestFoo::input
- PerlOutputFilterHandler MyApache::FilterRequestFoo::output
+ PerlResponseHandler MyApache2::NiceResponse
+ PerlInputFilterHandler MyApache2::FilterRequestFoo::input
+ PerlOutputFilterHandler MyApache2::FilterRequestFoo::output
</Location>
Now we have the request input and output filters configured.
@@ -1001,8 +1001,8 @@
attribute. Here is a similar example for the connection input and
output filters.
- package MyApache::FilterConnectionBar;
- use base qw(Apache::Filter);
+ package MyApache2::FilterConnectionBar;
+ use base qw(Apache2::Filter);
sub input : FilterConnectionHandler {
my($f, $bb, $mode, $block, $readbytes) = @_;
@@ -1022,14 +1022,14 @@
Listen 8005
<VirtualHost _default_:8005>
- PerlModule MyApache::FilterConnectionBar
- PerlModule MyApache::NiceResponse
+ PerlModule MyApache2::FilterConnectionBar
+ PerlModule MyApache2::NiceResponse
- PerlInputFilterHandler MyApache::FilterConnectionBar::input
- PerlOutputFilterHandler MyApache::FilterConnectionBar::output
+ PerlInputFilterHandler MyApache2::FilterConnectionBar::input
+ PerlOutputFilterHandler MyApache2::FilterConnectionBar::output
<Location />
SetHandler modperl
- PerlResponseHandler MyApache::NiceResponse
+ PerlResponseHandler MyApache2::NiceResponse
</Location>
</VirtualHost>
@@ -1061,7 +1061,7 @@
sub init : FilterInitHandler {
my $f = shift;
#...
- return Apache::OK;
+ return Apache2::OK;
}
The attribute C<FilterInitHandler> marks the Perl function suitable to
@@ -1075,20 +1075,20 @@
sub init : FilterInitHandler {
my $f = shift;
$f->remove() if should_remove_filter();
- return Apache::OK;
+ return Apache2::OK;
}
-Not all C<Apache::Filter> methods can be used in the init handler,
+Not all C<Apache2::Filter> methods can be used in the init handler,
because it's not a filter. Hence you can use methods that L<operate on
the filter
-itself|docs::2.0::api::Apache::Filter/Common_Filter_API>, such as
-C<L<remove()|docs::2.0::api::Apache::Filter/C_remove_>> and
-C<L<ctx()|docs::2.0::api::Apache::Filter/C_ctx_>> or retrieve request
-information, such as C<L<r()|docs::2.0::api::Apache::Filter/C_r_>> and
-C<L<c()|docs::2.0::api::Apache::Filter/C_c_>>. But not methods that
+itself|docs::2.0::api::Apache2::Filter/Common_Filter_API>, such as
+C<L<remove()|docs::2.0::api::Apache2::Filter/C_remove_>> and
+C<L<ctx()|docs::2.0::api::Apache2::Filter/C_ctx_>> or retrieve request
+information, such as C<L<r()|docs::2.0::api::Apache2::Filter/C_r_>> and
+C<L<c()|docs::2.0::api::Apache2::Filter/C_c_>>. But not methods that
operate on data, such as
-C<L<read()|docs::2.0::api::Apache::Filter/C_read_>> and
-C<L<print()|docs::2.0::api::Apache::Filter/C_print_>>.
+C<L<read()|docs::2.0::api::Apache2::Filter/C_read_>> and
+C<L<print()|docs::2.0::api::Apache2::Filter/C_print_>>.
In order to hook an init filter handler, the real filter has to assign
this callback using the C<FilterHasInitHandler> which accepts a
@@ -1096,13 +1096,13 @@
used callback function has to have the C<FilterInitHandler>
attribute. For example:
- package MyApache::FilterBar;
- use base qw(Apache::Filter);
+ package MyApache2::FilterBar;
+ use base qw(Apache2::Filter);
sub init : FilterInitHandler { ... }
sub filter : FilterRequestHandler FilterHasInitHandler(\&init) {
my ($f, $bb) = @_;
# ...
- return Apache::OK;
+ return Apache2::OK;
}
While attributes are parsed during the code compilation (it's really a
@@ -1112,24 +1112,24 @@
The argument to C<FilterHasInitHandler()> can be any Perl code which
when C<eval()>'ed returns a code reference. For example:
- package MyApache::OtherFilter;
- use base qw(Apache::Filter);
+ package MyApache2::OtherFilter;
+ use base qw(Apache2::Filter);
sub init : FilterInitHandler { ... }
- package MyApache::FilterBar;
- use MyApache::OtherFilter;
- use base qw(Apache::Filter);
- sub get_pre_handler { \&MyApache::OtherFilter::init }
+ package MyApache2::FilterBar;
+ use MyApache2::OtherFilter;
+ use base qw(Apache2::Filter);
+ sub get_pre_handler { \&MyApache2::OtherFilter::init }
sub filter : FilterHasInitHandler(get_pre_handler()) { ... }
-Here the C<MyApache::FilterBar::filter> handler is configured to run
-the C<MyApache::OtherFilter::init> init handler.
+Here the C<MyApache2::FilterBar::filter> handler is configured to run
+the C<MyApache2::OtherFilter::init> init handler.
Notice that the argument to C<FilterHasInitHandler()> is always
C<eval()>'ed in the package of the real filter handler (not the init
handler). So the above code leads to the following evaluation:
- $init_sub = eval "package MyApache::FilterBar; get_pre_handler()";
+ $init_sub = eval "package MyApache2::FilterBar; get_pre_handler()";
though, this is done in C, using the C<eval_pv()> C call.
@@ -1143,26 +1143,26 @@
Before we delve into the details of how to write filters that do
something with the data, lets first write a simple filter that does
nothing but snooping on the data that goes through it. We are going to
-develop the C<MyApache::FilterSnoop> handler which can snoop on
+develop the C<MyApache2::FilterSnoop> handler which can snoop on
request and connection filters, in input and output modes.
But first let's develop a simple response handler that simply dumps
the request's I<args> and I<content> as strings:
- file:MyApache/Dump.pm
+ file:MyApache2/Dump.pm
---------------------
- package MyApache::Dump;
+ package MyApache2::Dump;
use strict;
use warnings;
- use Apache::RequestRec ();
- use Apache::RequestIO ();
- use Apache::Filter ();
+ use Apache2::RequestRec ();
+ use Apache2::RequestIO ();
+ use Apache2::Filter ();
use APR::Brigade ();
use APR::Bucket ();
- use Apache::Const -compile => qw(OK M_POST);
+ use Apache2::Const -compile => qw(OK M_POST);
sub handler {
my $r = shift;
@@ -1170,15 +1170,15 @@
$r->print("args:\n", $r->args, "\n");
- if ($r->method_number == Apache::M_POST) {
+ if ($r->method_number == Apache2::M_POST) {
my $data = content($r);
$r->print("content:\n$data\n");
}
- return Apache::OK;
+ return Apache2::OK;
}
- use Apache::Const -compile => qw(MODE_READBYTES);
+ use Apache2::Const -compile => qw(MODE_READBYTES);
use APR::Const -compile => qw(SUCCESS BLOCK_READ);
use constant IOBUFSIZE => 8192;
@@ -1191,7 +1191,7 @@
my $data = '';
my $seen_eos = 0;
do {
- $r->input_filters->get_brigade($bb, Apache::MODE_READBYTES,
+ $r->input_filters->get_brigade($bb, Apache2::MODE_READBYTES,
APR::BLOCK_READ, IOBUFSIZE);
for (my $b = $bb->first; $b; $b = $bb->next($b)) {
@@ -1217,10 +1217,10 @@
which is configured as:
- PerlModule MyApache::Dump
+ PerlModule MyApache2::Dump
<Location /dump>
SetHandler modperl
- PerlResponseHandler MyApache::Dump
+ PerlResponseHandler MyApache2::Dump
</Location>
If we issue the following request:
@@ -1238,20 +1238,20 @@
Now let's write the snooping filter:
- file:MyApache/FilterSnoop.pm
+ file:MyApache2/FilterSnoop.pm
----------------------------
- package MyApache::FilterSnoop;
+ package MyApache2::FilterSnoop;
use strict;
use warnings;
- use base qw(Apache::Filter);
- use Apache::FilterRec ();
+ use base qw(Apache2::Filter);
+ use Apache2::FilterRec ();
use APR::Brigade ();
use APR::Bucket ();
use APR::BucketType ();
- use Apache::Const -compile => qw(OK DECLINED);
+ use Apache2::Const -compile => qw(OK DECLINED);
use APR::Const -compile => ':common';
sub connection : FilterConnectionHandler { snoop("connection", @_) }
@@ -1278,7 +1278,7 @@
return $rv unless $rv == APR::SUCCESS;
}
- return Apache::OK;
+ return Apache2::OK;
}
sub bb_dump {
@@ -1340,19 +1340,19 @@
Listen 8008
<VirtualHost _default_:8008>
- PerlModule MyApache::FilterSnoop
- PerlModule MyApache::Dump
+ PerlModule MyApache2::FilterSnoop
+ PerlModule MyApache2::Dump
# Connection filters
- PerlInputFilterHandler MyApache::FilterSnoop::connection
- PerlOutputFilterHandler MyApache::FilterSnoop::connection
+ PerlInputFilterHandler MyApache2::FilterSnoop::connection
+ PerlOutputFilterHandler MyApache2::FilterSnoop::connection
<Location /dump>
SetHandler modperl
- PerlResponseHandler MyApache::Dump
+ PerlResponseHandler MyApache2::Dump
# Request filters
- PerlInputFilterHandler MyApache::FilterSnoop::request
- PerlOutputFilterHandler MyApache::FilterSnoop::request
+ PerlInputFilterHandler MyApache2::FilterSnoop::request
+ PerlOutputFilterHandler MyApache2::FilterSnoop::request
</Location>
</VirtualHost>
@@ -1364,7 +1364,7 @@
% echo "mod_perl rules" | POST 'http://localhost:8008/dump?foo=1&bar=2'
-We get the same response, when using C<MyApache::FilterSnoop>, because
+We get the same response, when using C<MyApache2::FilterSnoop>, because
our snooping filter didn't change anything. Though there was a lot of
output printed to I<error_log>. We present it all here, since it helps
a lot to understand how filters work.
@@ -1421,7 +1421,7 @@
been consumed by the last core connection filter.
The following two entries are generated when
-C<MyApache::Dump::handler> reads the POSTed content:
+C<MyApache2::Dump::handler> reads the POSTed content:
<<< connection input filter
o bucket 1: HEAP
@@ -1441,7 +1441,7 @@
filter is of type I<EOS>, meaning that all the input data from the
current request has been received.
-Next we can see that C<MyApache::Dump::handler> has generated its
+Next we can see that C<MyApache2::Dump::handler> has generated its
response. However we can see that only the request output filter gets
run at this point:
@@ -1549,25 +1549,25 @@
The following input filter handler does that by directly manipulating
the bucket brigades:
- file:MyApache/InputFilterGET2HEAD.pm
+ file:MyApache2/InputFilterGET2HEAD.pm
-----------------------------------
- package MyApache::InputFilterGET2HEAD;
+ package MyApache2::InputFilterGET2HEAD;
use strict;
use warnings;
- use base qw(Apache::Filter);
+ use base qw(Apache2::Filter);
use APR::Brigade ();
use APR::Bucket ();
- use Apache::Const -compile => 'OK';
+ use Apache2::Const -compile => 'OK';
use APR::Const -compile => ':common';
sub handler : FilterConnectionHandler {
my($f, $bb, $mode, $block, $readbytes) = @_;
- return Apache::DECLINED if $f->ctx;
+ return Apache2::DECLINED if $f->ctx;
my $rv = $f->next->get_brigade($bb, $mode, $block, $readbytes);
return $rv unless $rv == APR::SUCCESS;
@@ -1585,7 +1585,7 @@
}
}
- Apache::OK;
+ Apache2::OK;
}
1;
@@ -1628,16 +1628,16 @@
(which normally resides in one bucket), so we have to make sure that
no other data gets mangled (e.g. there could be POSTED data and it may
match C</^GET/> in one of the buckets). We use
-C<L<$f-E<gt>ctx|docs::2.0::api::Apache::Filter/C_ctx_>> as a flag
+C<L<$f-E<gt>ctx|docs::2.0::api::Apache2::Filter/C_ctx_>> as a flag
here. When it's undefined the filter knows that it hasn't done the
required substitution, though once it completes the job it sets the
context to 1.
To optimize the speed, the filter immediately returns
-C<Apache::DECLINED> when it's invoked after the substitution job has
+C<Apache2::DECLINED> when it's invoked after the substitution job has
been done:
- return Apache::DECLINED if $f->ctx;
+ return Apache2::DECLINED if $f->ctx;
In that case mod_perl will call C<get_brigade()> internally which will
pass the bucket brigade to the downstream filter. Alternatively the
@@ -1645,7 +1645,7 @@
my $rv = $f->next->get_brigade($bb, $mode, $block, $readbytes);
return $rv unless $rv == APR::SUCCESS;
- return Apache::OK if $f->ctx;
+ return Apache2::OK if $f->ctx;
but this is a bit less efficient.
@@ -1655,7 +1655,7 @@
if ($f->ctx) {
$f->remove;
- return Apache::DECLINED;
+ return Apache2::DECLINED;
}
However, this can't be used with Apache 2.0.49 and lower, since it has
@@ -1679,25 +1679,25 @@
Finally we set the context to 1, so we know not to apply the
substitution on the following data and break from the I<for> loop.
-The handler returns C<Apache::OK> indicating that everything was
+The handler returns C<Apache2::OK> indicating that everything was
fine. The downstream filter will receive the bucket brigade with one
bucket modified.
Now let's check that the handler works properly. For example, consider
the following response handler:
- file:MyApache/RequestType.pm
+ file:MyApache2/RequestType.pm
---------------------------
- package MyApache::RequestType;
+ package MyApache2::RequestType;
use strict;
use warnings;
- use Apache::RequestIO ();
- use Apache::RequestRec ();
- use Apache::Response ();
+ use Apache2::RequestIO ();
+ use Apache2::RequestRec ();
+ use Apache2::Response ();
- use Apache::Const -compile => 'OK';
+ use Apache2::Const -compile => 'OK';
sub handler {
my $r = shift;
@@ -1707,7 +1707,7 @@
$r->set_content_length(length $response);
$r->print($response);
- Apache::OK;
+ Apache2::OK;
}
1;
@@ -1722,7 +1722,7 @@
<VirtualHost _default_:8005>
<Location />
SetHandler modperl
- PerlResponseHandler +MyApache::RequestType
+ PerlResponseHandler +MyApache2::RequestType
</Location>
</VirtualHost>
@@ -1739,16 +1739,16 @@
And the C<Content-Length> header is set to 24.
-However if we enable the C<MyApache::InputFilterGET2HEAD> input
+However if we enable the C<MyApache2::InputFilterGET2HEAD> input
connection filter:
Listen 8005
<VirtualHost _default_:8005>
- PerlInputFilterHandler +MyApache::InputFilterGET2HEAD
+ PerlInputFilterHandler +MyApache2::InputFilterGET2HEAD
<Location />
SetHandler modperl
- PerlResponseHandler +MyApache::RequestType
+ PerlResponseHandler +MyApache2::RequestType
</Location>
</VirtualHost>
@@ -1776,22 +1776,22 @@
=head2 Bucket Brigade-based Input Filters
Let's look at the request input filter that lowers the case of the
-request's body: C<MyApache::InputRequestFilterLC>:
+request's body: C<MyApache2::InputRequestFilterLC>:
- file:MyApache/InputRequestFilterLC.pm
+ file:MyApache2/InputRequestFilterLC.pm
-------------------------------------
- package MyApache::InputRequestFilterLC;
+ package MyApache2::InputRequestFilterLC;
use strict;
use warnings;
- use base qw(Apache::Filter);
+ use base qw(Apache2::Filter);
- use Apache::Connection ();
+ use Apache2::Connection ();
use APR::Brigade ();
use APR::Bucket ();
- use Apache::Const -compile => 'OK';
+ use Apache2::Const -compile => 'OK';
use APR::Const -compile => ':common';
sub handler : FilterRequestHandler {
@@ -1817,7 +1817,7 @@
$bb->insert_tail($b);
}
- Apache::OK;
+ Apache2::OK;
}
1;
@@ -1843,14 +1843,14 @@
which messes up the request method, the URL and the protocol.
-Now if we use the C<MyApache::Dump> response handler, we have
+Now if we use the C<MyApache2::Dump> response handler, we have
developed before in this chapter, which dumps the query string and the
content body as a response, and configure the server as follows:
<Location /lc_input>
SetHandler modperl
- PerlResponseHandler +MyApache::Dump
- PerlInputFilterHandler +MyApache::InputRequestFilterLC
+ PerlResponseHandler +MyApache2::Dump
+ PerlInputFilterHandler +MyApache2::InputRequestFilterLC
</Location>
When issuing a POST request:
@@ -1874,16 +1874,16 @@
Let's now look at the same filter implemented using the
stream-oriented API.
- file:MyApache/InputRequestFilterLC2.pm
+ file:MyApache2/InputRequestFilterLC2.pm
-------------------------------------
- package MyApache::InputRequestFilterLC2;
+ package MyApache2::InputRequestFilterLC2;
use strict;
use warnings;
- use base qw(Apache::Filter);
+ use base qw(Apache2::Filter);
- use Apache::Const -compile => 'OK';
+ use Apache2::Const -compile => 'OK';
use constant BUFF_LEN => 1024;
@@ -1894,7 +1894,7 @@
$f->print(lc $buffer);
}
- Apache::OK;
+ Apache2::OK;
}
1;
@@ -1940,8 +1940,8 @@
<Location /lc_input2>
SetHandler modperl
- PerlResponseHandler +MyApache::Dump
- PerlInputFilterHandler +MyApache::InputRequestFilterLC2
+ PerlResponseHandler +MyApache2::Dump
+ PerlInputFilterHandler +MyApache2::InputRequestFilterLC2
</Location>
When issuing a POST request:
@@ -1985,17 +1985,17 @@
First let's develop a response handler that sends two lines of output:
numerals 1234567890 and the English alphabet in a single string:
- file:MyApache/SendAlphaNum.pm
+ file:MyApache2/SendAlphaNum.pm
-------------------------------
- package MyApache::SendAlphaNum;
+ package MyApache2::SendAlphaNum;
use strict;
use warnings;
- use Apache::RequestRec ();
- use Apache::RequestIO ();
+ use Apache2::RequestRec ();
+ use Apache2::RequestIO ();
- use Apache::Const -compile => qw(OK);
+ use Apache2::Const -compile => qw(OK);
sub handler {
my $r = shift;
@@ -2005,7 +2005,7 @@
$r->print(1..9, "0\n");
$r->print('a'..'z', "\n");
- Apache::OK;
+ Apache2::OK;
}
1;
@@ -2022,16 +2022,16 @@
The first filter implementation is using the stream-oriented filtering
API:
- file:MyApache/FilterReverse1.pm
+ file:MyApache2/FilterReverse1.pm
----------------------------
- package MyApache::FilterReverse1;
+ package MyApache2::FilterReverse1;
use strict;
use warnings;
- use base qw(Apache::Filter);
+ use base qw(Apache2::Filter);
- use Apache::Const -compile => qw(OK);
+ use Apache2::Const -compile => qw(OK);
use constant BUFF_LEN => 1024;
@@ -2045,34 +2045,34 @@
}
}
- Apache::OK;
+ Apache2::OK;
}
1;
Next, we add the following configuration to I<httpd.conf>:
- PerlModule MyApache::FilterReverse1
- PerlModule MyApache::SendAlphaNum
+ PerlModule MyApache2::FilterReverse1
+ PerlModule MyApache2::SendAlphaNum
<Location /reverse1>
SetHandler modperl
- PerlResponseHandler MyApache::SendAlphaNum
- PerlOutputFilterHandler MyApache::FilterReverse1
+ PerlResponseHandler MyApache2::SendAlphaNum
+ PerlOutputFilterHandler MyApache2::FilterReverse1
</Location>
Now when a request to I</reverse1> is made, the response handler
-C<MyApache::SendAlphaNum::handler()> sends:
+C<MyApache2::SendAlphaNum::handler()> sends:
1234567890
abcdefghijklmnopqrstuvwxyz
as a response and the output filter handler
-C<MyApache::FilterReverse1::handler> reverses the lines, so the client
+C<MyApache2::FilterReverse1::handler> reverses the lines, so the client
gets:
0987654321
zyxwvutsrqponmlkjihgfedcba
-The C<Apache::Filter> module loads the C<read()> and C<print()>
+The C<Apache2::Filter> module loads the C<read()> and C<print()>
methods which encapsulate the stream-oriented filtering interface.
The reversing filter is quite simple: in the loop it reads the data in
@@ -2115,7 +2115,7 @@
$f->ctx($leftover) if defined $leftover;
}
- return Apache::OK;
+ return Apache2::OK;
}
The handler uses the C<$leftover> variable to store unprocessed data
@@ -2131,19 +2131,19 @@
The following filter implementation is using the bucket brigades API
to accomplish exactly the same task as the first filter.
- file:MyApache/FilterReverse2.pm
+ file:MyApache2/FilterReverse2.pm
--------------------------------
- package MyApache::FilterReverse2;
+ package MyApache2::FilterReverse2;
use strict;
use warnings;
- use base qw(Apache::Filter);
+ use base qw(Apache2::Filter);
use APR::Brigade ();
use APR::Bucket ();
- use Apache::Const -compile => 'OK';
+ use Apache2::Const -compile => 'OK';
use APR::Const -compile => ':common';
sub handler : FilterRequestHandler {
@@ -2172,18 +2172,18 @@
my $rv = $f->next->pass_brigade($bb_ctx);
return $rv unless $rv == APR::SUCCESS;
- Apache::OK;
+ Apache2::OK;
}
1;
and the corresponding configuration:
- PerlModule MyApache::FilterReverse2
- PerlModule MyApache::SendAlphaNum
+ PerlModule MyApache2::FilterReverse2
+ PerlModule MyApache2::SendAlphaNum
<Location /reverse2>
SetHandler modperl
- PerlResponseHandler MyApache::SendAlphaNum
- PerlOutputFilterHandler MyApache::FilterReverse2
+ PerlResponseHandler MyApache2::SendAlphaNum
+ PerlOutputFilterHandler MyApache2::FilterReverse2
</Location>
Now when a request to I</reverse2> is made, the client gets:
@@ -2209,7 +2209,7 @@
created brigade with modified data to the next filter and return.
Similarly to the original version of
-C<MyApache::FilterReverse1::handler>, this filter is not smart enough
+C<MyApache2::FilterReverse1::handler>, this filter is not smart enough
to handle incomplete lines. However the exercise of making the filter
foolproof should be trivial by porting a better matching rule and
using the C<$leftover> buffer from the previous section is trivial and
@@ -2301,16 +2301,16 @@
implementation details. First let's look at the C<response()> handler
(the first part of the module):
- #file:MyApache/Underrun.pm
+ #file:MyApache2/Underrun.pm
#-------------------------
- package MyApache::Underrun;
+ package MyApache2::Underrun;
use strict;
use warnings;
use constant IOBUFSIZE => 8192;
- use Apache::Const -compile => qw(MODE_READBYTES OK M_POST);
+ use Apache2::Const -compile => qw(MODE_READBYTES OK M_POST);
use APR::Const -compile => qw(SUCCESS BLOCK_READ);
sub response {
@@ -2318,14 +2318,14 @@
$r->content_type('text/plain');
- if ($r->method_number == Apache::M_POST) {
+ if ($r->method_number == Apache2::M_POST) {
my $data = read_post($r);
#warn "HANDLER READ: $data\n";
my $length = length $data;
$r->print("read $length chars");
}
- return Apache::OK;
+ return Apache2::OK;
}
sub read_post {
@@ -2336,7 +2336,7 @@
my $data = '';
my $seen_eos = 0;
do {
- $r->input_filters->get_brigade($bb, Apache::MODE_READBYTES,
+ $r->input_filters->get_brigade($bb, Apache2::MODE_READBYTES,
APR::BLOCK_READ, IOBUFSIZE);
for (my $b = $bb->first; $b; $b = $bb->next($b)) {
@@ -2364,11 +2364,11 @@
Now comes the filter (which lives in the same package):
- #file:MyApache/Underrun.pm (continued)
+ #file:MyApache2/Underrun.pm (continued)
#-------------------------------------
- use Apache::Filter ();
+ use Apache2::Filter ();
- use Apache::Const -compile => qw(OK M_POST);
+ use Apache2::Const -compile => qw(OK M_POST);
use constant TOKEN_SIZE => 1024*16 + 5; # ~16k
@@ -2417,7 +2417,7 @@
warn "storing the remainder: $len bytes\n";
}
- return Apache::OK;
+ return Apache2::OK;
}
# split a string into tokens of TOKEN_SIZE bytes and a remainder
@@ -2467,11 +2467,11 @@
And here is the configuration for this setup:
- PerlModule MyApache::Underrun
+ PerlModule MyApache2::Underrun
<Location />
- PerlInputFilterHandler MyApache::Underrun::filter
+ PerlInputFilterHandler MyApache2::Underrun::filter
SetHandler modperl
- PerlResponseHandler MyApache::Underrun::response
+ PerlResponseHandler MyApache2::Underrun::response
</Location>
@@ -2505,10 +2505,10 @@
=head2 Connection Filters over KeepAlive Connections
Whenever a new HTTP request is processed, request filters get their
-context (C<L<$f-E<gt>ctx|docs::2.0::api::Apache::Filter/C_ctx_>>)
+context (C<L<$f-E<gt>ctx|docs::2.0::api::Apache2::Filter/C_ctx_>>)
reset. This is also true for connection filters context, as long as
the connection is not
-C<L<keepalive|docs::2.0::api::Apache::Connection/C_keepalive_>>). When
+C<L<keepalive|docs::2.0::api::Apache2::Connection/C_keepalive_>>). When
the connection is kept alive, there could be many requests processed
during a single connection and the same filter context will persist
through all of them, until the maximum number of KeepAlive requests
@@ -2517,7 +2517,7 @@
Sometimes it's desirable to reset the whole context or parts of it
before a HTTP request is processed. For example
-C<Apache::Filter::HTTPHeadersFixup> needs to know when it should start
+C<Apache2::Filter::HTTPHeadersFixup> needs to know when it should start
and stop processing HTTP headers. It keeps the state in the filter's
context. The problem is that whenever a new HTTP request is coming in,
it needs to be able to reset the state machine. If it doesn't, it'll
@@ -2525,19 +2525,19 @@
requests.
So let's say we have a hypothetical module
-C<MyApache::Filter::StateMachine> which implements an input connection
+C<MyApache2::Filter::StateMachine> which implements an input connection
filter, which processes incoming data as long as the I<state> flag is
down. Once that flag goes up the filter switches to the
pass-through-unmodified mode. Here is a skeleton of the module:
- #file:MyApache/Filter/StateMachine.pm
+ #file:MyApache2/Filter/StateMachine.pm
#------------------------------------
- package MyApache::Filter::StateMachine;
+ package MyApache2::Filter::StateMachine;
- use base qw(Apache::Filter);
- use Apache::Connection ();
+ use base qw(Apache2::Filter);
+ use Apache2::Connection ();
- use Apache::Const -compile => qw(OK DECLINED CONN_KEEPALIVE);
+ use Apache2::Const -compile => qw(OK DECLINED CONN_KEEPALIVE);
sub handler : FilterConnectionHandler {
my($f, $bb, $mode, $block, $readbytes) = @_;
@@ -2545,7 +2545,7 @@
my $ctx = context($f);
# pass through unmodified
- return Apache::DECLINED if $ctx->{state};
+ return Apache2::DECLINED if $ctx->{state};
# get data, do some processing, send it out
process(); # your code comes here
@@ -2553,7 +2553,7 @@
# change the state if some condition is reached
$ctx->{state}++ if $done_condition;
- return Apache::OK;
+ return Apache2::OK;
}
sub context {
@@ -2592,7 +2592,7 @@
}
my $c = $f->c;
- if ($c->keepalive == Apache::CONN_KEEPALIVE &&
+ if ($c->keepalive == Apache2::CONN_KEEPALIVE &&
$ctx->{state} && $c->keepalives > $ctx->{keepalives}) {
$ctx->{state} = 0;
Modified: perl/modperl/docs/trunk/src/docs/2.0/user/handlers/http.pod
URL: http://svn.apache.org/viewcvs/perl/modperl/docs/trunk/src/docs/2.0/user/handlers/http.pod?view=diff&r1=159847&r2=159848
==============================================================================
--- perl/modperl/docs/trunk/src/docs/2.0/user/handlers/http.pod (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/user/handlers/http.pod Sat Apr 2 15:32:19 2005
@@ -12,20 +12,20 @@
All HTTP Request handlers have the following structure:
- package MyApache::MyHandlerName;
+ package MyApache2::MyHandlerName;
# load modules that are going to be used
use ...;
# compile (or import) constants
- use Apache::Const -compile => qw(OK);
+ use Apache2::Const -compile => qw(OK);
sub handler {
my $r = shift;
# handler code comes here
- return Apache::OK; # or another status constant
+ return Apache2::OK; # or another status constant
}
1;
@@ -34,7 +34,7 @@
The handler itself coming next and usually it receives the only
argument: the
-C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> object.
+C<L<Apache2::RequestRec|docs::2.0::api::Apache2::RequestRec>> object.
If the handler is declared as L<a method handler
|docs::2.0::user::coding::coding/Method_Handlers>:
@@ -42,7 +42,7 @@
my($class, $r) = @_;
the handler receives two arguments: the class name and the
-C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> object.
+C<L<Apache2::RequestRec|docs::2.0::api::Apache2::RequestRec>> object.
The handler ends with L<a return
code|docs::2.0::user::handlers::intro/Stacked_Handlers> and the file
@@ -129,9 +129,9 @@
Before discussing each handler in detail remember that if you use
L<the stacked handlers
feature|docs::2.0::user::handlers::intro/Stacked_Handlers> all
-handlers in the chain will be run as long as they return C<Apache::OK>
-or C<Apache::DECLINED>. Because stacked handlers is a special case. So
-don't be surprised if you've returned C<Apache::OK> and the next
+handlers in the chain will be run as long as they return C<Apache2::OK>
+or C<Apache2::DECLINED>. Because stacked handlers is a special case. So
+don't be surprised if you've returned C<Apache2::OK> and the next
handler was still executed. This is a feature, not a bug.
Now let's discuss each of the mentioned handlers in detail.
@@ -143,7 +143,7 @@
parsed.
This phase is usually used to do processing that must happen once per
-request. For example C<Apache::Reload> is usually invoked at this
+request. For example C<Apache2::Reload> is usually invoked at this
phase to reload modified Perl modules.
This phase is of type
@@ -161,14 +161,14 @@
use strict;
use warnings;
- use Apache::ServerUtil ();
- use Apache::RequestIO ();
+ use Apache2::ServerUtil ();
+ use Apache2::RequestIO ();
use File::Spec::Functions qw(catfile);
my $r = shift;
$r->content_type('text/plain');
- my $conf_file = catfile Apache::ServerUtil::server_root,
+ my $conf_file = catfile Apache2::ServerUtil::server_root,
"conf", "httpd.conf";
printf "$conf_file is %0.2f minutes old\n", 60*24*(-M $conf_file);
@@ -197,21 +197,21 @@
be executed as the very first thing of each requests, comes handy
here:
- file:MyApache/TimeReset.pm
+ file:MyApache2/TimeReset.pm
--------------------------
- package MyApache::TimeReset;
+ package MyApache2::TimeReset;
use strict;
use warnings;
- use Apache::RequestRec ();
+ use Apache2::RequestRec ();
- use Apache::Const -compile => 'OK';
+ use Apache2::Const -compile => 'OK';
sub handler {
my $r = shift;
$^T = $r->request_time;
- return Apache::OK;
+ return Apache2::OK;
}
1;
@@ -225,7 +225,7 @@
To enable it just add to I<httpd.conf>:
- PerlPostReadRequestHandler MyApache::TimeReset
+ PerlPostReadRequestHandler MyApache2::TimeReset
either to the global section, or to the C<E<lt>VirtualHostE<gt>>
section if you want this handler to be run only for a specific virtual
@@ -272,16 +272,16 @@
the following handler can do the rewriting work transparent to
I<news.pl>, so you can still use the former URI mapping:
- file:MyApache/RewriteURI.pm
+ file:MyApache2/RewriteURI.pm
---------------------------
- package MyApache::RewriteURI;
+ package MyApache2::RewriteURI;
use strict;
use warnings;
- use Apache::RequestRec ();
+ use Apache2::RequestRec ();
- use Apache::Const -compile => qw(DECLINED);
+ use Apache2::Const -compile => qw(DECLINED);
sub handler {
my $r = shift;
@@ -290,13 +290,13 @@
$r->uri("/perl/news.pl");
$r->args("date=$date&id=$id&page=$page");
- return Apache::DECLINED;
+ return Apache2::DECLINED;
}
1;
The handler matches the URI and assigns a new URI via C<$r-E<gt>uri()>
and the query string via C<$r-E<gt>args()>. It then returns
-C<Apache::DECLINED>, so the next translation handler will get invoked,
+C<Apache2::DECLINED>, so the next translation handler will get invoked,
if more rewrites and translations are needed.
Of course if you need to do a more complicated rewriting, this handler
@@ -304,7 +304,7 @@
To configure this module simply add to I<httpd.conf>:
- PerlTransHandler +MyApache::RewriteURI
+ PerlTransHandler +MyApache2::RewriteURI
@@ -331,24 +331,24 @@
For example if you don't want Apache to try to attempt to translate
URI into a filename, just add a handler:
- PerlMapToStorageHandler MyApache::NoTranslation
+ PerlMapToStorageHandler MyApache2::NoTranslation
using the following code:
- file:MyApache/NoTranslation.pm
+ file:MyApache2/NoTranslation.pm
------------------------------
- package MyApache::NoTranslation;
+ package MyApache2::NoTranslation;
use strict;
use warnings FATAL => 'all';
- use Apache::Const -compile => qw(OK);
+ use Apache2::Const -compile => qw(OK);
sub handler {
my $r = shift;
# skip ap_directory_walk stat() calls
- return Apache::OK;
+ return Apache2::OK;
}
1;
@@ -356,24 +356,24 @@
shortcut it, C<TRACE> calls will be not handled. In case you need to
handle such, you may rewrite it as:
- file:MyApache/NoTranslation2.pm
+ file:MyApache2/NoTranslation2.pm
-------------------------------
- package MyApache::NoTranslation2;
+ package MyApache2::NoTranslation2;
use strict;
use warnings FATAL => 'all';
- use Apache::RequestRec ();
+ use Apache2::RequestRec ();
- use Apache::Const -compile => qw(DECLINED OK M_TRACE);
+ use Apache2::Const -compile => qw(DECLINED OK M_TRACE);
sub handler {
my $r = shift;
- return Apache::DECLINED if $r->method_number == Apache::M_TRACE;
+ return Apache2::DECLINED if $r->method_number == Apache2::M_TRACE;
# skip ap_directory_walk stat() calls
- return Apache::OK;
+ return Apache2::OK;
}
1;
@@ -429,27 +429,27 @@
C<L<PerlHeaderParserHandler|/PerlHeaderParserHandler>> phase:
<Location /email>
- PerlHeaderParserHandler MyApache::SendEmail
+ PerlHeaderParserHandler MyApache2::SendEmail
</Location>
-and here is the C<MyApache::SendEmail> handler:
+and here is the C<MyApache2::SendEmail> handler:
- file:MyApache/SendEmail.pm
+ file:MyApache2/SendEmail.pm
--------------------------
- package MyApache::SendEmail;
+ package MyApache2::SendEmail;
use strict;
use warnings;
- use Apache::RequestRec ();
- use Apache::RequestIO ();
- use Apache::RequestUtil ();
- use Apache::ServerUtil ();
- use Apache::ServerRec ();
- use Apache::Process ();
+ use Apache2::RequestRec ();
+ use Apache2::RequestIO ();
+ use Apache2::RequestUtil ();
+ use Apache2::ServerUtil ();
+ use Apache2::ServerRec ();
+ use Apache2::Process ();
use APR::Table ();
- use Apache::Const -compile => qw(DECLINED OK);
+ use Apache2::Const -compile => qw(DECLINED OK);
use constant METHOD => 'EMAIL';
use constant SMTP_HOSTNAME => "localhost";
@@ -457,13 +457,13 @@
sub handler {
my $r = shift;
- return Apache::DECLINED unless $r->method eq METHOD;
+ return Apache2::DECLINED unless $r->method eq METHOD;
$r->server->method_register(METHOD);
$r->handler("perl-script");
$r->push_handlers(PerlResponseHandler => \&send_email_handler);
- return Apache::OK;
+ return Apache2::OK;
}
sub send_email_handler {
@@ -476,13 +476,13 @@
$r->content_type('text/plain');
$r->print($status ? "ACK" : "NACK");
- return Apache::OK;
+ return Apache2::OK;
}
use APR::Brigade ();
use APR::Bucket ();
- use Apache::Const -compile => qw(MODE_READBYTES);
+ use Apache2::Const -compile => qw(MODE_READBYTES);
use APR::Const -compile => qw(SUCCESS BLOCK_READ);
use constant IOBUFSIZE => 8192;
@@ -495,7 +495,7 @@
my $data = '';
my $seen_eos = 0;
do {
- $r->input_filters->get_brigade($bb, Apache::MODE_READBYTES,
+ $r->input_filters->get_brigade($bb, Apache2::MODE_READBYTES,
APR::BLOCK_READ, IOBUFSIZE);
for (my $b = $bb->first; $b; $b = $bb->next($b)) {
@@ -530,12 +530,12 @@
request method is not equal to C<EMAIL> (set in the C<METHOD>
constant):
- return Apache::DECLINED unless $r->method eq METHOD;
+ return Apache2::DECLINED unless $r->method eq METHOD;
Next it tells Apache that this new method is a valid one and that the
C<perl-script> handler will do the processing.
- Apache::RequestUtil::method_register($r->server->process->pconf,
+ Apache2::RequestUtil::method_register($r->server->process->pconf,
METHOD);
$r->handler("perl-script");
@@ -550,7 +550,7 @@
The function terminates the header_parser phase by:
- return Apache::OK;
+ return Apache2::OK;
All other phases run as usual, so you can reuse any HTTP protocol
hooks, such as authentication and fixup phases.
@@ -569,11 +569,11 @@
Finally return to the client a simple response acknowledging that
email has been sent and finish the response phase by returning
-C<Apache::OK>:
+C<Apache2::OK>:
$r->content_type('text/plain');
$r->print($status ? "ACK" : "NACK");
- return Apache::OK;
+ return Apache2::OK;
Of course you will want to add extra validations if you want to use
this code in production. This is just a proof of concept
@@ -639,30 +639,30 @@
C<L<RUN_ALL|docs::2.0::user::handlers::intro/item_RUN_ALL>>.
The best example here would be to use
-C<L<Apache::Reload|docs::2.0::api::Apache::Reload>>
+C<L<Apache2::Reload|docs::2.0::api::Apache2::Reload>>
which takes the benefit of this directive. Usually
-C<L<Apache::Reload|docs::2.0::api::Apache::Reload>> is
+C<L<Apache2::Reload|docs::2.0::api::Apache2::Reload>> is
configured as:
- PerlInitHandler Apache::Reload
+ PerlInitHandler Apache2::Reload
PerlSetVar ReloadAll Off
- PerlSetVar ReloadModules "MyApache::*"
+ PerlSetVar ReloadModules "MyApache2::*"
which during the current HTTP request will monitor and reload all
-C<MyApache::*> modules that have been modified since the last HTTP
+C<MyApache2::*> modules that have been modified since the last HTTP
request. However if we move the global configuration into a
C<E<lt>LocationE<gt>> container:
<Location /devel>
- PerlInitHandler Apache::Reload
+ PerlInitHandler Apache2::Reload
PerlSetVar ReloadAll Off
- PerlSetVar ReloadModules "MyApache::*"
+ PerlSetVar ReloadModules "MyApache2::*"
SetHandler perl-script
PerlResponseHandler ModPerl::Registry
Options +ExecCGI
</Location>
-C<L<Apache::Reload|docs::2.0::api::Apache::Reload>> will
+C<L<Apache2::Reload|docs::2.0::api::Apache2::Reload>> will
reload the modified modules, only when a request to the I</devel>
namespace is issued, because C<L<PerlInitHandler|/PerlInitHandler>>
plays the role of
@@ -687,23 +687,23 @@
C<L<DIR|docs::2.0::user::config::config/item_DIR>>.
The concept behind access checker handler is very simple, return
-C<Apache::FORBIDDEN> if the access is not allowed, otherwise return
-C<Apache::OK>.
+C<Apache2::FORBIDDEN> if the access is not allowed, otherwise return
+C<Apache2::OK>.
The following example handler denies requests made from IPs on the
blacklist.
- file:MyApache/BlockByIP.pm
+ file:MyApache2/BlockByIP.pm
--------------------------
- package MyApache::BlockByIP;
+ package MyApache2::BlockByIP;
use strict;
use warnings;
- use Apache::RequestRec ();
- use Apache::Connection ();
+ use Apache2::RequestRec ();
+ use Apache2::Connection ();
- use Apache::Const -compile => qw(FORBIDDEN OK);
+ use Apache2::Const -compile => qw(FORBIDDEN OK);
my %bad_ips = map {$_ => 1} qw(127.0.0.1 10.0.0.4);
@@ -711,8 +711,8 @@
my $r = shift;
return exists $bad_ips{$r->connection->remote_ip}
- ? Apache::FORBIDDEN
- : Apache::OK;
+ ? Apache2::FORBIDDEN
+ : Apache2::OK;
}
1;
@@ -730,7 +730,7 @@
<Location /perl/>
SetHandler perl-script
PerlResponseHandler ModPerl::Registry
- PerlAccessHandler MyApache::BlockByIP
+ PerlAccessHandler MyApache2::BlockByIP
Options +ExecCGI
</Location>
@@ -741,7 +741,7 @@
I<httpd.conf>:
<Location />
- PerlAccessHandler MyApache::BlockByIP
+ PerlAccessHandler MyApache2::BlockByIP
</Location>
@@ -754,8 +754,8 @@
This phase is usually used to verify a user's identification
credentials. If the credentials are verified to be correct, the
-handler should return C<Apache::OK>. Otherwise the handler returns
-C<Apache::HTTP_UNAUTHORIZED> to indicate that the user has not
+handler should return C<Apache2::OK>. Otherwise the handler returns
+C<Apache2::HTTP_UNAUTHORIZED> to indicate that the user has not
authenticated successfully. When Apache sends the HTTP header with
this code, the browser will normally pop up a dialog box that prompts
the user for login information.
@@ -771,17 +771,17 @@
the supplied username and password and a single space equals to the
secret length, specified by the constant C<SECRET_LENGTH>.
- file:MyApache/SecretLengthAuth.pm
+ file:MyApache2/SecretLengthAuth.pm
---------------------------------
- package MyApache::SecretLengthAuth;
+ package MyApache2::SecretLengthAuth;
use strict;
use warnings;
- use Apache::Access ();
- use Apache::RequestUtil ();
+ use Apache2::Access ();
+ use Apache2::RequestUtil ();
- use Apache::Const -compile => qw(OK DECLINED HTTP_UNAUTHORIZED);
+ use Apache2::Const -compile => qw(OK DECLINED HTTP_UNAUTHORIZED);
use constant SECRET_LENGTH => 14;
@@ -789,19 +789,19 @@
my $r = shift;
my ($status, $password) = $r->get_basic_auth_pw;
- return $status unless $status == Apache::OK;
+ return $status unless $status == Apache2::OK;
- return Apache::OK
+ return Apache2::OK
if SECRET_LENGTH == length join " ", $r->user, $password;
$r->note_basic_auth_failure;
- return Apache::HTTP_UNAUTHORIZED;
+ return Apache2::HTTP_UNAUTHORIZED;
}
1;
First the handler retrieves the status of the authentication and the
-password in plain text. The status will be set to C<Apache::OK> only
+password in plain text. The status will be set to C<Apache2::OK> only
when the user has supplied the username and the password
credentials. If the status is different, we just let Apache handle
this situation for us, which will usually challenge the client so
@@ -840,7 +840,7 @@
storing passwords in clear is a bad idea.
Finally if our authentication fails the handler calls
-note_basic_auth_failure() and returns C<Apache::HTTP_UNAUTHORIZED>, which
+note_basic_auth_failure() and returns C<Apache2::HTTP_UNAUTHORIZED>, which
sets the proper HTTP response headers that tell the client that its
user that the authentication has failed and the credentials should be
supplied again.
@@ -862,7 +862,7 @@
<Location /perl/>
SetHandler perl-script
PerlResponseHandler ModPerl::Registry
- PerlAuthenHandler MyApache::SecretLengthAuth
+ PerlAuthenHandler MyApache2::SecretLengthAuth
Options +ExecCGI
AuthType Basic
@@ -877,7 +877,7 @@
example for any requests to the site, simply use:
<Location />
- PerlAuthenHandler MyApache::SecretLengthAuth
+ PerlAuthenHandler MyApache2::SecretLengthAuth
AuthType Basic
AuthName "The Gate"
Require valid-user
@@ -895,9 +895,9 @@
As this phase is tightly connected to the authentication phase, the
handlers registered for this phase are only called when the requested
resource is password protected, similar to the auth phase. The handler
-is expected to return C<Apache::DECLINED> to defer the decision,
-C<Apache::OK> to indicate its acceptance of the user's authorization,
-or C<Apache::HTTP_UNAUTHORIZED> to indicate that the user is not
+is expected to return C<Apache2::DECLINED> to defer the decision,
+C<Apache2::OK> to indicate its acceptance of the user's authorization,
+or C<Apache2::HTTP_UNAUTHORIZED> to indicate that the user is not
authorized to access the requested document.
This phase is of type
@@ -906,21 +906,21 @@
The handler's configuration scope is
C<L<DIR|docs::2.0::user::config::config/item_DIR>>.
-Here is the C<MyApache::SecretResourceAuthz> handler which grants
+Here is the C<MyApache2::SecretResourceAuthz> handler which grants
access to certain resources only to certain users who have already
properly authenticated:
- file:MyApache/SecretResourceAuthz.pm
+ file:MyApache2/SecretResourceAuthz.pm
------------------------------------
- package MyApache::SecretResourceAuthz;
+ package MyApache2::SecretResourceAuthz;
use strict;
use warnings;
- use Apache::Access ();
- use Apache::RequestUtil ();
+ use Apache2::Access ();
+ use Apache2::RequestUtil ();
- use Apache::Const -compile => qw(OK HTTP_UNAUTHORIZED);
+ use Apache2::Const -compile => qw(OK HTTP_UNAUTHORIZED);
my %protected = (
'admin' => ['stas'],
@@ -935,15 +935,15 @@
my($section) = $r->uri =~ m|^/company/(\w+)/|;
if (defined $section && exists $protected{$section}) {
my $users = $protected{$section};
- return Apache::OK if grep { $_ eq $user } @$users;
+ return Apache2::OK if grep { $_ eq $user } @$users;
}
else {
- return Apache::OK;
+ return Apache2::OK;
}
}
$r->note_basic_auth_failure;
- return Apache::HTTP_UNAUTHORIZED;
+ return Apache2::HTTP_UNAUTHORIZED;
}
1;
@@ -963,7 +963,7 @@
authentication fails, i.e, calls:
$r->note_basic_auth_failure;
- return Apache::HTTP_UNAUTHORIZED;
+ return Apache2::HTTP_UNAUTHORIZED;
The configuration is similar to the one in L<the previous
section|/PerlAuthenHandler>, this time we just add the
@@ -973,8 +973,8 @@
<Location /company/>
SetHandler perl-script
PerlResponseHandler ModPerl::Registry
- PerlAuthenHandler MyApache::SecretLengthAuth
- PerlAuthzHandler MyApache::SecretResourceAuthz
+ PerlAuthenHandler MyApache2::SecretLengthAuth
+ PerlAuthzHandler MyApache2::SecretResourceAuthz
Options +ExecCGI
AuthType Basic
@@ -986,8 +986,8 @@
whole site, simply add:
<Location />
- PerlAuthenHandler MyApache::SecretLengthAuth
- PerlAuthzHandler MyApache::SecretResourceAuthz
+ PerlAuthenHandler MyApache2::SecretLengthAuth
+ PerlAuthzHandler MyApache2::SecretResourceAuthz
AuthType Basic
AuthName "The Secret Gate"
Require valid-user
@@ -1032,7 +1032,7 @@
depending on which type of response handler is wanted.
Writing a C<PerlTypeHandler> handler which sets the content-type value
-and returns C<Apache::DECLINED> so that the default handler will do
+and returns C<Apache2::DECLINED> so that the default handler will do
the rest of the work, is not a good idea, because mod_mime will
probably override this and other settings.
@@ -1060,18 +1060,18 @@
handler and callback should be used to process the request based on
the file extension of the request's URI.
- file:MyApache/FileExtDispatch.pm
+ file:MyApache2/FileExtDispatch.pm
--------------------------------
- package MyApache::FileExtDispatch;
+ package MyApache2::FileExtDispatch;
use strict;
use warnings;
- use Apache::RequestIO ();
- use Apache::RequestRec ();
- use Apache::RequestUtil ();
+ use Apache2::RequestIO ();
+ use Apache2::RequestRec ();
+ use Apache2::RequestUtil ();
- use Apache::Const -compile => 'OK';
+ use Apache2::Const -compile => 'OK';
use constant HANDLER => 0;
use constant CALLBACK => 1;
@@ -1095,7 +1095,7 @@
$r->set_handlers(PerlResponseHandler => $exts{$ext}->[CALLBACK]);
}
- return Apache::OK;
+ return Apache2::OK;
}
sub cgi_handler { content_handler($_[0], 'cgi') }
@@ -1108,7 +1108,7 @@
$r->content_type('text/plain');
$r->print("A handler of type '$type' was called");
- return Apache::OK;
+ return Apache2::OK;
}
1;
@@ -1152,7 +1152,7 @@
Alias /dispatch/ /home/httpd/httpd-2.0/htdocs/
<Location /dispatch/>
- PerlFixupHandler MyApache::FileExtDispatch
+ PerlFixupHandler MyApache2::FileExtDispatch
</Location>
Notice that there is no need to specify anything, but the fixup
@@ -1172,7 +1172,7 @@
<Location /perl>
SetHandler perl-script
- PerlResponseHandler MyApache::WorldDomination
+ PerlResponseHandler MyApache2::WorldDomination
</Location>
C<SetHandler> set to
@@ -1196,18 +1196,18 @@
content. This time let's do something more interesting than printing
I<"Hello world">. Let's write a handler that prints itself:
- file:MyApache/Deparse.pm
+ file:MyApache2/Deparse.pm
------------------------
- package MyApache::Deparse;
+ package MyApache2::Deparse;
use strict;
use warnings;
- use Apache::RequestRec ();
- use Apache::RequestIO ();
+ use Apache2::RequestRec ();
+ use Apache2::RequestIO ();
use B::Deparse ();
- use Apache::Const -compile => 'OK';
+ use Apache2::Const -compile => 'OK';
sub handler {
my $r = shift;
@@ -1215,7 +1215,7 @@
$r->content_type('text/plain');
$r->print('sub handler ', B::Deparse->new->coderef2text(\&handler));
- return Apache::OK;
+ return Apache2::OK;
}
1;
@@ -1223,14 +1223,14 @@
<Location /deparse>
SetHandler modperl
- PerlResponseHandler MyApache::Deparse
+ PerlResponseHandler MyApache2::Deparse
</Location>
Now when the server is restarted and we issue a request to
I<http://localhost/deparse> we get the following response:
sub handler {
- package MyApache::Deparse;
+ package MyApache2::Deparse;
use warnings;
use strict 'refs';
my $r = shift @_;
@@ -1268,46 +1268,46 @@
I</users/username/>, so it's easy to categorize requests by the second
URI path component. Here is the log handler that does that:
- file:MyApache/LogPerUser.pm
+ file:MyApache2/LogPerUser.pm
---------------------------
- package MyApache::LogPerUser;
+ package MyApache2::LogPerUser;
use strict;
use warnings;
- use Apache::RequestRec ();
- use Apache::Connection ();
+ use Apache2::RequestRec ();
+ use Apache2::Connection ();
use Fcntl qw(:flock);
use File::Spec::Functions qw(catfile);
- use Apache::Const -compile => qw(OK DECLINED);
+ use Apache2::Const -compile => qw(OK DECLINED);
sub handler {
my $r = shift;
my($username) = $r->uri =~ m|^/users/([^/]+)|;
- return Apache::DECLINED unless defined $username;
+ return Apache2::DECLINED unless defined $username;
my $entry = sprintf qq(%s [%s] "%s" %d %d\n),
$r->connection->remote_ip, scalar(localtime),
$r->uri, $r->status, $r->bytes_sent;
- my $log_path = catfile Apache::ServerUtil::server_root,
+ my $log_path = catfile Apache2::ServerUtil::server_root,
"logs", "$username.log";
open my $fh, ">>$log_path" or die "can't open $log_path: $!";
flock $fh, LOCK_EX;
print $fh $entry;
close $fh;
- return Apache::OK;
+ return Apache2::OK;
}
1;
First the handler tries to figure out what username the request is
issued for, if it fails to match the URI, it simply returns
-C<Apache::DECLINED>, letting other log handlers to do the
-logging. Though it could return C<Apache::OK> since all other log
+C<Apache2::DECLINED>, letting other log handlers to do the
+logging. Though it could return C<Apache2::OK> since all other log
handlers will be run anyway.
Next it builds the log entry, similar to the default I<access_log>
@@ -1329,7 +1329,7 @@
<Location /users/>
SetHandler perl-script
PerlResponseHandler ModPerl::Registry
- PerlLogHandler MyApache::LogPerUser
+ PerlLogHandler MyApache2::LogPerUser
Options +ExecCGI
</Location>
@@ -1340,7 +1340,7 @@
http://localhost/users/eric/test.pl
http://localhost/users/stas/date.pl
-The C<MyApache::LogPerUser> handler will append to I<logs/stas.log>:
+The C<MyApache2::LogPerUser> handler will append to I<logs/stas.log>:
127.0.0.1 [Sat Aug 31 01:50:38 2002] "/users/stas/test.pl" 200 8
127.0.0.1 [Sat Aug 31 01:50:40 2002] "/users/stas/date.pl" 200 44
@@ -1356,7 +1356,7 @@
I<httpd.conf>:
<Location />
- PerlLogHandler MyApache::LogPerUser
+ PerlLogHandler MyApache2::LogPerUser
</Location>
Since the C<PerlLogHandler> phase is of type
@@ -1390,7 +1390,7 @@
=item 1 Using the C<PerlCleanupHandler> phase
- PerlCleanupHandler MyApache::Cleanup
+ PerlCleanupHandler MyApache2::Cleanup
or:
@@ -1426,20 +1426,20 @@
C<push_handlers()> to push C<PerlCleanupHandler> to unlink the file at
the end of the request.
- #file:MyApache/Cleanup1.pm
+ #file:MyApache2/Cleanup1.pm
#-------------------------
- package MyApache::Cleanup1;
+ package MyApache2::Cleanup1;
use strict;
use warnings FATAL => 'all';
use File::Spec::Functions qw(catfile);
- use Apache::RequestRec ();
- use Apache::RequestIO ();
- use Apache::RequestUtil ();
+ use Apache2::RequestRec ();
+ use Apache2::RequestIO ();
+ use Apache2::RequestUtil ();
- use Apache::Const -compile => qw(OK DECLINED);
+ use Apache2::Const -compile => qw(OK DECLINED);
use APR::Const -compile => 'SUCCESS';
my $file = catfile "/tmp", "data";
@@ -1457,7 +1457,7 @@
$r->push_handlers(PerlCleanupHandler => \&cleanup);
- return Apache::OK;
+ return Apache2::OK;
}
sub cleanup {
@@ -1466,7 +1466,7 @@
die "Can't find file: $file" unless -e $file;
unlink $file or die "failed to unlink $file";
- return Apache::OK;
+ return Apache2::OK;
}
1;
@@ -1474,7 +1474,7 @@
<Location /cleanup1>
SetHandler modperl
- PerlResponseHandler MyApache::Cleanup1
+ PerlResponseHandler MyApache2::Cleanup1
</Location>
Now when a request to I</cleanup1> is made, the contents of the
@@ -1492,9 +1492,9 @@
names across threads and processes:
sub unique_id {
- require Apache::MPM;
+ require Apache2::MPM;
require APR::OS;
- return Apache::MPM->is_threaded
+ return Apache2::MPM->is_threaded
? "$$." . ${ APR::OS::thread_current() }
: $$;
}
@@ -1521,22 +1521,22 @@
better version of the response and cleanup handlers, that uses this
technique:
- #file:MyApache/Cleanup2.pm
+ #file:MyApache2/Cleanup2.pm
#-------------------------
- package MyApache::Cleanup2;
+ package MyApache2::Cleanup2;
use strict;
use warnings FATAL => 'all';
use File::Spec::Functions qw(catfile);
- use Apache::RequestRec ();
- use Apache::RequestIO ();
- use Apache::RequestUtil ();
+ use Apache2::RequestRec ();
+ use Apache2::RequestIO ();
+ use Apache2::RequestUtil ();
use APR::UUID ();
use APR::Pool ();
- use Apache::Const -compile => qw(OK DECLINED);
+ use Apache2::Const -compile => qw(OK DECLINED);
use APR::Const -compile => 'SUCCESS';
my $file_base = catfile "/tmp", "data-";
@@ -1555,7 +1555,7 @@
$r->pool->cleanup_register(\&cleanup, $file);
- return Apache::OK;
+ return Apache2::OK;
}
sub cleanup {
@@ -1564,7 +1564,7 @@
die "Can't find file: $file" unless -e $file;
unlink $file or die "failed to unlink $file";
- return Apache::OK;
+ return Apache2::OK;
}
1;
@@ -1572,7 +1572,7 @@
<Location /cleanup2>
SetHandler modperl
- PerlResponseHandler MyApache::Cleanup2
+ PerlResponseHandler MyApache2::Cleanup2
</Location>
And now when requesting I</cleanup2> we still get the same output --
@@ -1606,7 +1606,7 @@
early|docs::1.0::guide::porting/Generating_correct_HTTP_Headers> from
the handler:
- return Apache::OK if $r->header_only;
+ return Apache2::OK if $r->header_only;
This logic should not be used in mod_perl 2.0, because Apache 2.0
automatically discards the response body for HEAD requests. It expects
Modified: perl/modperl/docs/trunk/src/docs/2.0/user/handlers/intro.pod
URL: http://svn.apache.org/viewcvs/perl/modperl/docs/trunk/src/docs/2.0/user/handlers/intro.pod?view=diff&r1=159847&r2=159848
==============================================================================
--- perl/modperl/docs/trunk/src/docs/2.0/user/handlers/intro.pod (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/user/handlers/intro.pod Sat Apr 2 15:32:19 2005
@@ -23,17 +23,17 @@
A typical handler is simply a perl package with a I<handler>
subroutine. For example:
- file:MyApache/CurrentTime.pm
+ file:MyApache2/CurrentTime.pm
----------------------------
- package MyApache::CurrentTime;
+ package MyApache2::CurrentTime;
use strict;
use warnings;
- use Apache::RequestRec ();
- use Apache::RequestIO ();
+ use Apache2::RequestRec ();
+ use Apache2::RequestIO ();
- use Apache::Const -compile => qw(OK);
+ use Apache2::Const -compile => qw(OK);
sub handler {
my $r = shift;
@@ -41,7 +41,7 @@
$r->content_type('text/plain');
$r->print("Now is: " . scalar(localtime) . "\n");
- return Apache::OK;
+ return Apache2::OK;
}
1;
@@ -51,15 +51,15 @@
Since this is a response handler, we configure it as a such in
I<httpd.conf>:
- PerlResponseHandler MyApache::CurrentTime
+ PerlResponseHandler MyApache2::CurrentTime
Since the response handler should be configured for a specific
location, let's write a complete configuration section:
- PerlModule MyApache::CurrentTime
+ PerlModule MyApache2::CurrentTime
<Location /time>
SetHandler modperl
- PerlResponseHandler MyApache::CurrentTime
+ PerlResponseHandler MyApache2::CurrentTime
</Location>
Now when a request is issued to I<http://localhost/time> this response
@@ -79,32 +79,32 @@
value -- things will change in the future and you won't know why
things aren't working anymore.
-The only value that can be returned by all handlers is C<Apache::OK>,
+The only value that can be returned by all handlers is C<Apache2::OK>,
which tells Apache that the handler has successfully finished its
execution.
-C<Apache::DECLINED> is another return value that indicates success,
+C<Apache2::DECLINED> is another return value that indicates success,
but it's only relevant for
L<phases|docs::2.0::user::handlers::intro/Stacked_Handlers>
of type C<L<RUN_FIRST|/RUN_FIRST>>.
L<HTTP handlers|docs::2.0::user::handlers::http> may also return
-C<Apache::DONE> which tells Apache to stop the normal L<HTTP request
+C<Apache2::DONE> which tells Apache to stop the normal L<HTTP request
cycle|docs::2.0::user::handlers::http/HTTP_Request_Cycle_Phases> and
fast forward to the
C<L<PerlLogHandler|docs::2.0::user::handlers::http/PerlLogHandler>>,
followed by
C<L<PerlCleanupHandler|docs::2.0::user::handlers::http/PerlCleanupHandler>>.
L<HTTP handlers|docs::2.0::user::handlers::http> may return any HTTP
-status, which similarly to C<Apache::DONE> will cause an abort of the
+status, which similarly to C<Apache2::DONE> will cause an abort of the
request cycle, by also will be interpreted as an error. Therefore you
-don't want to return C<Apache::HTTP_OK> from your HTTP response
-handler, but C<Apache::OK> and Apache will send the C<200 OK> status
+don't want to return C<Apache2::HTTP_OK> from your HTTP response
+handler, but C<Apache2::OK> and Apache will send the C<200 OK> status
by itself.
L<Filter handlers|docs::2.0::user::handlers::filters> return
-C<Apache::OK> to indicate that the filter has successfully
-finished. If the return value is C<Apache::DECLINED>, mod_perl will
+C<Apache2::OK> to indicate that the filter has successfully
+finished. If the return value is C<Apache2::DECLINED>, mod_perl will
read and forward the data on behalf of the filter. Please notice that
this feature is specific to mod_perl. If there is some problem with
obtaining or sending the bucket brigades, or the buckets in it,
@@ -116,12 +116,12 @@
aren't really handled by Apache, the handler is supposed to take care
of any errors by itself. The only special case is the
C<L<PerlPreConnectionHandler|docs::2.0::user::handlers::protocols/PerlPreConnectionHandler>>
-handler, which, if returning anything but C<Apache::OK> or
-C<Apache::DONE>, will prevent from
+handler, which, if returning anything but C<Apache2::OK> or
+C<Apache2::DONE>, will prevent from
C<L<PerlConnectionHandler|docs::2.0::user::handlers::protocols/PerlConnectionHandler>>
to be
run. C<L<PerlPreConnectionHandler|docs::2.0::user::handlers::protocols/PerlPreConnectionHandler>>
-handlers should always return C<Apache::OK>.
+handlers should always return C<Apache2::OK>.
@@ -271,22 +271,22 @@
Handlers of the type C<VOID> will be I<all> executed in the order they
have been registered disregarding their return values. Though in
-mod_perl they are expected to return C<Apache::OK>.
+mod_perl they are expected to return C<Apache2::OK>.
=head2 C<RUN_FIRST>
Handlers of the type C<RUN_FIRST> will be executed in the order they
have been registered until the first handler that returns something
-other than C<Apache::DECLINED>. If the return value is
-C<Apache::DECLINED>, the next handler in the chain will be run. If the
-return value is C<Apache::OK> the next phase will start. In all other
+other than C<Apache2::DECLINED>. If the return value is
+C<Apache2::DECLINED>, the next handler in the chain will be run. If the
+return value is C<Apache2::OK> the next phase will start. In all other
cases the execution will be aborted.
=head2 C<RUN_ALL>
Handlers of the type C<RUN_ALL> will be executed in the order they
have been registered until the first handler that returns something
-other than C<Apache::OK> or C<Apache::DECLINED>.
+other than C<Apache2::OK> or C<Apache2::DECLINED>.
For C API declarations see I<include/ap_config.h>, which includes
other types which aren't exposed by mod_perl handlers.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org