/ 
Test-AutoBuild-1.2.4
River stage zero No dependents
/ Test::AutoBuild::Archive

NAME

Test::AutoBuild::Archive - archival of files and metadata

SYNOPSIS

  my $manager = [...get instance of Test::AutoBuild::ArchiveManager...]
  my $archive = $manager->get_current_archive;

  my %orig_files = (
    "/usr/src/redhat/RPMS/noarch/autobuild-1.0.0-1.noarch.pm" => ...metadata...
  );

  # Save status of the 'build' action for module 'autobuild-dev'
  $archive->save_data("autobuild-dev",
		      "build",
		      "success");

  # Save list of packages associated with module 'autobuild-dev'
  $archive->save_files("autobuild-dev",
		       "packages",
		       \%orig_files,
		       { link => 1,
			 move => 1,
			 base => "/usr/src/redhat"});


  # Retrieve status of the 'build' action for module 'autobuild-dev'
  my $status = $archive->get_data("autobuild-dev",
				  "build");

  # Retrieve metadata associated with saved files
  my $metadat = $archive->get_files("autobuild-dev",
				    "packages");

  # Save RPMSs to an HTTP site
  $archive->extract_files("autobuild-dev",
			  "packages",
			  "/var/www/html/packages/autobuild-dev",
			  { link => 1 });

DESCRIPTION

The Test::AutoBuild::Archive module provides an API for associating chunks of data and files, with objects, persisting them to some form of storage. Each object in the archive is uniquely identified by an alphanumeric string, and can in turn contain many storage buckets, again uniquely identified by an alphanumeric string. An individual bucket can store a chunk of metadata, and a set of files at any one time. Each file stored can also have a chunk of associated metadata. Conceptually the organization of an archive is thus

ROOT
 |
 +- myobject
 |   |
 |   +- mybucket
 |   |   |
 |   |   +- DATA       - chunk of generic metadata
 |   |   +- FILES      - set of files
 |   |   +- FILE-DATA  - chunk of metadata about FILES
 |   |
 |   +- otherbucket
 |   |   |
 |   |   +- DATA       - chunk of generic metadata
 |   |   +- FILES      - set of files
 |   |   +- FILE-DATA  - chunk of metadata about FILES
 |   |
 |   +- ...
 |
 +- otherobject
 |   |
 |   +- mybucket
 |   |   |
 |   |   +- DATA       - chunk of generic metadata
 |   |   +- FILES      - set of files
 |   |   +- FILE-DATA  - chunk of metadata about FILES
 |   |
 |   +- otherbucket
 |   |   |
 |   |   +- DATA       - chunk of generic metadata
 |   |   +- FILES      - set of files
 |   |   +- FILE-DATA  - chunk of metadata about FILES
 |   |
 |   +- ...
 |
 +- ...

METHODS

$archive->save_data($object, $bucket, $data);

Save a chunk of data $data associated with object $object into the storage bucket named $bucket. Both the $object and $bucket parameters must be plain strings comprising characters from the set 'a'..'z','A'..'Z','0'-'9','-','_' and '.'. The $data can be comprised scalars, array references and hash references. Code references and file handles are forbidden. If there is already data present in the bucket $bucket associated with the object $object then an error will be thrown. The data can later be retrieved from the archive by calling the get_data method with matching arguments for object and bucket.

$archive->save_files($object, $bucket, $files, $options)

Saves a set of files $files associated with object $object into the storage bucket named $bucket. Both the $object and $bucket parameters must be plain strings comprising characters from the set 'a'..'z','A'..'Z','0'-'9','-','_' and '.'. The $files parameter should be a hash reference where the keys are fully qualified file names, and the values are arbitrary chunks of data, comprised of scalars, array references and hash references. Code references and file handles are forbidden. If there are already files present in the bucket $bucket associated with the object $object then an error will be thrown. The data can later be retrieved from the archive by calling the extract_files method with matching arguments for object and bucket. A listing of files stored in the archive can be retrieved by calling the method get_files with matching arguments for object and bucket. The $options parameter controls the way in which the files are stored. It can contain the following keys

Attempt to hardlink the files into the archive, rather than doing a regular copy. In combination with same option on the extra_files and attach_files methods, this allows for considerable conversation of disk space, by only ever having one copy of the data no matter how many locations the file is kept. Care must be taken, however, to ensure that the contents of the original file is not modified after the archive is saved. If omitted, defaults to 0.

move

Delete the original file after copying it into the archive. This can also be used in combination with the link option as protect. If omitted, defaults to 0

base

When storing the filenames, trim the directory prefix specified by the value to this option, off the front of the filenames to form a relative filename. This can be useful when later extracting the files back out to an alternate directory. If omitted, defaults to the root directory.

flatten

When storing the filenames, trim off the entire directory prefix, only maintaining the basic filename. If two files have the same filename after trimming, an error will be thrown. If omitted, defaults to 0.

This method returns a hash reference, whose keys are the filenames saved, relative to the value associated with the base key in the $options parameter.

$archive->_save_metadata($object, $bucket, $datatype, $data);

This an internal method to be implemented by subclasses, to provide the actual storage for metadata. The $object and $bucket parameters are as per the save_data or save_files methods. The datatype parameter is a key, either DATA to indicate general metadata being saved, or FILES to indicate the per file metadata. Finally, the $data parameter is the actual data to be saved, which may be a scalar, hash reference or array reference, nested to arbitrary depth. Implementations must throw an error if the archive already contains data stored against the tuple ($object,$bucket,$type).

my $copied = $archive->clone_files($object, $bucket, $archive, $options);

This method copies the files associated with the object $object in bucket $bucket in the archive $archive over to this archive. If the link key is specified as an option, then implementations are free to implement this as a zero-copy operation to save storage. This method returns a hash reference whose keys are the list of filenames, relative to their original base directory, and whose values are the metadata associated with each file.

$archive->_persist_files($object, $bucket, $files, $options);

This an internal method to be implemented by subclasses, to provide the actual storage for metadata. The $object and $bucket parameters are as per the save_data or save_files methods. The $files parameter is a hash reference detailing the files to be persisted. The keys of the hash reference are filenames relative to the directory specified by the base key in the $options parameter. The $options parameter can also contain the keys link to indicate zero-copy persistence of files, and move to indicate the original file should be deleted.

my @objects = $archive->list_objects

Retrieves a list of all objects which have either files or metadata stored in this archive. The returned list of objects is sorted alphabetically.

my @objects = $archive->_get_objects

This is an internal method used to retrieve the list of objects stored in the archive. This should return a list of objects stored, but need not sort them in any particular order. This method must be implemented by subclasses.

my @buckets = $archive->list_buckets($object)

Retrieves a list of all storage buckets associated with the object $object. The returned list of buckets is not sorted in any particular order. If the object $object is not stored in this archive, then the empty list is to be returned. This method must be implemented by subclasses.

my $data = $archive->get_data($object, $bucket);

Retrieves the data in the bucket $bucket associated with the object $object, which was previously stored with the save_data method.

AUTHORS

Dennis Gregorovic <dgregorovic@alum.mit.edu>, Daniel Berrange <dan@berrange.com>

COPYRIGHT

Copyright (C) 2003-2004 Dennis Gregorovic <dgregorovic@alum.mit.edu>, Copyright (C) 2005 Daniel Berrange <dan@berrange.com>

SEE ALSO

perl(1), Test::AutoBuild::ArchiveManager, Test::AutoBuild::Archive::File