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