Linux Certif

Toute la documentation sur la certification Linux LPI

Test::AutoBuild::ArchiveManager.3pm

NAME

Test::AutoBuild::ArchiveManager - The base class for managing archive

SYNOPSIS

   # Create a manager (must be some subclass)
   use Test::AutoBuild::ArchiveManager::XXX;
   my $manager = Test::AutoBuild::Manager::XXX->new()
 
 
   # Create a new archive, keyed off current time
   $manager->create_archive(time);
 
 
   # Get current archive & store some stuff
   my $archive = $manager->get_current_archive
   $archive->save_data("myobject", "build", { status => "failed" });
 
 
   # Get prevous archive, aka the 'cache' from last cycle
   my $cache = $manager->get_previous_archive
   if ($cache->has_data("myobject", "build")) {
     my $build = $cache->get_data("myobject", "build");
     print "Previous status was ", $build->{status};
   }
 
 
   # Purge invalid archives
   foreach ($manager->list_invalid_archives) {
     $manager->delete_archive($_->key);
   }
 
 

DESCRIPTION

The "Test::AutoBuild::ArchiveManager" module provides capabilities for managing a set of "Test::AutoBuild::Archive" instances. It provides apis for creation, deletion and retrieval of archive intances, and for determining when an archive should be expired. This module is an abstract base class providing generic functionality, and is intended to be subclassed to provide functionality specific to the backend storage system. It works hand in hand with the Test::AutoBuild::Archive module which defines APIs for working with a single archive intance.

The most commonly used subclass is Test::AutoBuild::ArchiveManager::File which provides for management of archives stored on local filesystem, via the Test::AutoBuild::Archive::File module. For demo & test purposes there is also an in-memory manager Test::AutoBuild::ArchiveManager::Memory, although obviously this should not be used for large scale archives, since it stores absolutely everything in RAM.

SUBCLASSING

There are three methods which must be implemented by all subclasses; The default implementations of these methods simply call "die", informing the caller that the subclass forgot to override them.

list_archives

To retrieve a list of all archives currently managed. This will later be filtered to separate out current / expired archives.

create_archive

To create a new empty instance of the Test::AutoBuild::Archive subclass related to this module

delete_archive

To delete an instance of Test::AutoBuild::Archive no longer required.

METHODS

my $manager = Test::AutoBuild::ArchiveManager->new('max-age' => $age, 'max-instance' => $count, 'max-size' => $size, 'options' => \%options);

This method creates a new archive manager instance. This method is not for use by end users since this is an abstract base class; indeed this metohd will die unless the class being constructed is a subclass. The "max-age" parameter is used to set the "max_age" property, defaulting to "7d". The "max-size" parameter is used to set the "max_size" property defaulting to "1g". The "max-instance" parameter is used to set the "max_instance" property defaulting to 10. The final "options" parameter is a hash reference containing arbitrary key, value pairs. These are not used by this class, however, may be used by subclasses for implementation specific configuration parameters.

my $value = $manager->option($name[, $newvalue]);

Retrieves the subclass specific configuration option specified by the $name parameter. If there is no stored option associated with the key $name, then "undef" is returned. If the $newvalue parameter is supplied, then the stored option value is updated.

my $archive = $manager->get_current_archive();

This retrieves the most recently created, and still valid, archive instance managed by this object. If there are no valid archives currently managed, this returns "undef". This is the method one would typically use to retrieve the archive into which the current build cycle's results will be stored.

my $archive = $manager->get_previous_archive();

This retrieves the second most recently created, and still valid archive instance managed by this object. If there are less than two valid archives managed, this returns "undef". This is the method one would typically use to retrieve the archive from which the previous build cycle's results can be extracted.

my $archive = $manager->create_archive($key);

This creates a new instance of the Test::AutoBuild::Archive subclass used by this object, assigning it the unique key $key. Archive keys should be generated such that when comparing the keys for two archives, the key associated with the newest archive compares numerically larger than that of the older archive. For all intents & purposes this means, that keys should be monotonically increasing integers. New prescence of a newly created archive is immediately reflected by the other methods in this class. ie, what was the 'current archive' is will become the 'previous archive', and the new archive will be the new 'previous archive'. Any expiry / validity rules will also immediately take effect, for example 'max-instances' may cause an older archive to become invalid. This method must be overriden by subclass, since the default implementation will simply call "die".

$manager->delete_archive($key);

This deletes archive instance associated with this manager which has the key $key. If there is no matching achive instance, this method will call "die". The deletion of an archive is immediately reflected by the other methods in this class. This method must be overriden by subclass, since the default implementation will simply call "die".

my @archives = $manager->list_archives;

Returns a list of all archive instances, valid or not, currently managed by this manager object. The archive instances will be some subclass of Test::AutoBuild::Archive applicable to this manager object. The list will be sorted such that the oldest archive is the first in the list, while the newest archive is the last in the list. This method must be overriden by subclasses, since the default implementation simply calls "die".

my @archives = $manager->list_invalid_archives;

Returns a list of all invalid archive instances currently managed by this manager. An archive is invalid, if its inclusion in the list would cause any of the "max-size", "max-instance", or "max-age" constraints to be violated. Invalid archives are typically candidates for immediate deletion.

PROPERTIES

The following properties each have a correspondingly named method which supports getting & setting of the property value. The getter is the no-arg version, while the setter is the one-argument version. eg,

   my $age = $manager->max_age
   $manager->max_age("7d");
 
 

max_age

This property controls how long an archive can exist before it is considered invalid & thus a candidate for removal. It is represented as an integer, followed by a unit specifier, eg '7d' for seven days, '8h' for eight hours, or '9m' for nine minutes.

max_instance

This property specifies the total number of archive instances to create before beginning to mark old archives as invalid. It is simply an integer count.

max_size

This property controls the maximum storage to allow to be consumed by all managed archives. It is represented as an integer followed by a unit specifier, eg '1g' for 1 gigabyte, or '2m' for 2 megabytes.

BUGS

Although nicely documented, the "max_instance" and "max_size" properties are not currently used when determining list of invalid archives. This ommision ought to be fixed at some point....

AUTHORS

Daniel Berrange <dan@berrange.com>, Dennis Gregorovic <dgregorovic@alum.mit.edu>

COPYRIGHT

Copyright (C) 2004-2005 Dennis Gregorovic, Daniel Berrange

SEE ALSO

perl(1), Test::AutoBuild, Test::AutoBuild::Runtime