/ 
Contentment-0.011_033
River stage zero No dependents
/ Contentment::Manual::LifeCycle

NAME

Contentment::Manual::LifeCycle - Description of the Contentment request life-cycle

DESCRIPTION

The goal of this document is to describe the general life-cycle of the Contentment process and Contentment requests. There are three general phases to a Contentment process: startup, request-handling, and cleanup.

STARTUP

The startup process of Contentment happens during the call to Contentment->begin. This is subdivided into five steps:

  1. Find Plugins. During the first step, Contentment searches all plugin repositories for init.yml files for plugins to load. This prepares the way for the next step.

  2. Resolve Dependencies. All of the depends_on dependencies in each init.yml is considered and converted into an order setting. The order determines what oder the plugins will be handled in the next step. The ordering handled such that those plugins with no dependencies will be handled earliest, while those with dependencies will be handled after all their dependencies have been loaded. Any dependency loops are broken and the system will attempt to load those plugins anyway.

  3. Load Plugins. In the order determined during the last step, each plugins libraries are loaded. This handles the use_lib and use settings for each init.yml file.

  4. Install Plugins. Any plugin that is discovered that has not yet been installed will have the "Contentment::install" hook run for that plugin. (An empty implementation of the hook is used, if none is defined.) The plugin is then marked as installed.

  5. Update Plugins. Any plugin that is discovered whose version has changed since it was last examined will have the "Contentment::upgrade" hook run for that plugin. (An empty implementation of the hook is used, if none is defined.) The plugin is then marked as being installed to the lastest version.

At the end of the call to Contentment->begin, the "Contentment::begin" hook is called, signalling the start of the second phase of the Contentment process.

REQUEST HANDLING

Depending on the platform in use, a Contentment process may either handle a single request per process (CGI) or multiple requests per process (FastCGI/mod_perl/LWP). Request handling can best be described in terms of the hooks called during the process.

Here is the list of all the hooks called:

Contentment::Request::begin
Contentment::Response::resolve
Contentment::Response::begin
Contentment::Response::filter
Contentment::Response::end
Contentment::Request::end

Between the "Contentment::Response::begin" and "Contentment::Response::end" hooks, the generator returned by the "Contentment::Response::resolve" hook is called.

The intention of the various hooks:

Contentment::Request::begin

Handlers for this hook may be used to manipulate the request itself or to associate additional information with the request in the context.

This hook is used by the Session plugin to load any session data associated with the SESSIONID cookie. The Security plugin loads any information about the current user, roles, and permissions at this time. The Site plugin associates information about the detected or default site with the context, based upon the request.

Contentment::Response::resolve

Handlers for this hook determine which generator object is used to generate the main output for the response.

The VFS plugin uses this hook to see if any of the given paths match any file in the virtual file system.

Contentment::Response::begin

Handlers for this hook may output data available on the standard input of the generator.

At the time of this writing, no plugin has used this functionality.

Contentment::Response::filter

Handlers for this hook may modify the output of the generator or the output of another "Contentment::Response::filter" hook handler.

The Transform plugin uses this hook to apply data transformations on the output of the generator. The Theme plugin uses this hook to wrap the output of any generator within a custom layout.

Contentment::Response::end

Handlers for this hook have the last chance there is to modify the request. The actual output is already set and cannot be modified, but any headers or other parameters may be modified.

The Security plugin uses this hook to save a cookie containing information about anonymous users.

Contentment::Request::end

Handlers for this hook may be used to save or otherwise clean-up information used during the request or response process.

The Session plugin uses this hook to save any changes to the session data. The Security plugin uses this hook to save any changes to the user profile.

CLEANUP

The cleanup phase currently consists entirely of a call to Contentment->end, which calls the "Contentment::end" hook.

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@cpan.org>

LICENSE AND COPYRIGHT

Copyright 2005 Andrew Sterling Hanenkamp <hanenkamp@cpan.org>. All Rights Reserved.

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

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.