NAME

Helix::Application - Helix Framework application base class.

SYNOPSIS

Example application package (lib/Example/Application.pm):

    package Example::Application;
    use base qw/Helix::Application/;

    our $VERSION = "0.01";

CGI application gateway (index.cgi):

    use lib "./lib";
    use Example::Application;

    my $app = Example::Application->new(Example::Application->TYPE_CGI);
    $app->handle_request;

DESCRIPTION

The Helix::Application class is the base high-level class of a usual Helix Framework application. It creates various system objects, reads application configuration and handles user requests.

Should never be used directly, subclass it from your application's Application.pm instead.

Request processing flow

These steps are performed while processing user request. This sequence can be redefined by the ancestor class, but in most cases you won't need to do this.

1. Create system registry

Registry is the system information structure. This step is done first, because other parts of the system depend on the registry. For more information see "Mount points" section below and Helix::Core::Registry module documentation.

2. Load application configuration

In this step application loads and instantiates the application configuration class. It contains all basic system settings. Application configuration in example application would be stored in lib/Example/Config.pm. For more information see Helix::Core::Config.

3. Accept requests (FastCGI application only!)

FastCGI application works like a daemon - it resides in memory, accepting connections from the web server. Whence a new connection is established, the application goes to the next step.

4. Handle request

Actually, all the work is done in this step. First of all, the application creates the Helix::Core::CGI object, that is used to process all incoming data. Next, application loads system drivers using the Helix::Core::Driver::Loader object. The list of required drivers must be specified in the application configuration. Afterwards, the Helix::Core::Router package comes to action. It tries to find the request handler and transfers execution to it or to the error handler, if something went wrong.

After request (or error) handling, a CGI application shuts down, but FastCGI application goes next.

5. Go to step #3 (FastCGI application only!)

When a user request is handled, our daemon-like application is ready to serve another clients without termination, so we save a bit of system resources.

Mount points

During initialization and request handling application mounts each vital object to system registry to allow other application parts to use it later. This is the list of all mount points, that are created by Helix::Application ($r below stands for Helix::Core::Registry instance):

$r->{"cfg"}

Application configuration object (see "Load application configuration" section above and Helix::Core::Config module documentation).

$r->{"cgi"}

CGI object (see Helix::Core::CGI for more information).

$r->{"driver"}

Driver loader object (see Helix::Core::Driver::Loader).

$r->{"router"}

Request router object (see Helix::Core::Router for more information).

Of course, you can mount other objects to the registry while overloading one of Helix::Application methods, though it's not recommended.

METHODS

new($type)

Class constructor. Creates an object and calls the application initialization function. $type - application type (see "CONSTANTS").

_init($name, $type)

Application initialization. Creates system registry and loads application configuration. $name is the application name, $type - application type.

handle_request()

User request processing. This function parses and routes the request, then it transfers execution to request handler. If any exception occurs during processing, it tries to start application's error handler. If no such handler was found, application dies.

CONSTANTS

TYPE_CGI

CGI application is the default type. It is suitable for development purposes (Helix::Debug will work only with this application type) and low-loaded applications. When this type is used, the web server starts one interpreter instance per user request, so if you issue high CPU usage or high memory load - use the following application type.

TYPE_FCGI

FastCGI application type is suitable for high-loaded applications with a lot of concurrent connections. It's faster than CGI up to 2000%. This type suggests FCGI module to be installed, otherwise application won't work. Also, this type has one significant limitation - you are unable to use Helix Framework debugging facility (Helix::Debug) with this type, so use TYPE_CGI during development.

SEE ALSO

Helix, Helix::Debug, Helix::Core::Registry, Helix::Core::Config, Helix::Core::CGI, Helix::Core::Driver::Loader, Helix::Core::Router

LICENSE

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

AUTHOR

Anton Belousov, <abel@cpan.org>

COPYRIGHT

Copyright (c) 2009, Atma 7, http://www.atma7.com

cpanm Helix

perl -MCPAN -e shell
install Helix