[ANNOUNCE] MasonX::Apache2Handler

[be...@beaucox.com]

I am happy to announce the the following modules for running
Mason under Apache 2 / mod_perl 2 with the native Apache 2 request
handler (libapreq2).

  MasonX::Apache2Handler-0.04
  MasonX::Request::WithApache2Session-0.04

These modules are currently on my site at:

 <http://beaucox.com/mason>

and will be submitted to CPAN in the next few days.

In addition, buffer flushing has been tweaked to work correctly
with Apache 2 / mod_perl 2 so that '$m->redirect( $url ); is
functional.

Partial documentation:

NAME
    MasonX::Apache2Handler - experimental (beta) Mason/mod_perl2 interface

SYNOPSIS
        use MasonX::Apache2Handler;
 
        my $ah = MasonX::Apache2Handler->new (..name/value params..);
        ...
        sub handler {
           my $r = shift;
           $ah->handle_request($r);
        }

DESCRIPTION
    MasonX::Apache2Handler is experimental ( beta ) and should only be used
    in a test environment. The MasonX::Apache2Handler module itself is a
    simple clone of Mason's HTML::Mason::ApacheHandler, and, as such, seems
    to be solid. However the components used, mod_perl 2 and libapreq2, are
    currently under development each give a version of the above warning.

    If you are interested in moving to mod_perl 2 when it reaches production
    status, I encourage you to try these modules in a test environment; your
    feedback will help getting mod_perl 2 out the door. I have been using
    this module on two live sites since mid-January 2004, with no problems.

    MasonX::Apache2Handler was written to allow Mason to run in a 'pure'
    mod_perl2/Apache2 environment using the mod_perl2 native request
    structure as implemented by libapreq2. This is an unofficial release,
    not supported by the Mason group. If you want to use this module in a
    testing environment, please address problems, issues, comments, and
    improvements to me, not Mason.

    When deciding to port Mason to mod_perl2 I took the approach to add
    Module(s) rather than patching core Mason modules. Upon investigation I
    discovered that all the Apache 'glue' code in Mason was contained in
    HTML::Mason::ApacheHandler. Therefore, I renamed and modified that
    module to create MasonX::Apache2Handler.

    The actual changes I made can be found in the distribution in
    diff/ApacheHandler.diff ( made with 'diff -Naru' ... ).

    As a result of my approach, you may install the normal Mason ( >= 1.25
    ), the modules in "PREREQUISITES" below, and this module. After
    configuring ( see "CONFIGURATION" below ), you're ready to play.

    The Apache2Handler object links Mason to mod_perl2, running components
    in response to HTTP requests. It is controlled primarily through
    parameters to the new() constructor.

    handle_request() is not a user method, but rather is called from the
    HTML::Mason::handler() routine in handler.pl.

    MasonX::Apache2Handler is a modified copy of the standard
    HTML::Mason::ApacheHandler. Apache2Handler MUST be used with mod_perl2.

    You may, however, run Mason with Apache2/mod_perl2 without
    Apache2Handler (see my rather dated mini-HOWTO at
    <http://beaucox.com/mason/mason-with-apmp2-mini-HOWTO.htm>), but you
    then use use 'CGI' requests rather than the native 'mod_perl' requests.

    The interface is the same as ApacheHandler's, Please refer to
    HTML::Mason, HTML::Mason::ApacheHandler, and
    <http://masonhq.com/docs/manual/Admin.html>.

NAME CHANGE
    I have changed module names and released them as version 0.04 as perl
    Mason's request:

        HTML::Mason::ApacheHandler2 =>
            MasonX::Apache2Handler

        MasonX::Request::WithApacheSession2 =>
            MasonX::Request::WithApache2Session

    These changes keep my modules out of the 'core' Mason namespace. Those
    of you who have installed my prior modules are encouraged to install the
    new modules and make the necessary changes to the configuration files
    and scripts.

PREREQUISITES
    You must have the following packages installed:

        perl            => 5.8.0
        mod_perl        => 1.9910
        HTML::Mason     => 1.25
        libapreq2       => 2.02-dev

    Please refer to the packages' documentation for instructions.

WARNING: PERL 5.8.2
    If you are using perl 5.8.2 you may get a series of errors in the
    http/error_log such as:

        Attempt to free unreferenced scalar: SV 0x405e6e78
         at /usr/lib/perl5/site_perl/5.8.2/HTML/Mason/Request.pm line 160.
        ...
        [Fri Jan 30 09:41:58 2004] [error] [client 207.175.219.202]
         Attempt to free unreferenced scalar: SV 0x405e6e78
         at /usr/lib/perl5/site_perl/5.8.2/i686-linux-thread-multi/
         Apache/Cookie.pm line 67.
  
        Stack:
          [/usr/lib/perl5/site_perl/5.8.2/MasonX/Apache2Handler.pm:892]
          [/usr/lib/perl5/site_perl/5.8.2/MasonX/Apache2Handler.pm:801]
          [/srv/www/perl/MyApache/Mason/Apache2Handler.pm:86]
          [-e:0]

    which may return a 500 Internal Server Error to the user.

    There was a bug introduced in perl 5.8.2 and fixed in 5.8.3, which
    affects some XS modules running under a threaded mpm mod_perl 2.0 (or
    any ithreads perl application). The affected modules can be fixed, to
    avoid this problem, by using the PERL_NO_GET_CONTEXT macro in the XS
    code (see the perlguts manpage for more information). So you need to
    check whether a newer version of the module is available. If not you
    need to upgrade to perl 5.8.3 or higher and the problem will go away.

    When I had these problems, I ended up upgrading to 5.8.3 and recompiling
    EVERY CPAN module I use and remaking mod_perl2. You may have to do the
    same thing.

    Perl 5.8.0 and 5.8.1 operate correctly, the problem is manifested in
    5.8.2.

FLUSH BUFFER AND REDIRECTS
    I have 'subclassed' HTML::Mason::Request (as MasonX::Request2) and
    HTML::Mason::Buffer (as MasonX::Buffer2) to change handling of buffer
    flushing as per Johnathan Kupferer's suggestion (see
    http://marc.theaimsgroup.com/?l=mason-devel&m=105337019427296&w=2).
    Basically the buffer is flushed only if there is really anything to
    flush, which clears the way for $m->redirect( $url );.

    I have tested this change extensively and found it to be solid. You may
    wish to uncomment the "print STDERR ..." statements in Burrer2 and
    Request2 if you wish to see the flushing process at work (or you still
    have redirect problems). The print STDERR's appear in the Apache log.

CONFIGURATION
...

Aloha => Beau;


-- 
Report problems: http://perl.apache.org/bugs/
Mail list info: http://perl.apache.org/maillist/modperl.html
List etiquette: http://perl.apache.org/maillist/email-etiquette.html