[ANNOUNCE] Apache::Dispatch-0.03

[Geoffrey Young <gy...@laserlink.net>]

The URL

 
http://morpheus.laserlink.net/~gyoung/modules/Apache-Dispatch-0.03.tar.gz

has entered CPAN as

  file: $CPAN/authors/id/G/GE/GEOFF/Apache-Dispatch-0.03.tar.gz
  size: 5735 bytes
   md5: 91eacb0aeff8e751ebc8c7156426fbfb

Changes:
0.03  8.4.2000
        - complete API and internal rewrite
            o added DispatchExtras and DispatchPrefix directive
            o removed per-server configurations
            o added new pre_dispatch, post_dispatch, error_dispatch
              and dispatch_index method tie-ins
        - updated documentation
        - more kudos to Matt Sergeant for invaluable insight

README:
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.

=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
    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 <ge...@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.