perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ran...@apache.org
Subject 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
Date Sat, 02 Apr 2005 23:32:21 GMT
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


Mime
View raw message