NAME

Gantry::State::Exceptions - A state machine for Gantry that uses exceptions

SYNOPSIS

This module implements a state machine to control the execution context within GantryXs handler() method. This state machine uses exceptions to alter flow instead of flag variables.

DESCRIPTION

When a request comes into Gantry a preXdetermined set of steps are executed. These preXdetermined steps can be termed "states", and the process can be called a "state machine". There are many ways to implement a "state machine", so this document will not get into the semantics of the term.

The currently implemented state machines use flag variables. At specific steps, these variables are checked, the flow is then altered based on the results of those tests. Gantry currently handles the following status codes: 200, 301, 302, 400 and 500. There are flag variables for these codes and handlers to be executed, when they are set. But what if you wanted to use a 402 code. Well, you would need to create a flag variable, code a state machine to check for that variable and create a handler for that condition. Not a very scalable solution.

This module introduces the concept of using structured exceptions to change the flow of execution. If a redirect is issued using the relocate() method, an exception is raised instead of a flag variable being set. The exception takes effect immediately and is caught by the state machines handler. Which then goes thru the redirect process.

This is not too differant from how Gantry::State::Simple currently works. The advantage is that if I wanted to use that 402 code, all I would have to do is the following:

 Gantry::Exception->throw(
     status => 402,
     status_line => 'Payment required',
     message => "Gimme all your money, and your luvin\' too..."
 );

And then the exception handler would be able to do the "right thing". If there is no defined exception handler, a message is printed to stdout and a 500 code is returned to the browser.

CONFIGURATION

To load a differant state machine you need to do the following:

use MyApp qw{ -XStateMachine=Exceptions };

AUTHOR

Kevin L. Esteb <kesteb@wsipc.org>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 419:: Non-ASCII character seen before =encoding in 'GantryXs'. Assuming UTF-8