The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
OpenInteract-1.99_05
River stage zero No dependents
1 ++
/ OpenInteract2::Setup

NAME

OpenInteract2::Setup - Setup an OpenInteract2::Context object

SYNOPSIS

 # Note: This is normally done ONLY in OpenInteract2::Context

 use OpenInteract2::Setup;
 
 # Just used for less typing...
 
 my $setup = OpenInteract2::Setup->new;
  
 # Create a temporary library -- a single directory where we copy all
 # Perl modules from the packages used. (The 'create' option clears
 # out the old directory and replaces it.)
 
 my $copied = $setup->create_temp_lib({ temp_lib_create => 'create' });
 print "Files copied to temp library: ", join( ", ", @{ $copied } );
 
 # Same thing, except only copy modules if the temp lib doesn't exist
 # and if the refresh file (CTX->lookup_temp_lib_refresh_filename)
 # doesn't exist
 
 my $copied = $setup->create_temp_lib;
 
 # Build the action table and bring in the necessary classes
 
 my $actions = $setup->read_action_table();
 print "Actions in server: ", join( ", ", @{ $actions } );
 my $modules = $setup->require_action_classes( $actions );
 my $initialized = $setup->initialize_action_classes( $modules );
 
 # Read the SPOPS configuration and build all the SPOPS classes
 
 my $spops_config = $setup->read_spops_config();
 print "SPOPS object aliases: ", join( ", ", @{ $aliases } );
 my $classes = $setup->activate_spops_classes( $spops_config );
 
 # Require a bunch of mdules at once
 
 my $required = $setup->require_module({ class => \@class_list });
 my $required = $setup->require_module({ filename => 'apache_modules.dat' });
 
 # Declare a custom subclass for setup in $WEBSITE_DIR/conf/server.ini
 [system_class]
 setup = My::CustomSetup
 
 package My::CustomSetup;
 
 use base qw( OpenInteract2::Setup );
 
 sub run_pre_process {
     my ( $self ) = @_;
     # perform actions before the setup runs
 }
 
 sub run_post_process {
     my ( $self ) = @_;
     # perform actions after the setup runs
 }

DESCRIPTION

This class exists only to setup the OpenInteract2::Context object and only gets used once, when the context is first created.

METHODS

Subclassing

You can create your own routines to run at context initialization by telling OpenInteract to use your setup class. How to do this:

 # In $WEBSITE_DIR/conf/server.ini
 
 [system_class]
 setup = My::CustomSetup

This tells OI about your class. Now you can override functionality from OpenInteract2::Setup and also implement hooks to run before and/or after the setup process:

 package My::CustomSetup;
 
 use base qw( OpenInteract2::Setup );
 use File::Path             qw( rmtree );
 use OpenInteract2::Context qw( CTX );
 
 sub run_post_process {
     my ( $self ) = @_;
     # initialize Class::DBI classes, load cached data, whatever....
 }
 
 # always recreate the temporary library
 
 sub create_temp_dir {
     my ( $self ) = @_;
     my $temp_lib = CTX->lookup_temp_lib_directory;
     rmtree( $temp_lib );
     return $self->SUPER::create_temp_lib;
 }

run_pre_process()

This method is called just after the OpenInteract2::Context is created and has read in the server configuration.

run_post_process()

This method is called after all setup has completed.

Setup methods

read_server_config()

The base_config property of the context must be defined before this is called. Reads in the server configuration, sets information from the base configuration (website name and directory) and calls translate_dirs() on the server config object.

Throws an exception if it cannot read the server configuration file or on any errors found in creating the OpenInteract2::Config object.

Returns: OpenInteract2::Config-derived object

read_repository()

Opens up a package repository and stores it. Must have the base_config property defined before calling or an exception is thrown.

Returns: The OpenInteract2::Repository object

read_packages()

Retrieve all packages currently in a website. You must first assign a OpenInteract2::Repository object (run read_repository()) to the context or this method will throw an exception.

Returns: an arrayref of OpenInteract2::Package objects.

create_temp_dir( \%params )

Optionally copies all .pm files from all packages in a website to a temporary library directory. Unlike OI 1.x the default is to leave the directory as-is if it already exists and only overwrite it on demand. So if the directory exists and the refresh file does not exist (more below), no files will be copied unless the 'temp_lib_create' key in \%params is set to 'create'.

The context must have the packages set before this is run, otherwise an exception is thrown.

The refresh file is created by certain OI2 management tasks and signals that the library directory needs to be refreshed. One such task is installing a new package, the assumption being that you will only need to refresh the temporary library directory when the libraries actually change.

Returns: Arrayref of all files copied

read_action_table()

Reads in all available action configurations from all installed packages. While we read in each action configuration we perform a few other tasks, listed below.

Note that when copying default information, we only copy the information if the action key (not just the value) is undefined. This ensures you can define empty action keys and not worry about any default information overwriting it at server startup.

  • Install the action name in the keys 'key' and 'name' (One of these will probably be chosen before release.)

  • Copy the package name and version into the action using the keys 'package_name' and 'package_version'.

  • Copy the filename from which we read the information into the key 'config_file'.

  • Copy default action information from the global defaults (found in the server configuration key 'action_info.default').

  • Copy default action information from the local defaults, found in the action 'DEFAULT' in each configuration file. (This is optional.)

Returns: Action table (hashref)

Example:

 action.ini
 ----------------------------------------
 [DEFAULT]
 author       = Chris Winters E<lt>chris@cwinters.comE<gt>
 
 [user]
 class        = OpenInteract2::Handler::User
 security     = no
 default_task = search_form
 
 [newuser]
 class        = OpenInteract2::Handler::NewUser
 error        = OpenInteract2::Error::User
 security     = no
 default_task = show
 ----------------------------------------

This would result in an action table:

 user => {
    class        => 'OpenInteract2::Handler::User',
    security     => 'no',
    default_task => 'search_form',
    key          => 'user',
    name         => 'user',
    package_name => 'base_user',
    package_version => 1.45,
    config_file  => '/home/httpd/mysite/pkg/base_user-1.45/conf/action.ini',
    author       => 'Chris Winters E<lt>chris@cwinters.comE<gt>',
 },
 newuser => {
    class        => 'OpenInteract2::Handler::NewUser',
    error        => 'OpenInteract2::Error::User',
    security     => 'no',
    default_task => 'show'
    key          => 'newuser',
    name         => 'newuser',
    package_name => 'base_user',
    package_version => 1.45,
    config_file  => '/home/httpd/mysite/pkg/base_user-1.45/conf/action.ini',
    author       => 'Chris Winters E<lt>chris@cwinters.comE<gt>',
 },

require_action_classes( \%action_table )

Scans through all the actions and performs a 'require' on all referenced classes.

Returns: Arrayref of all classes successfully required.

initialize_action_classes( \@action_classes )

Calls init_at_startup() on each class in \@action_classes. Catches any exceptions thrown and logs them but continues with the process. A class is considered successfully initialized if it does not throw an exception.

Returns: Arrayref of all classes successfully initialized.

initialize_observers()

Initializes the observers from the server and packages (see OpenInteract2::Observer), reads the configuration observers from the server and packages (see OpenInteract2::Config::Initializer).

Returns: nothing

read_spops_config()

Reads in all available SPOPS class configurations from all installed packages. When we read in each configuration we perform a few additional tasks (most of them done in OpenInteract2::SPOPS and OpenInteract2::SPOPS::DBI.

  • Put the name of the SPOPS configuration into the key 'key'

  • Copy the package name and version into the action using the keys 'package_name' and 'package_version'.

  • Copy the filename from which we read the information into the key 'config_file'.

  • Modify the 'isa' field depending on whether the 'use_security' key is set to 'yes'

  • Modify the 'isa' field based on the datasource used.

  • Modify the 'creation_security' field to resolve group names into the ID values. (For instance, you can use 'site_admin_group' as an identifier and it will resolve to the ID found in the server configuration key 'default_objects.site_admin_group'.)

Returns: Hashref with SPOPS configuration information in all packages.

activate_spops_process()

Extremely thin wrapper around SPOPS::Initialize which does all the work toward creating and initializing SPOPS classes.

Returns: Arrayref of SPOPS classes properly read and initialized.

initialize_indexers()

Bring in the 'class' for each of the configured full-text indexers.

Returns: nothing; if we cannot include a class we throw an exception

initialize_controller()

Reads in all controllers from server configuration and registers them with OpenInteract2::Controller.

initialize_content_generator()

Just call OpenInteract2::ContentGenerator::OpenInteract2::ContentGenerator->initialize().

create_cache()

Create a cache object based on the server configuration. The cache information is held in cache, and if the use property of that is not a true value, we do not do anything. Otherwise we require the class property of the cache information and then call new() on it, returning the cache object.

Returns: OpenInteract2::Cache-derived object.

require_module( \%params )

Does a require on one or more modules. The modules to be read in can be specified in the parameter 'class' or they can be in a filename named in 'filename', one per line.

SEE ALSO

OpenInteract2::Context

OpenInteract2::Config

OpenInteract2::Config::Base

SPOPS::Initialize

COPYRIGHT

Copyright (c) 2001-2004 Chris Winters. All rights reserved.

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

AUTHORS

Chris Winters <chris@cwinters.com>