SPOPS::Initialize - Provide methods for initializing groups of SPOPS objects at once

SPOPS documentation Contained in the SPOPS distribution.

Index

Code Index:

NAME

Top

SPOPS::Initialize - Provide methods for initializing groups of SPOPS objects at once

SYNOPSIS

Top

 # Bring in the class

 use SPOPS::Initialize;

 # Assumes that all your SPOPS configuration information is collected
 # in a series of files 'spops/*.perl'

 my $config = SPOPS::Initialize->read_config({
                              directory => '/path/to/spops',
                              pattern   => '\.perl' });

 # You could also have all your SPOPS classes in a single file:

 my $config = SPOPS::Initialize->read_config({
                              filename => '/path/to/my/spops.config' });

 # Or in a number of files:

 my $config = SPOPS::Initialize->read_config({
                              filename => [ '/path/to/my/spops.config.1',
                                            '/path/to/my/spops.config.2' ] });

 # As a shortcut, you read the config and process all at once

 SPOPS::Initialize->process({ directory => '/path/to/spops',
                              pattern   => '\.perl' });

 SPOPS::Initialize->process({ filename => '/path/to/my/spops.config' });

 SPOPS::Initialize->process({ filename => [ '/path/to/my/spops.config.1',
                                            '/path/to/my/spops.config.2' ] });

 # Use an already-formed config hashref from somewhere else

 SPOPS::Initialize->process({ config => \%spops_config });

 # You can also pass in multiple config hashrefs that get processed at
 # once, taking care of circular relationship problems (e.g., 'user'
 # links-to 'group', 'group' links-to 'user').

 SPOPS::Initialize->process({ config => [ $config1, $config2 ] });

DESCRIPTION

Top

This class makes it simple to initialize SPOPS classes and should be suitable for utilizing at a server (or long-running process) startup.

Initialization of a SPOPS class consists of four steps:

1.

Read in the configuration. The configuration can be in a separate file, read from a database or built on the fly.

2.

Ensure that the classes used by SPOPS are 'require'd.

3.

Build the SPOPS class, using SPOPS::ClassFactory.

4.

Initialize the SPOPS class. This ensures any initial work the class needs to do on behalf of its objects is done. Once this step is complete you can instantiate objects of the class and use them at will.

METHODS

Top

process( \%params )

The configuration parameter 'config' can refer to one or more SPOPS object configuration hashrefs. These can be already-formed configuration hashrefs which, if there are more than one,are merged.

Example:

 SPOPS::Initialize->process({ config => $spops_config });
 SPOPS::Initialize->process({ config => [ $spops_config, $spops_config ] });

You can also pass one or more filenames of SPOPS information (using 'filename', or a combination of 'directory' and 'pattern'). Filename/directory processing parameters are passed directly to read_config().

Examples:

 # Process configurations in files 'user/spops.perl' and
 # 'group/spops.perl'

 SPOPS::Initialize->process({ filename => [ 'user/spops.perl',
                                            'group/spops.perl' ] });

 # Process all configuration files ending in .perl in the directory
 # 'conf/spops/':

 SPOPS::Initialize->process({ directory => 'conf/spops/',
                              pattern   => q(\.perl$) });

Other parameters in \%params depend on SPOPS::ClassFactory -- any values you pass will be passed through. This is fairly rare -- the only one you might ever want to pass is 'alias_list', which is an arrayref of aliases in the (merged or not) SPOPS config hashref to process.

Example:

 # We're just clowning around, so only process 'bozo' -- 'user' and
 # 'group' aren't touched

 my $config = {  user  => { ... },
                 group => { ... },
                 bozo  => { ... } };
 SPOPS::Initialize->process({ config => $config, alias_list => [ 'bozo' ] });

read_config( \%params )

Read in SPOPS configuration information from one or more files in the filesystem.

Parameters:

SEE ALSO

Top

SPOPS::ClassFactory

COPYRIGHT

Top

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

Top

Chris Winters <chris@cwinters.com>

SPOPS documentation Contained in the SPOPS distribution. 
package SPOPS::Initialize;

# $Id: Initialize.pm,v 3.4 2004/06/02 00:48:21 lachoy Exp $

use strict;
use Log::Log4perl qw( get_logger );
use SPOPS;
use SPOPS::ClassFactory;
use SPOPS::Exception qw( spops_error );

my $log = get_logger();

$SPOPS::Initialize::VERSION = sprintf("%d.%02d", q$Revision: 3.4 $ =~ /(\d+)\.(\d+)/);

# Main interface -- take the information read in from 'read_config()'
# and create SPOPS classes, then initialize them

sub process {
    my ( $class, $p ) = @_;
    $p ||= {};
    my $config = $p->{config};
    if ( $p->{directory} or $p->{filename} ) {
        $config = $class->read_config( $p );
        return unless ( ref $config eq 'HASH' );
        delete $p->{filename};
        delete $p->{directory};
        delete $p->{pattern};
    }

    # We were given more than one configuration to process, so merge

    if ( ref $config eq 'ARRAY' ) {
        my $full_config = {};
        foreach my $single_config ( @{ $config } ) {
            next unless ( ref $single_config eq 'HASH' );
            foreach my $object_key ( keys %{ $single_config } ) {
                $full_config->{ $object_key } = $single_config->{ $object_key };
            }
        }
        $config = $full_config;
    }

    my $class_created_ok = SPOPS::ClassFactory->create( $config, $p ) || [];
    unless ( scalar @{ $class_created_ok } ) {
        $log->warn( "No classes were created by 'SPOPS::ClassFactory->create()'" );
        return undef;
    }

    # Now go through each of the classes created and initialize

    my @full_success = ();
    foreach my $spops_class ( @{ $class_created_ok } ) {
        eval { $spops_class->class_initialize() };
        if ( $@ ) {
            spops_error "Failed to run class_initialize() on ",
                        "[$spops_class]: $@";
        }
        push @full_success, $spops_class;
    }
    return \@full_success;
}


# Read in one or more configuration files (see POD)

sub read_config {
    my ( $class, $p ) = @_;
    my @config_files = ();

    # You can specify one or more filenames to read

    if ( $p->{filename} ) {
        if ( ref $p->{filename} eq 'ARRAY' ) {
            push @config_files, @{ $p->{filename} };
        }
        else {
            push @config_files, $p->{filename};
        }
    }

    # Or specify a directory and, optionally, a pattern to match for
    # files to read

    elsif ( $p->{directory} and -d $p->{directory} ) {
        my $dir = $p->{directory};
        $log->is_info &&
            $log->info( "Reading configuration files from ($dir) with pattern ($p->{pattern})" );
        opendir( CONF, $dir )
               || spops_error "Cannot read configuration files from directory [$dir]: $!";
        my @directory_files = readdir( CONF );
        close( CONF );
        foreach my $file ( @directory_files ) {
            my $full_filename = "$dir/$file";
            next unless ( -f $full_filename );
            if ( $p->{pattern} ) {
                next unless ( $file =~ /$p->{pattern}/ );
            }
            push @config_files, $full_filename;
        }
    }

    # Now read in each of the files and assign the values to the main
    # $spops_config.

    my %spops_config = ();
    foreach my $file ( @config_files ) {
        $log->is_info &&
            $log->info( "Reading configuration from file: ($file)" );
        my $data = $class->read_perl_file( $file );
        if ( ref $data eq 'HASH' ) {
            foreach my $spops_key ( keys %{ $data } ) {
                $spops_config{ $spops_key } = $data->{ $spops_key };
            }
        }
    }

    return \%spops_config;
}


# Read in a Perl data structure from a file and return

sub read_perl_file {
    my ( $class, $filename ) = @_;
    return undef unless ( -f $filename );
    eval { open( INFO, $filename ) || die $! };
    if ( $@ ) {
        warn "Cannot open config file for evaluation ($filename): $@ ";
        return undef;
    }
    local $/ = undef;
    no strict;
    my $info = <INFO>;
    close( INFO );
    my $data = eval $info;
    if ( $@ ) {
        spops_error "Cannot read data structure from [$filename]: $@";
    }
    return $data;
}

1;

__END__