/ 
Apache-Dispatch-0.05
River stage zero No dependents
/ Apache::Dispatch

NAME

Apache::Dispatch - call PerlHandlers with the ease of CGI scripts

SYNOPSIS

httpd.conf:

PerlModule Apache::Dispatch
PerlModule Bar

DispatchExtras Pre Post Error
DispatchStat On

<Location /Foo>
  SetHandler perl-script
  PerlHandler Apache::Dispatch

  DispatchPrefix Bar
</Location>

DESCRIPTION

Apache::Dispatch translates $r->uri into a class and method and runs it as a PerlHandler. Basically, this allows you to call PerlHandlers as you would CGI scripts without having to load your httpd.conf with a slurry of <Location> tags.

EXAMPLE

in httpd.conf

  PerlModule Apache::Dispatch
  PerlModule Bar

  <Location /Foo>
    SetHandler perl-script
    PerlHandler Apache::Dispatch

    DispatchPrefix Bar
  </Location>

in browser:
  http://localhost/Foo/baz

the results are the same as if your httpd.conf looked like: <Location /Foo> SetHandler perl-script PerlHandler Bar::dispatch_baz </Location>

but with the additional security of protecting the class name from the browser and keeping the method name from being called directly. Because any class under the Bar:: hierarchy can be called, one <Location> directive is be able to handle all the methods of Bar, Bar::Baz, etc...

CONFIGURATION DIRECTIVES

DispatchPrefix
  The base class to be substituted for the $r->location part of the
  uri.  Applies on a per-location basis only.  

DispatchExtras
  An optional list of extra processing to enable per-request.  They
  may be applied on a per-server or per-location basis.  If the main
  handler is not a valid method call, the request is declined prior
  to the execution of any of the extra methods.

    Pre   - eval()s Foo->pre_dispatch() prior to dispatching the uri
            uri.  The $@ of the eval is not checked in any way.

    Post  - eval()s Foo->post_dispatch() prior to dispatching the
            uri.  The $@ of the eval is not checked.

    Error - If the main handler returns other than OK then 
            Foo->error_dispatch() is called and return status of it
            is returned instead.  Without this feature, the return
            status of your handler is returned.

DispatchStat
  An optional directive that enables reloading of the module
  resulting from the uri to class translation, similar to
  Apache::Registry or Apache::StatINC.  It applies on a per-server
  or per-location basis and defaults to Off.  Although the same
  functionality is available with Apache::StatINC for development
  DispatchStat does not check all of the modules in %INC.  This cuts
  down on overhead, making it a reasonable alternative to recycling
  the server.

    On    - Test the called package for modification and reload
            on change

    Off   - Do not test or reload the package

    ISA   - Test the called package and all other packages in the
            called package's @ISA and reload on change

SPECIAL CODING GUIDELINES

Apache::Dispatch uses object oriented calls behind the scenes. This means that you either need to account for your handler to be called as a method handler, such as

sub dispatch_bar {
  my $class = shift;  # your class
  my $r = shift;
}

or get the Apache request object yourself via

sub dispatch_bar {
  my $r = Apache->request;
}

This also has the interesting side effect of allowing for inheritance on a per-location basis.

NOTES

In addition to the special methods pre_dispatch(), post_dispatch(), and error_dispatch(), if you define dispatch_index() it will be called by /Foo or /Foo/. /Foo/index is always directly callable, but /Foo will only translate to /Foo/index at the highest level - that is, when just the location is specified. Meaning /Foo/Baz/index will call Bar::Baz->dispatch_index, but /Foo/Baz will try to call Bar->Baz().

Support for AUTOLOAD has been enabled, but requires special care. Please take the time to read the camel book on using AUTOLOAD with can() and subroutine declarations. There is also a small note in eg/Foo.pm. Consider the support experimental for now.

There is no require()ing or use()ing of the packages or methods prior to their use as a PerlHandler. This means that if you try to dispatch a method without a PerlModule directive or use() entry in your startup.pl you probably will not meet with much success. This adds a bit of security and reminds us we should be pre-loading that code in the parent process anyway...

If the uri can be dispatched but contains anything other than [a-zA-Z0-9_/-] Apache::Dispatch declines to handle the request.

Like everything in perl, the package names are case sensitive.

Verbose debugging is enabled by setting $Apache::Dispatch::DEBUG=1. Very verbose debugging is enabled at 2. To turn off all debug information set your apache LogLevel directive above info level.

This is alpha software, and as such has not been tested on multiple platforms or environments for security, stability or other concerns. It requires PERL_DIRECTIVE_HANDLERS=1, PERL_LOG_API=1, PERL_HANDLER=1, and maybe other hooks to function properly.

FEATURES/BUGS

If a module fails reload under DispatchStat, Apache::Dispatch declines the request. This might change to SERVER_ERROR in the future...

SEE ALSO

perl(1), mod_perl(1), Apache(3), Apache::StatINC(3)

AUTHOR

Geoffrey Young <geoff@cpan.org>

COPYRIGHT

Copyright 2000 Geoffrey Young - all rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.