/ 
Apache-Dispatch-0.03
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

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

  DispatchPrefix Bar
  DispatchExtras Pre Post Error
</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 - directly from the browser - 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
  A 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.

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 which would allow you to define, say, a base error_dispatch() method in Foo which is then inherited by Foo::Bar, but overriden in Foo::Bar::Baz.

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().

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_METHOD_HANDLERS=1, PERL_LOG_API=1, PERL_HANDLER=1, and maybe other hooks to function properly.

FEATURES/BUGS

No known bugs or unexpected features at this time...

SEE ALSO

perl(1), mod_perl(1), Apache(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.