/ 
Apache2-Controller-0.0004
River stage zero No dependents
/ Apache2::Controller::Dispatch

NAME

Apache2::Controller::Dispatch - dispatch base class for Apache::Controller

SYNOPSIS

# vhost.conf:
PerlModule MyApp::Dispatch

<Location />
    SetHandler modperl
    PerlInitHandler MyApp::Dispatch
</Location>

# lib/MyApp/Dispatch:

package MyApp::Dispatch;

use strict;
use warnings FATAL => 'all';

use base qw( Apache2::Controller::Dispatch::Simple );

our %dispatch_map = (
    foo        => 'MyApp::C::Foo',
    bar        => 'MyApp::C::Bar',
    biz        => 'MyApp::C::Biz',
    'biz/baz'  => 'MyApp::C::Biz::Baz',
);

1;

DESCRIPTION

Apache2::Controller::Dispatch forms the base for the PerlInitHandler module to dispatch incoming requests to libraries based on their URL.

You don't use this module. You use one of its subclasses as a base for your dispatch module.

Natively, this does not try to figure out the appropriate module using any complex magic. Instead, you spell out the uris under the root handler location and what controller modules you want to handle paths under that URL, using the <A2CController> directive.

(future implementation

SUBCLASSES

Subclasses of this module implement <find_controller()> in different ways, usually interpreting the URI from a hash called <%dispatch_map> in your subclass.

See Apache2::Controller::Dispatch::Simple and Apache2::Controller::Dispatch::HashTree for other dispatch possibilities.

Any implementation of find_controller() should throw an Apache2::Controller::X with http => Apache2::Const::NOT_FOUND in the event that the detected method selected does not appear in the list of @ALLOWED_METHODS in the controller module. See "check_allowed_method" in Apache2::Controller::Funk

Successful run of find_controller() should result in four items of data being set in request->notes and request->pnotes:

notes->{relative_uri} = matching part of uri relative to location

This is the uri relative to the location. For example, if the dispatch module is the init handler in a <Location /subdir> config block, then for /subdir/foo/bar/biz/zip in this example code, relative_uri should be 'foo/bar' because this is the key of %dispatch_map that was matched. /subdir/foo/bar is the 'virtual directory.'

If there is no relative uri, for example if the uri requested was /subdir and this is the same as the location, then notes-{relative_uri}> would be set to the empty string.

notes->{controller} = selected package name

This should be the name of an Apache2::Controller subclass selected for dispatch.

notes->{method} = method name in controller to process the uri

This is the name of the method of the controller to use for this request.

pnotes->{path_args} = [ remaining path_info ]

The remaining 'virtual directory' arguments of the uri. In the example above for notes->{relative_uri}, this is [ 'biz', 'zip' ].

@path_args is the array of remaining elements. For example if your dispatch map contains the URI 'foo', and the incoming URI was '/foo/bar/baz', then $r->pnotes->{path_args} should be ['bar', 'baz'] before returning.

METHODS

$handler->init()

You can limit HTTP methods in your child class:

package MyApp::Dispatch;
use base qw( Apache2::Controller::Dispatch );
my @LIMIT_HTTP_METHODS = qw( GET POST ); # but not HEAD or PUT, etc

This gets processed by init() which is run from Apache2::Controller::NonResponseBase if the method is available.

$handler->process()

process() is the main guts of Apache2::Controller::Dispatch logic. It calls $self->find_controller(), which is implemented in another base class. (See Apache2::Controller::Dispatch::Simple.) If that works, then it creates an Apache2::Request object from $r, which will supposedly parse the query string once for all further handlers that create Apache2::Request objects.

get_dispatch_map

Get the cached %dispatch_map of the dispatch handler object's class. Caches hashes here in parent package space and checks with <exists>.

EXAMPLE

# configuration for <Location>:
# PerlInitHandler MyApp::Dispatch

package MyApp::Dispatch;
use base qw( 
    Apache2::Controller::Dispatch
    Apache2::Controller::Dispatch::Simple
);

my @LIMIT_HTTP_METHODS = qw( GET );

our %dispatch_map = (
    foo        => 'MyApp::C::Foo',
    bar        => 'MyApp::C::Bar',
    biz        => 'MyApp::C::Biz',
);

1;

SEE ALSO

Apache2::Controller::Dispatch::Simple, Apache2::Controller

AUTHOR

Mark Hedges, <hedges at scriptdolphin.org>

COPYRIGHT & LICENSE

Copyright 2008 Mark Hedges, all rights reserved.

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