=head1 NAME

HTML::Mason::ApacheHandler - Mason/mod_perl interface

=head1 SYNOPSIS

    use HTML::Mason::ApacheHandler;

    my $ah = new HTML::Mason::ApacheHandler (..name/value params..);
    ...
    sub handler {
        my $r = shift;
        $ah->handle_request($r);
    }

=head1 DESCRIPTION

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

=head1 PARAMETERS TO THE use() DECLARATION

The following are parameters to pass explicitly when using
HTML::Mason::ApacheHandler. e.g.

    use HTML::Mason::ApacheHandler (args_method=>'mod_perl');

=over

=item args_method

Method to use for unpacking GET and POST arguments. The valid options
are 'CGI' and 'mod_perl'; these indicate that a CGI.pm or
Apache::Request object (respectively) will be created for the purposes
of argument handling. These objects are, unfortunately, not yet
accessible from components.

'CGI' is the default and should work on most Perl systems. However,
if you have the Apache::Request package (or are inclined to fetch it
from CPAN), you might switch to 'mod_perl' for speed and memory
efficiency.

When specifying args_method='CGI', the Mason request object ($m)
will have a method called C<cgi_object> available.  This method
returns the CGI object used in the ApacheHandler code.

When specifying args_method='mod_perl', the $r global is upgraded
to an Apache::Request object. This object inherits all Apache
methods and adds a few of its own, dealing with parameters and
file uploads. See Apache::Request manual page for more information.

=back

=head1 PARAMETERS TO THE new() CONTRUCTOR

=over

=item apache_status_title

Title that you want this ApacheHandler to appear as under
Apache::Status.  Default is "HTML::Mason status".  This is useful if
you create more then one ApacheHandler object and want them all
visible via Apache::Status.

=item auto_send_headers

True or undef; default true.  Indicates whether Mason should
automatically send HTTP headers before sending content back to the
client. If you set to false, you should call $r->send_http_header
manually.

See the Devel/sending_http_headers of the Component Developer's
Guide for details about the automatic header feature.

=item debug_handler_proc, debug_handler_script, debug_mode, debug_perl_binary

The B<debug_*> parameters control Mason's use of debug files.
Component Admin/debugging procedures are fully described in the I<Mason
Administrator's Guide>.

=item decline_dirs

Indicates whether Mason should decline directory requests, leaving
Apache to serve up a directory index or a FORBIDDEN error as
appropriate. Default is 1. See Admin/Allowing directory requests
for more information about handling directories with Mason.

=item error_mode

Specifies how to handle Perl errors. Options are 'html', 'fatal',
'raw_html', and 'raw_fatal'; the default is 'html'.

In html mode the handler sends a readable HTML version of the error
message to the client. This mode is most useful on a development
server.

In fatal mode the handler simply dies with a compact version of the
error message. This may be caught with an eval around
C<$ah-E<gt>handle_request> or left for Apache to handle. In the latter
case the error will end up in the error logs. This mode is most
useful on a production server.

The raw_html and raw_fatal modes emulate pre-1.02 error behavior. They
are analagous to the modes above except that the errors are not
processed for readability or compactness. The resulting messages are
much longer, but may include information accidentally omitted by
Mason's processing.

Regardless of this setting, no readability processing occurs if you
have overriden the Interp/die_handler Interp parameter.

=item output_mode

This parameter has been replaced by the equivalent Interp parameter
Interp/out_mode. For backward compatibility, setting
C<$ah-E<gt>output_mode> will cause C<$interp-E<gt>out_mode> to be set
appropriately.

=item top_level_predicate

Reference to a subroutine that decides whether a component can answer
top level requests. This allows for private-use components that live
within the DocumentRoot but are inaccesible from URLs. By default,
always returns 1.

The subroutine receives one parameter, the absolute path to the
component.  It then returns either a true (serve component) or false
(reject component). In this example, the predicate rejects requests
for components whose name starts with an "_" character:

    top_level_predicate => sub { $_[0] !~ m{/_[^/]+$}

=back

=head1 ACCESSOR METHODS

All of the above properties have standard accessor methods of the
same name: no arguments retrieves the value, and one argument sets it.
For example:

    my $ah = new HTML::Mason::ApacheHandler;
    my $errmode = $ah->error_mode;
    $ah->error_mode('html');

=head1 AUTHOR

Jonathan Swartz, swartz@pobox.com

=head1 SEE ALSO

HTML::Mason,
HTML::Mason::Parser,
HTML::Mason::Interp,
HTML::Mason::Admin

=cut
