Test::AutoBuild::ArchiUsernContributed Perl Test::AutoBuild::ArchiveManager(3)NAMETest::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 ALSOperl(1), Test::AutoBuild, Test::AutoBuild::Runtime
perl v5.14.12011-09-01Test::AutoBuild::ArchiveManager(3)
