view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    When you've got this module, you can use the same handler both as a
    stand-alone handler, and as an element in a chain. Just make sure that
    whenever you're chaining, all the handlers in the chain are "Filter-aware,"
    i.e. they each call $r->filter_register() exactly once, before they start
    printing to STDOUT. There should be almost no overhead for doing this when
    there's only one element in the chain.

    Currently the following public modules are Filter-aware. Please tell me of
    others you know about.

     Apache::Registry (using Apache::RegistryFilter, included here)
     Apache::SSI
     Apache::ASP
     HTML::Mason
     Apache::SimpleReplace
     Apache::HTML::ClassParser (part of HTML_Tree distribution)

METHODS
    Apache::Filter is a subclass of Apache, so all Apache methods are available.

    This module doesn't create an Apache handler class of its own - rather, it
    adds some methods to the Apache:: class. Thus, it's really a mix-in package
    that just adds functionality to the $r request object.

    * $r = $r->filter_register()
        Every Filter-aware module must call this method exactly once, so that
        Apache::filter can properly rotate its filters from previous handlers,
        and so it can know when the output should eventually go to the browser.

    * $r->filter_input()
        This method will give you a filehandle that contains either the file
        requested by the user ($r->filename), or the output of a previous
        filter. If called in a scalar context, that filehandle is all you'll get
        back. If called in a list context, you'll also get an Apache status code
        (OK, NOT_FOUND, or FORBIDDEN) that tells you whether $r->filename was
        successfully found and opened. If it was not, the filehandle returned
        will be undef.

    * $r->changed_since($time)
        Returns true or false based on whether the current input seems like it
        has changed since "$time". Currently the criteria to figure this out is
        this: if the file pointed to by "$r->finfo" hasn't changed since the
        time given, and if all previous filters in the chain are deterministic
        (see below), then we return false. Otherwise we return true.

        This method is meant to be useful in implementing caching schemes.

        A caution: always call the "changed_since()" and "deterministic()"
        methods AFTER the "filter_register()" method. This is because
        Apache::Filter uses a crude counting method to figure out which handler
        in the chain is currently executing, and calling these routines out of
        order messes up the counting.

    * $r->deterministic(1|0);
        As of version 0.07, the concept of a "deterministic" filter is
        supported. A deterministic filter is one whose output is entirely
        determined by the contents of its input file (whether the $r->filename
        file or the output of another filter), and doesn't depend at all on
        outside factors. For example, a filter that translates all its output to
        upper-case is deterministic, but a filter that adds a date stamp to a
        page, or looks things up in a database which may vary over time, is not.

        Why is this a big deal? Let's say you have the following setup:

         <Files ~ "\.boffo$">
          SetHandler perl-script
          PerlSetVar Filter On
          PerlHandler Apache::FormatNumbers Apache::DoBigCalculation
          # The above are fake modules, you get the idea
         </Files>

        Suppose the FormatNumbers module is deterministic, and the
        DoBigCalculation module takes a long time to run. The DoBigCalculation
        module can now cache its results, so that when an input file is
        unchanged on disk, its results will remain known when passed through the
        FormatNumbers module, and the DoBigCalculation module will be able to
        used cached results from a previous run.

        The guts of the modules would look something like this:

         sub Apache::FormatNumbers::handler {
            my $r = shift;
            $r->content_type("text/html");
            my ($fh, $status) = $r->filter_input();
            return $status unless $status == OK;
            $r->deterministic(1); # Set to true; default is false
    
            # ... do some formatting, print to STDOUT
            return OK;
         }
 
         sub Apache::DoBigCalculation::handler {
            my $r = shift;
            $r->content_type("text/html");
            my ($fh, $status) = $r->filter_input();
            return $status unless $status == OK;
    
            # This module implements a caching scheme by using the 
            # %cache_time and %cache_content hashes.
            my $time = $cache_time{$r->filename};
            my $output;
            if ($r->changed_since($time)) {
                # Read from <$fh>, perform a big calculation on it, and print to STDOUT
            } else {
                print $cache_content{$r->filename};
            }
    
            return OK;
         }

        A caution: always call the "changed_since()" and "deterministic()"
        methods AFTER the "filter_register()" method. This is because
        Apache::Filter uses a crude counting method to figure out which handler
        in the chain is currently executing, and calling these routines out of
        order messes up the counting.

HEADERS
    In previous releases of this module, it was dangerous to call
    $r->send_http_header(), because a previous/postvious filter might also try
    to send headers, and then you'd have duplicate headers getting sent. In
    current releases you can simply send the headers. If the current filter is