1Test::AutoBuild::ArchivUesMearnaCgoenrt(r3i)buted Perl DToecsutm:e:nAtuattoiBounild::ArchiveManager(3)
2
6 Test::AutoBuild::ArchiveManager - The base class for managing archive
7
9 # Create a manager (must be some subclass)
10 use Test::AutoBuild::ArchiveManager::XXX;
11 my $manager = Test::AutoBuild::Manager::XXX->new()
12 # Create a new archive, keyed off current time
15 $manager->create_archive(time);
16 # Get current archive & store some stuff
19 my $archive = $manager->get_current_archive
20 $archive->save_data("myobject", "build", { status => "failed" });
21 # Get prevous archive, aka the 'cache' from last cycle
24 my $cache = $manager->get_previous_archive
25 if ($cache->has_data("myobject", "build")) {
26 my $build = $cache->get_data("myobject", "build");
27 print "Previous status was ", $build->{status};
28 }
29 # Purge invalid archives
32 foreach ($manager->list_invalid_archives) {
33 $manager->delete_archive($_->key);
34 }
35
37 The "Test::AutoBuild::ArchiveManager" module provides capabilities for
38 managing a set of "Test::AutoBuild::Archive" instances. It provides
39 apis for creation, deletion and retrieval of archive intances, and for
40 determining when an archive should be expired. This module is an
41 abstract base class providing generic functionality, and is intended to
42 be subclassed to provide functionality specific to the backend storage
43 system. It works hand in hand with the Test::AutoBuild::Archive module
44 which defines APIs for working with a single archive intance.
45 The most commonly used subclass is
47 Test::AutoBuild::ArchiveManager::File which provides for management of
48 archives stored on local filesystem, via the
49 Test::AutoBuild::Archive::File module. For demo & test purposes there
50 is also an in-memory manager Test::AutoBuild::ArchiveManager::Memory,
51 although obviously this should not be used for large scale archives,
52 since it stores absolutely everything in RAM.
53
55 There are three methods which must be implemented by all subclasses;
56 The default implementations of these methods simply call "die",
57 informing the caller that the subclass forgot to override them.
58 list_archives
60 To retrieve a list of all archives currently managed. This will
61 later be filtered to separate out current / expired archives.
62 create_archive
64 To create a new empty instance of the Test::AutoBuild::Archive
65 subclass related to this module
66 delete_archive
68 To delete an instance of Test::AutoBuild::Archive no longer
69 required.
70
72 my $manager = Test::AutoBuild::ArchiveManager->new('max-age' => $age,
73 'max-instance' => $count, 'max-size' => $size, 'options' => \%options);
74 This method creates a new archive manager instance. This method is
75 not for use by end users since this is an abstract base class;
76 indeed this metohd will die unless the class being constructed is a
77 subclass. The "max-age" parameter is used to set the "max_age"
78 property, defaulting to "7d". The "max-size" parameter is used to
79 set the "max_size" property defaulting to "1g". The "max-instance"
80 parameter is used to set the "max_instance" property defaulting to
81 10. The final "options" parameter is a hash reference containing
82 arbitrary key, value pairs. These are not used by this class,
83 however, may be used by subclasses for implementation specific
84 configuration parameters.
85 my $value = $manager->option($name[, $newvalue]);
87 Retrieves the subclass specific configuration option specified by
88 the $name parameter. If there is no stored option associated with
89 the key $name, then "undef" is returned. If the $newvalue parameter
90 is supplied, then the stored option value is updated.
91 my $archive = $manager->get_current_archive();
93 This retrieves the most recently created, and still valid, archive
94 instance managed by this object. If there are no valid archives
95 currently managed, this returns "undef". This is the method one
96 would typically use to retrieve the archive into which the current
97 build cycle's results will be stored.
98 my $archive = $manager->get_previous_archive();
100 This retrieves the second most recently created, and still valid
101 archive instance managed by this object. If there are less than two
102 valid archives managed, this returns "undef". This is the method
103 one would typically use to retrieve the archive from which the
104 previous build cycle's results can be extracted.
105 my $archive = $manager->create_archive($key);
107 This creates a new instance of the Test::AutoBuild::Archive
108 subclass used by this object, assigning it the unique key $key.
109 Archive keys should be generated such that when comparing the keys
110 for two archives, the key associated with the newest archive
111 compares numerically larger than that of the older archive. For
112 all intents & purposes this means, that keys should be
113 monotonically increasing integers. New prescence of a newly created
114 archive is immediately reflected by the other methods in this
115 class. ie, what was the 'current archive' is will become the
116 'previous archive', and the new archive will be the new 'previous
117 archive'. Any expiry / validity rules will also immediately take
118 effect, for example 'max-instances' may cause an older archive to
119 become invalid. This method must be overriden by subclass, since
120 the default implementation will simply call "die".
121 $manager->delete_archive($key);
123 This deletes archive instance associated with this manager which
124 has the key $key. If there is no matching achive instance, this
125 method will call "die". The deletion of an archive is immediately
126 reflected by the other methods in this class. This method must be
127 overriden by subclass, since the default implementation will simply
128 call "die".
129 my @archives = $manager->list_archives;
131 Returns a list of all archive instances, valid or not, currently
132 managed by this manager object. The archive instances will be some
133 subclass of Test::AutoBuild::Archive applicable to this manager
134 object. The list will be sorted such that the oldest archive is the
135 first in the list, while the newest archive is the last in the
136 list. This method must be overriden by subclasses, since the
137 default implementation simply calls "die".
138 my @archives = $manager->list_invalid_archives;
140 Returns a list of all invalid archive instances currently managed
141 by this manager. An archive is invalid, if its inclusion in the
142 list would cause any of the "max-size", "max-instance", or
143 "max-age" constraints to be violated. Invalid archives are
144 typically candidates for immediate deletion.
145
147 The following properties each have a correspondingly named method which
148 supports getting & setting of the property value. The getter is the no-
149 arg version, while the setter is the one-argument version. eg,
150 my $age = $manager->max_age
152 $manager->max_age("7d");
153 max_age
155 This property controls how long an archive can exist before it is
156 considered invalid & thus a candidate for removal. It is
157 represented as an integer, followed by a unit specifier, eg '7d'
158 for seven days, '8h' for eight hours, or '9m' for nine minutes.
159 max_instance
161 This property specifies the total number of archive instances to
162 create before beginning to mark old archives as invalid. It is
163 simply an integer count.
164 max_size
166 This property controls the maximum storage to allow to be consumed
167 by all managed archives. It is represented as an integer followed
168 by a unit specifier, eg '1g' for 1 gigabyte, or '2m' for 2
169 megabytes.
170
172 Although nicely documented, the "max_instance" and "max_size"
173 properties are not currently used when determining list of invalid
174 archives. This ommision ought to be fixed at some point....
175
177 Daniel Berrange <dan@berrange.com>, Dennis Gregorovic
178 <dgregorovic@alum.mit.edu>
179
181 Copyright (C) 2004-2005 Dennis Gregorovic, Daniel Berrange
182
184 perl(1), Test::AutoBuild, Test::AutoBuild::Runtime
185perl v5.12.1 2007-12-08Test::AutoBuild::ArchiveManager(3)