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.

=head1 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 in production.

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

      Off   - Do not test the package

      ISA   - Test the called package and all other packages in the
              called packages @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().

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

If a module fails reload under DispatchStat, Apache::Dispatch declines
the request.

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.