[Apache-dispatch-devel] SF.net SVN: apache-dispatch:[76] trunk
Brought to you by:
geoffrey_young,
phred_moyer
Menu
▾
▴
[Apache-dispatch-devel] SF.net SVN: apache-dispatch:[76] trunk
|
From: <phr...@us...> - 2009-04-25 22:46:33
|
Revision: 76
http://apache-dispatch.svn.sourceforge.net/apache-dispatch/?rev=76&view=rev
Author: phred_moyer
Date: 2009-04-25 22:46:21 +0000 (Sat, 25 Apr 2009)
Log Message:
-----------
Release 0.11 with A::B 0.06
Modified Paths:
--------------
trunk/Changes
trunk/MANIFEST
trunk/README
trunk/lib/Apache/Dispatch.pm
Modified: trunk/Changes
===================================================================
--- trunk/Changes 2009-04-19 08:11:26 UTC (rev 75)
+++ trunk/Changes 2009-04-25 22:46:21 UTC (rev 76)
@@ -1,6 +1,6 @@
Revision history for Perl extension Apache::Dispatch
-0.11 04.05.2009 20:34 PDT
+0.11 04.25.2009 14:32 PST
- remove t/TEST.PL (it is not needed)
- put version in Apache::Dispatch::Util to avoid issue with Apache2::Module
- document PerlLoadModule for Dispatch* directives - ideysus@annocpan
Modified: trunk/MANIFEST
===================================================================
--- trunk/MANIFEST 2009-04-19 08:11:26 UTC (rev 75)
+++ trunk/MANIFEST 2009-04-25 22:46:21 UTC (rev 76)
@@ -23,5 +23,4 @@
t/03filter.t
t/04oo.t
t/conf/extra.last.conf.in
-t/TEST.PL
META.yml Module meta-data (added by MakeMaker)
Modified: trunk/README
===================================================================
--- trunk/README 2009-04-19 08:11:26 UTC (rev 75)
+++ trunk/README 2009-04-25 22:46:21 UTC (rev 76)
@@ -1,324 +1,310 @@
NAME
+ Apache::Dispatch - call PerlHandlers with the ease of Registry scripts
-Apache::Dispatch - call PerlHandlers with the ease of Registry scripts
-
SYNOPSIS
+ Makefile.PL:
-Makefile.PL:
+ # require util since it can be used outside an apache process
+ PREREQ_PM => {
+ 'Apache::Dispatch::Util' => 0.11,
+ }
- # require util since it can be used outside an apache process
- PREREQ_PM => {
- 'Apache::Dispatch::Util' => 0.11,
+ httpd.conf:
-httpd.conf:
+ PerlModule Apache::Dispatch
+ PerlModule Bar
- PerlModule Apache::Dispatch
- PerlModule Bar
+ DispatchExtras Pre Post Error
+ DispatchStat On
+ DispatchISA "My::Utils"
+ DispatchAUTOLOAD Off
- DispatchExtras Pre Post Error
- DispatchStat On
- DispatchISA "My::Utils"
- DispatchAUTOLOAD Off
+ <Location /Foo>
+ SetHandler perl-script
+ PerlHandler Apache::Dispatch
- <Location /Foo>
- SetHandler perl-script
- PerlHandler Apache::Dispatch
+ DispatchPrefix Bar
+ DispatchFilter Off
+ </Location>
- DispatchPrefix Bar
- DispatchFilter Off
- </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 Regsitry scripts without having to load your httpd.conf with a
+ slurry of <Location> tags.
-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 Regsitry scripts without having to load your httpd.conf
-with a slurry of <Location> tags.
-
EXAMPLE
+ in httpd.conf
- in httpd.conf
+ PerlModule Apache::Dispatch
+ PerlModule Bar
- PerlModule Apache::Dispatch
- PerlModule Bar
+ <Location /Foo>
+ SetHandler perl-script
+ PerlHandler Apache::Dispatch
- <Location /Foo>
- SetHandler perl-script
- PerlHandler Apache::Dispatch
+ DispatchPrefix Bar
+ </Location>
- DispatchPrefix Bar
- </Location>
+ in browser:
+ http://localhost/Foo/baz
- 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>
- 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 able to handle all the methods of Bar, Bar::Baz, etc...
-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 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.
- DispatchPrefix
- The base class to be substituted for the $r->location part of the
- uri.
+ DispatchLocation
+ Using Apache::Dispatch from a <Directory> directive, either
+ directly or from a .htaccess file, will _require_ the use of
+ DispatchLocation, which defines the location from which
+ Apache::Dispatch will start class->method() translation.
+ For example:
- DispatchLocation
- Using Apache::Dispatch from a <Directory> directive, either
- directly or from a .htaccess file, will _require_ the use of
- DispatchLocation, which defines the starting location from which
- Apache::Dispatch will start class->method() translation.
- For example:
+ httpd.conf
+ DocumentRoot /usr/local/apache/htdocs
+ <Directory /usr/local/apache/htdocs/>
+ ...
+ <Directory>
- httpd.conf
- DocumentRoot /usr/local/apache/htdocs
- <Directory /usr/local/apache/htdocs/>
- ...
- <Directory>
+ .htaccess (in /usr/local/apache/htdocs/Foo)
+ SetHandler perl-script
+ PerlHandler Apache::Dispatch
+ DispatchPrefix Baz
+ DispatchLocation /Foo
- .htaccess (in /usr/local/apache/htdocs/Foo)
- SetHandler perl-script
- PerlHandler Apache::Dispatch
- DispatchPrefix Baz
- DispatchLocation /Foo
+ This allows a request to /Foo/Bar/biff to properly map to
+ Baz::Bar->biff().
- This allows a request to /Foo/Bar/biff to properly map to
- Baz::Bar->biff().
+ While intended specifically for <Directory> configurations, one
+ could use DispatchLocation to further obscure uri translations
+ within <Location> sections as well by changing the part of
+ the uri that is substitued with your module.
- While intended specifically for <Directory> configurations, one
- could use DispatchLocation to further obscure uri translations
- within <Location> sections as well by changing the part of
- the uri that is substitued with your module.
+ DispatchExtras
+ An optional list of extra processing to enable per-request. If
+ the main handler is not a valid method call, the request is
+ declined prior to the execution of any of the extra methods.
- DispatchExtras
- An optional list of extra processing to enable per-request. 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($r) prior to dispatching the
+ uri. The $@ of the eval is not checked in any way.
- Pre - eval()s Foo->pre_dispatch($r) prior to dispatching the
- uri. The $@ of the eval is not checked in any way.
+ Post - eval()s Foo->post_dispatch($r) after dispatching the
+ uri. The $@ of the eval is not checked in any way.
- Post - eval()s Foo->post_dispatch($r) after dispatching the
- uri. The $@ of the eval is not checked in any way.
+ Error - If the main handler returns other than OK then
+ Foo->error_dispatch($r, $@) is called and return status
+ of it is returned instead. Unlike the pre and post
+ processing routines above, error_dispatch is not wrapped
+ in an eval, so if it dies, the Apache::Dispatch dies,
+ and Apache will process the error using ErrorDocument,
+ custom_response(), etc.
+ With error_dispatch() disabled, the return status of the
+ the main handler is returned to the client.
- Error - If the main handler returns other than OK then
- Foo->error_dispatch($r, $@) is called and return status
- of it is returned instead. Unlike the pre and post
- processing routines above, error_dispatch is not wrapped
- in an eval, so if it dies, the Apache::Dispatch dies,
- and Apache will process the error using ErrorDocument,
- custom_response(), etc.
- With error_dispatch() disabled, the return status of the
- the main handler is returned to the client.
+ DispatchRequire
+ An optional directive that enables require()ing of the module that
+ is the result of the uri to class->method translation. This allows
+ your configuration to be a bit more dynamic, but also decreases
+ security somewhat. And don't forget that you really should be
+ pre-loading frequently used modules in the parent process to reduce
+ overhead - DispatchRequire is a directive of conveinence.
- DispatchRequire
- An optional directive that enables require()ing of the module that
- is the result of the uri to class->method translation. This allows
- your configuration to be a bit more dynamic, but also decreases
- security somewhat. And don't forget that you really should be
- pre-loading frequently used modules in the parent process to reduce
- overhead - DispatchRequire is a directive of conveinence.
+ On - require() the module
- On - require() the module
+ Off - Do not require() the module (Default)
- Off - Do not require() the module (Default)
+ DispatchStat
+ An optional directive that enables reloading of the module that is
+ the result of the uri to class->method translation, similar to
+ Apache::Registry, Apache::Reload, or Apache::StatINC.
- DispatchStat
- An optional directive that enables reloading of the module that is
- the result of the uri to class->method translation, similar to
- Apache::Registry, Apache::Reload, or Apache::StatINC.
+ On - Test the called package for modification and reload on
+ change
- On - Test the called package for modification and reload on
- change
+ Off - Do not test or reload the package (Default)
- Off - Do not test or reload the package (Default)
+ ISA - Test the called package, and all other packages in the
+ called package's @ISA, and reload on change
- ISA - Test the called package, and all other packages in the
- called package's @ISA, and reload on change
+ DispatchAUTOLOAD
+ An optional directive that enables unknown methods to use
+ AutoLoader. It may be applied on a per-server or per-location
+ basis and defaults to Off. Please see the special section on
+ AUTOLOAD below.
- DispatchAUTOLOAD
- An optional directive that enables unknown methods to use
- AutoLoader. It may be applied on a per-server or per-location
- basis and defaults to Off. Please see the special section on
- AUTOLOAD below.
+ On - Allow for methods to be defined in AUTOLOAD method
- On - Allow for methods to be defined in AUTOLOAD method
-
- Off - Turn off search for AUTOLOAD method (Default)
+ Off - Turn off search for AUTOLOAD method (Default)
- DispatchISA
- An optional list of parent classes you want your dispatched class
- to inherit from.
+ DispatchISA
+ An optional list of parent classes you want your dispatched class
+ to inherit from.
- DispatchFilter
- If you have Apache::Filter 1.013 or above installed, you can take
- advantage of other Apache::Filter aware modules. Please see the
- section on FILTERING below. In keeping with Apache::Filter
- standards, PerlSetVar Filter has the same effect as DispatchFilter
- but with lower precedence.
+ DispatchFilter
+ If you have Apache::Filter 1.013 or above installed, you can take
+ advantage of other Apache::Filter aware modules. Please see the
+ section on FILTERING below. In keeping with Apache::Filter
+ standards, PerlSetVar Filter has the same effect as DispatchFilter
+ but with lower precedence.
- On - make the output of your module Apache::Filter aware
+ On - make the output of your module Apache::Filter aware
- Off - do not use Apache::Filter (Default)
+ Off - do not use Apache::Filter (Default)
+ DispatchDebug
+ Set DispatchDebug to 1 or 2 to control the verbosity of
+ debug statements.
+
SPECIAL CODING GUIDELINES
+ Migrating to Apache::Dispatch is relatively painless - it requires only
+ a few minor code changes. The good news is that once you adapt code to
+ work with Dispatch, it can be used as a conventional mod_perl method
+ handler, requiring only a few considerations. Below are a few things
+ that require attention.
-Migrating to Apache::Dispatch is relatively painless - it requires
-only a few minor code changes. The good news is that once you adapt
-code to work with Dispatch, it can be used as a conventional mod_perl
-method handler, requiring only a few considerations. Below are a few
-things that require attention.
+ In the interests of security, all handler methods must be prefixed with
+ 'dispatch_', which is added to the uri behind the scenes. Unlike
+ ordinary mod_perl handlers, for Apache::Dispatch there is no default
+ method (with a tiny exception - see NOTES below).
-In the interests of security, all handler methods must be prefixed
-with 'dispatch_', which is added to the uri behind the scenes. Unlike
-ordinary mod_perl handlers, for Apache::Dispatch there is no default
-method (with a tiny exception - see NOTES below).
+ 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
-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 $self = shift; # your class
+ my $r = shift;
+ }
- sub dispatch_bar {
- my $self = shift; # your class
- my $r = shift;
- }
+ or get the Apache request object directly via
-or get the Apache request object directly via
+ sub dispatch_bar {
+ my $r = Apache->request;
+ }
- sub dispatch_bar {
- my $r = Apache->request;
- }
+ If you want to use the handler unmodified outside of Apache::Dispatch,
+ you must do three things:
-If you want to use the handler unmodified outside of Apache::Dispatch,
-you must do three things:
+ prototype your handler:
- prototype your handler:
+ sub dispatch_baz ($$) {
+ my $self = shift;
+ my $r = shift;
+ }
- sub dispatch_baz ($$) {
- my $self = shift;
- my $r = shift;
- }
+ change your httpd.conf entry:
- change your httpd.conf entry:
+ <Location /Foo>
+ SetHandler perl-script
+ PerlHandler Bar->dispatch_baz
+ </Location>
- <Location /Foo>
- SetHandler perl-script
- PerlHandler Bar->dispatch_baz
- </Location>
+ pre-load your module:
+ PerlModule Bar
+ or
+ PerlRequire startup.pl
+ # where startup.pl contains
+ # use Bar;
- pre-load your module:
- PerlModule Bar
- or
- PerlRequire startup.pl
- # where startup.pl contains
- # use Bar;
+ That's it - now the handler can be swapped in and out of Dispatch
+ without further modification. See the Eagle book on method handlers for
+ more details.
-That's it - now the handler can be swapped in and out of Dispatch
-without further modification. See the Eagle book on method handlers
-for more details.
-
FILTERING
+ Apache::Dispatch provides for output filtering using Apache::Filter
+ 1.013 and above.
-Apache::Dispatch provides for output filtering using Apache::Filter
-1.013 and above.
+ <Location /Foo>
+ SetHandler perl-script
+ PerlHandler Apache::Dispatch Apache::Compress
- <Location /Foo>
- SetHandler perl-script
- PerlHandler Apache::Dispatch Apache::Compress
+ DispatchPrefix Bar
+ DispatchFilter On
+ </Location>
- DispatchPrefix Bar
- DispatchFilter On
- </Location>
+ Your handler need do nothing special to make its output the start of the
+ chain - Apache::Dispatch registers itself with Apache::Filter and hides
+ the task from your handler. Thus, any dispatched handler is
+ automatically Apache::Filter ready without the need for additional code.
-Your handler need do nothing special to make its output the start of
-the chain - Apache::Dispatch registers itself with Apache::Filter and
-hides the task from your handler. Thus, any dispatched handler is
-automatically Apache::Filter ready without the need for additional
-code.
+ The only caveat is that you must use the request object that is passed
+ to the handler and not get it directly using Apache->request.
-The only caveat is that you must use the request object that is passed
-to the handler and not get it directly using Apache->request.
-
AUTOLOAD
+ Support for AUTOLOAD has been made optional, but requires special care.
+ Please take the time to read the camel book on using AUTOLOAD with can()
+ and subroutine declarations (3rd ed pp326-329).
-Support for AUTOLOAD has been made optional, but requires special
-care. Please take the time to read the camel book on using AUTOLOAD
-with can() and subroutine declarations (3rd ed pp326-329).
+ Basically, you declare the methods you want AUTOLOAD to capture by name
+ at the top of your script. This is necessary because can() will return
+ true if your class (or any parent class) contains an AUTOLOAD method,
+ but $AUTOLOAD will only be populated for declared method calls. Hence,
+ without a declaration you won't be able to get at the name of the method
+ you want to AUTOLOAD.
-Basically, you declare the methods you want AUTOLOAD to capture by
-name at the top of your script. This is necessary because can()
-will return true if your class (or any parent class) contains an
-AUTOLOAD method, but $AUTOLOAD will only be populated for declared
-method calls. Hence, without a declaration you won't be able to
-get at the name of the method you want to AUTOLOAD.
+ DispatchISA introduced some convenience, but some headaches as well - if
+ you inherit from a class that uses AutoLoader then ALL method calls are
+ true. And as just explained, AUTOLOAD() will not know what the called
+ method was. This may represent a problem if you aren't aware that, say,
+ CGI.pm uses AutoLoader and spend a few hours trying to figure out why
+ all of a sudden every URL under Dispatch is bombing. You may want to
+ check out NEXT.pm (available from CPAN) for use in your AUTOLOAD
+ routines to help circumvent this partucular feature.
-DispatchISA introduced some convenience, but some headaches as well -
-if you inherit from a class that uses AutoLoader then ALL method calls
-are true. And as just explained, AUTOLOAD() will not know what the
-called method was. This may represent a problem if you aren't aware
-that, say, CGI.pm uses AutoLoader and spend a few hours trying to
-figure out why all of a sudden every URL under Dispatch is bombing.
+ If you decide to use DispatchISA it is HIGHLY SUGGESTED that you do so
+ with DispatchAUTOLOAD Off (which is the default behavior).
-If you decide to use DispatchISA it is HIGHLY SUGGESTED that you do so
-with DispatchAUTOLOAD Off (which is the default behavior).
-
NOTES
+ If you define a dispatch_index() method calls to /Foo will default to
+ it. Unfortunately, this implicit translation only happens at the highest
+ level - calls to /Foo/Bar will translate to Foo->Bar() (that is, unless
+ Foo::Bar is your DispatchPrefix, in which case it will work but
+ /Foo/Bar/Baz will not, etc). Explicit calls to /Foo/index follow the
+ normal dispatch rules.
-If you define a dispatch_index() method calls to /Foo will default to
-it. Unfortunately, this implicit translation only happens at the
-highest level - calls to /Foo/Bar will translate to Foo->Bar() (that
-is, unless Foo::Bar is your DispatchPrefix, in which case it will
-work but /Foo/Bar/Baz will not, etc). Explicit calls to /Foo/index
-follow the normal dispatch rules.
+ If the uri can be dispatched but contains anything other than
+ [a-zA-Z0-9_/-] Apache::Dispatch declines to handle the request.
-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.
-Like everything in perl, the package names are case sensitive.
+ Warnings have been left on, so if you set an invalid class with
+ DispatchISA you will see a message like: Can't locate package Foo::Bar
+ for @Bar::Baz::ISA at .../Apache/Dispatch.pm line 277.
-Warnings have been left on, so if you set an invalid class with
-DispatchISA you will see a message like:
- Can't locate package Foo::Bar for @Bar::Baz::ISA at
- .../Apache/Dispatch.pm line 277.
+ 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.
-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...
-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::Filter(3), Apache::Reload(3),
+ Apache::StatINC(3)
-perl(1), mod_perl(1), Apache(3), Apache::Filter(3), Apache::Reload(3),
-Apache::StatINC(3)
-
MAINTAINER
+ Fred Moyer <ph...@ap...>
-Fred Moyer <ph...@ap...>
-
AUTHOR
+ Geoffrey Young <ge...@cp...>
-Geoffrey Young <ge...@cp...>
-
COPYRIGHT
+ Copyright 2001-2006 Geoffrey Young - all rights reserved.
-Copyright 2001 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.
-This library is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
Modified: trunk/lib/Apache/Dispatch.pm
===================================================================
--- trunk/lib/Apache/Dispatch.pm 2009-04-19 08:11:26 UTC (rev 75)
+++ trunk/lib/Apache/Dispatch.pm 2009-04-25 22:46:21 UTC (rev 76)
@@ -47,7 +47,7 @@
require Apache::ModuleConfig;
require DynaLoader;
push @Apache::Dispatch::ISA, qw(DynaLoader);
- __PACKAGE__->bootstrap($VERSION);
+ __PACKAGE__->bootstrap($Apache::Dispatch::Util::VERSION);
}
sub handler {
@@ -323,6 +323,7 @@
# require util since it can be used outside an apache process
PREREQ_PM => {
'Apache::Dispatch::Util' => 0.11,
+ }
httpd.conf:
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
