NAME

Apache::Wyrd::Handler - Apache Handler object for Apache::Wyrd modules

SYNOPSIS

        PerlWarn off
        <Directory /var/www/sites/BASENAME>
                SetHandler perl-script
                PerlHandler BASENAME::Handler
        </Directory>

DESCRIPTION

Handler for Apache::Wyrd documents. For more information on mod_perl and handlers, see http://perl.apache.org/docs/index.html

This module has been developed for and only been tested in Apache < 2.0 / mod_perl < 1.99. In this environment, the SYNOPSIS shows a typical set of appropriate Apache directives. Global Perl warnings are turned off, as they are more granularly handled within the package. Note that the Handler that is used is an instance of this handler. It is named, in this example, BASNAME::Handler and is found in a BASENAME directory which in @INC of a local mod_perl installation. Traditionally, this is in <apache configuration directory>/lib/perl/. If the perl module BASENAME::Handler has a use base qw(Apache::Wyrd::Handler) declaration, the handler method should properly determine the base class for the BASENAME set of Wyrds and the handler should interpret only those tags beginning <BASENAME::... A rudimentary sample of this usage is available in the t/lib directory of this package and is used for testing.

This way, several sites using Wyrds can be built, each subclassing Apache::Wyrd objects in their own idiom without interfering in the interpretation of the same objects in another BASENAME class. (However, nothing prevents a second BASENAME from including the first BASENAME in its use base declaration array). This is a feature(tm) of Apache::Wyrd and is intended to promote code re-use.

The Handler also dumps out the error log, if needed from the DBL, where it accumulates from it's own internal calls and calls by Wyrds to the error-level functions (_warn, _error, etc.). If the ``init'' hashref has a non-null key called ``error_page'', this log will be reverse-dumped in a standard-looking error page with a backtrace of events.

METHODS

new

Accept and bless a new object. Provided for tradition's sake, since the handler method does the real work.

handler

Handle the request. This handler uses the 2 argument function prototype so that it can be instantiated in another name-space.

In the example Apache directive above, the arguments supplied by the Apache directive give it the class name ``BASENAME''. It uses this BASENAME to determine what is the base class of all Wyrds it handles. Consequently, it will only parse Wyrds which begin with <BASENAME::...

The handler assembles the Apache request object itself, the initialization hash for the generation of Apache::Wyrd objects, and the globals used by Apache::DBL. It then calls process and respond in sequence. If all goes well, the 'output' attribute has been set by the response method, and this is returned with the appropriate headers set.

_exception_handler

Before returning a non-OK response, the handler will send two scalars to this method and if the method returns a response, that response will be sent instead. Subclasses of Apache::Wyrd::Handler can use this method to invoke and return responses from other handlers. What arguments for the first method subclasses of this method accept and how they invoke the responding entity are entirely up to the programmer. Usually, however, the dir_config table is populated with authorization requirements for this request, as required by Apache::Wyrd::Services::Auth in order to masquerade this handler as a stacked Auth handler.

add_headers

Called by handler on a successful responses from process and respond. Adds some standard headers to the response or can be overridden. By default, it adds headers to help with compatibility with AOL's famously broken proxies and other similar problems.

get_file

Based on the request, locates the file to be used and sets the file attribute to that path. It declines non-text/html files (via mime type) and, on accepting a file, passes the mtime and size of the file to the init hashref for use by the Apache::Wyrd object.

globals

defines the hashref which will be kept by the DBL object. Empty by default.

init

defines the hashref which will be used to initialize the Apache::Wyrd objects. It must return the request object under the key 'req', which is stored under the Apache::Wyrd::Handler attribute 'req' by the handler method. Any other keys are optional.

By default, if the hash key 'error_page' is set (non-null), the installation will use an error page with a debugging log. See the errorpage method.

process

``Hook'' method for introducing other handling checks to the request. It should return an Apache::Constants value if it wants to override the response of the respond method. If it does this override, then it is responsible for setting it's own headers.

respond

Does the work of setting up the found page as an Apache::Wyrd object and calling it's output method. Should probably not be overridden, unless there are tweaks that cannot be accomplished in add_headers and process.

req

return the Apache request object. This object has been initialized in handler

errorpage

Simply a formatting method. Given the error and the log in scalar form, outputs an Error Page with ``Internal Server Error'' at the top. Called by respond when the debugging flags are on.

BUGS/CAVEATS/RESERVED METHODS

FREE SOFTWARE

Standard warning about GNU GPL software. See LICENSE under the documentation for Apache::Wyrd

(GENERALLY) UNIX-Only

This software has only tested under Linux and Darwin, but should work for any *nix-style system. This software is not intended for use on windows or other delicate glassware.

AUTHOR

Barry King <wyrd@nospam.wyrdwright.com>

LICENSE

See LICENSE under the documentation for Apache::Wyrd.

Apache::Wyrd::Handler - Apache Handler object for Apache::Wyrd modules