/ 
Apache2-Controller-0.0002
River stage zero No dependents
/ Apache2::Controller::X

NAME

Apache2::Controller::X - Exception::Class hierarchy for Apache2::Controller

SYNOPSIS

package MyApp::C::Foo;
use base qw( Apache2::Controller ); 
use Apache2::Controller::X;
# ...
sub page_controller_method {
   Apache2::Controller::X::Redirect->throw('http://foo.bar');
}

# or subclass and extend the errors...

package MyApp::X;
use base qw( Apache2::Controller::X );
use Exception::Class (
    'MyApp::X' => { 
        isa => 'Apache2::Controller::X',
    },
    'MyApp::X::Redirect' => { 
        isa => 'Apache2::Controller::X::Redirect',
    },
);

package MyApp::C::Bar;
use base qw( Apache2::Controller );
use Apache2::Const -compile => qw( :http );
use MyApp::X;
# ...
sub page_controller_method {
    MyApp::X->throw(
         message => q{ You're not supposed to be here. },
         http_status => Apache2::Const::FORBIDDEN,
         dump => {
           this    => q{structure will get YAML::Syck::Dump'd},
           that    => [qw( to the error log )],
         },
    );
}

DESCRIPTION

Hierarchy of Exception::Class objects for Apache2::Controller. All are subclasses of Apache2::Controller::X.

FIELDS

All Apache2::Controller::X exceptions implement three fields:

message

Required. The standard Exception::Class message field. If you call throw() with only one argument, a string, then this gets set as the message field, which is displayed when the object is referred to in string context.

eval { Apache2::Controller::X->throw("booyeah") };
if (my $X = Exception::Class->caught('Apache2::Controller::X')) {
    warn "my exception 'message' was '$X'\n";
    warn $X->trace;
}

http_status

This can be set to an ":http" in Apache2::Const constant, which will then be set as the http_status for the request.

Apache2::Controller::X->throw(
    message => "oh no!",
    http_status => Apache2::Const::HTTP_INTERNAL_SERVER_ERROR,
);

status_line

Combined with http_status, when intercepted by "handler" in Apache2::Controller this sets a custom message with "status_line" in Apache2::RequestRec.

Apache2::Controller::X->throw(
    message => "Warp injection coil failure in unit 3-A-73",
    http_status => Apache2::Const::HTTP_INTERNAL_SERVER_ERROR,
    status_line => "Turbulence ahead. Please buckle your safety belts.",
);

This differentiation can be used to display technical information in the log while giving a nice message to the user.

If "error" in Apache2::Controller::Render::Template is used, status_line is preferentially used to translate the error code, otherwise it uses "status_message" in HTTP::Status.

dump

An arbitrary data structure which Apache2::Controller will send through YAML::Syck Dump() when printing to the error log.

SUBCLASSES

Apache2::Controller::X

The basic exception object that implements the three basic fields.

Apache2::Controller::X::Redirect

If thrown back to the handler, the message will be used as a url to redirect the browser.

Apache2::Controller::X::Redirect->throw('http://foo.bar');

This works by setting $r->location(), not through an internal redirect. If you want to do an internal redirect, just do it with $self->internal_redirect() inherited from Apache2::SubRequest.

METHODS

Fields

This is the Fields() method provided by Exception::Class.

SEE ALSO

Exception::Class

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.