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