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