1Test::AutoBuild::ArchivUes(e3r)Contributed Perl DocumentTaetsito:n:AutoBuild::Archive(3)
2
6 Test::AutoBuild::Archive - archival of files and metadata
7
9 my $manager = [...get instance of Test::AutoBuild::ArchiveManager...]
10 my $archive = $manager->get_current_archive;
11 my %orig_files = (
13 "/usr/src/redhat/RPMS/noarch/autobuild-1.0.0-1.noarch.pm" => ...metadata...
14 );
15 # Save status of the 'build' action for module 'autobuild-dev'
17 $archive->save_data("autobuild-dev",
18 "build",
19 "success");
20 # Save list of packages associated with module 'autobuild-dev'
22 $archive->save_files("autobuild-dev",
23 "packages",
24 \%orig_files,
25 { link => 1,
26 move => 1,
27 base => "/usr/src/redhat"});
28 # Retrieve status of the 'build' action for module 'autobuild-dev'
30 my $status = $archive->get_data("autobuild-dev",
31 "build");
32 # Retrieve metadata associated with saved files
34 my $metadat = $archive->get_files("autobuild-dev",
35 "packages");
36 # Save RPMSs to an HTTP site
38 $archive->extract_files("autobuild-dev",
39 "packages",
40 "/var/www/html/packages/autobuild-dev",
41 { link => 1 });
42
44 The "Test::AutoBuild::Archive" module provides an API for associating
45 chunks of data and files, with objects, persisting them to some form of
46 storage. Each object in the archive is uniquely identified by an
47 alphanumeric string, and can in turn contain many storage buckets,
48 again uniquely identified by an alphanumeric string. An individual
49 bucket can store a chunk of metadata, and a set of files at any one
50 time. Each file stored can also have a chunk of associated metadata.
51 Conceptually the organization of an archive is thus
52 ROOT
54 ⎪
55 +- myobject
56 ⎪ ⎪
57 ⎪ +- mybucket
58 ⎪ ⎪ ⎪
59 ⎪ ⎪ +- DATA - chunk of generic metadata
60 ⎪ ⎪ +- FILES - set of files
61 ⎪ ⎪ +- FILE-DATA - chunk of metadata about FILES
62 ⎪ ⎪
63 ⎪ +- otherbucket
64 ⎪ ⎪ ⎪
65 ⎪ ⎪ +- DATA - chunk of generic metadata
66 ⎪ ⎪ +- FILES - set of files
67 ⎪ ⎪ +- FILE-DATA - chunk of metadata about FILES
68 ⎪ ⎪
69 ⎪ +- ...
70 ⎪
71 +- otherobject
72 ⎪ ⎪
73 ⎪ +- mybucket
74 ⎪ ⎪ ⎪
75 ⎪ ⎪ +- DATA - chunk of generic metadata
76 ⎪ ⎪ +- FILES - set of files
77 ⎪ ⎪ +- FILE-DATA - chunk of metadata about FILES
78 ⎪ ⎪
79 ⎪ +- otherbucket
80 ⎪ ⎪ ⎪
81 ⎪ ⎪ +- DATA - chunk of generic metadata
82 ⎪ ⎪ +- FILES - set of files
83 ⎪ ⎪ +- FILE-DATA - chunk of metadata about FILES
84 ⎪ ⎪
85 ⎪ +- ...
86 ⎪
87 +- ...
88
90 $archive->save_data($object, $bucket, $data);
91 Save a chunk of data $data associated with object $object into the
92 storage bucket named $bucket. Both the $object and $bucket parame‐
93 ters must be plain strings comprising characters from the set
94 'a'..'z','A'..'Z','0'-'9','-','_' and '.'. The $data can be com‐
95 prised scalars, array references and hash references. Code refer‐
96 ences and file handles are forbidden. If there is already data
97 present in the bucket $bucket associated with the object $object
98 then an error will be thrown. The data can later be retrieved from
99 the archive by calling the "get_data" method with matching argu‐
100 ments for object and bucket.
101 $archive->save_files($object, $bucket, $files, $options)
103 Saves a set of files $files associated with object $object into the
104 storage bucket named $bucket. Both the $object and $bucket parame‐
105 ters must be plain strings comprising characters from the set
106 'a'..'z','A'..'Z','0'-'9','-','_' and '.'. The $files parameter
107 should be a hash reference where the keys are fully qualified file
108 names, and the values are arbitrary chunks of data, comprised of
109 scalars, array references and hash references. Code references and
110 file handles are forbidden. If there are already files present in
111 the bucket $bucket associated with the object $object then an error
112 will be thrown. The data can later be retrieved from the archive by
113 calling the "extract_files" method with matching arguments for
114 object and bucket. A listing of files stored in the archive can be
115 retrieved by calling the method "get_files" with matching arguments
116 for object and bucket. The $options parameter controls the way in
117 which the files are stored. It can contain the following keys
118 link
120 Attempt to hardlink the files into the archive, rather than
121 doing a regular copy. In combination with same option on the
122 "extra_files" and "attach_files" methods, this allows for con‐
123 siderable conversation of disk space, by only ever having one
124 copy of the data no matter how many locations the file is kept.
125 Care must be taken, however, to ensure that the contents of the
126 original file is not modified after the archive is saved. If
127 omitted, defaults to 0.
128 move
130 Delete the original file after copying it into the archive.
131 This can also be used in combination with the "link" option as
132 protect. If omitted, defaults to 0
133 base
135 When storing the filenames, trim the directory prefix specified
136 by the value to this option, off the front of the filenames to
137 form a relative filename. This can be useful when later
138 extracting the files back out to an alternate directory. If
139 omitted, defaults to the root directory.
140 flatten
142 When storing the filenames, trim off the entire directory pre‐
143 fix, only maintaining the basic filename. If two files have the
144 same filename after trimming, an error will be thrown. If omit‐
145 ted, defaults to 0.
146 This method returns a hash reference, whose keys are the filenames
148 saved, relative to the value associated with the "base" key in the
149 $options parameter.
150 $archive->_save_metadata($object, $bucket, $datatype, $data);
152 This an internal method to be implemented by subclasses, to provide
153 the actual storage for metadata. The $object and $bucket parameters
154 are as per the "save_data" or "save_files" methods. The "datatype"
155 parameter is a key, either "DATA" to indicate general metadata
156 being saved, or "FILES" to indicate the per file metadata. Finally,
157 the $data parameter is the actual data to be saved, which may be a
158 scalar, hash reference or array reference, nested to arbitrary
159 depth. Implementations must throw an error if the archive already
160 contains data stored against the tuple ($object,$bucket,$type).
161 my $copied = $archive->clone_files($object, $bucket, $archive,
163 $options);
164 This method copies the files associated with the object $object in
165 bucket $bucket in the archive $archive over to this archive. If the
166 "link" key is specified as an option, then implementations are free
167 to implement this as a zero-copy operation to save storage. This
168 method returns a hash reference whose keys are the list of file‐
169 names, relative to their original base directory, and whose values
170 are the metadata associated with each file.
171 $archive->_persist_files($object, $bucket, $files, $options);
173 This an internal method to be implemented by subclasses, to provide
174 the actual storage for metadata. The $object and $bucket parameters
175 are as per the "save_data" or "save_files" methods. The $files
176 parameter is a hash reference detailing the files to be persisted.
177 The keys of the hash reference are filenames relative to the direc‐
178 tory specified by the "base" key in the $options parameter. The
179 $options parameter can also contain the keys "link" to indicate
180 zero-copy persistence of files, and "move" to indicate the original
181 file should be deleted.
182 my @objects = $archive->list_objects
184 Retrieves a list of all objects which have either files or metadata
185 stored in this archive. The returned list of objects is sorted
186 alphabetically.
187 my @objects = $archive->_get_objects
189 This is an internal method used to retrieve the list of objects
190 stored in the archive. This should return a list of objects stored,
191 but need not sort them in any particular order. This method must be
192 implemented by subclasses.
193 my @buckets = $archive->list_buckets($object)
195 Retrieves a list of all storage buckets associated with the object
196 $object. The returned list of buckets is not sorted in any particu‐
197 lar order. If the object $object is not stored in this archive,
198 then the empty list is to be returned. This method must be imple‐
199 mented by subclasses.
200 my $data = $archive->get_data($object, $bucket);
202 Retrieves the data in the bucket $bucket associated with the object
203 $object, which was previously stored with the "save_data" method.
204
206 Dennis Gregorovic <dgregorovic@alum.mit.edu>, Daniel Berrange
207 <dan@berrange.com>
208
210 Copyright (C) 2003-2004 Dennis Gregorovic <dgregorovic@alum.mit.edu>,
211 Copyright (C) 2005 Daniel Berrange <dan@berrange.com>
212
214 perl(1), Test::AutoBuild::ArchiveManager, Test::AutoBuild::Ar‐
215 chive::File
216perl v5.8.8 2007-12-09 Test::AutoBuild::Archive(3)