NAME
Cantella::Store::UUID - UUID based file storage
DESCRIPTION
Cantella::Store::UUID stores documents in a deterministic location based on a UUID. Depending on the number of files to be stored, a store may use 1 or more levels. A level is composed of 16 directories (0-9 and A-F) nested to n depth. For Example, if a store has 3 levels, the path to file represented by UUID A5D45AF2-73D1-11DD-AA18-4B321EADD46B would be A/5/D/A5D45AF2-73D1-11DD-AA18-4B321EADD46B.
The goal is to provide a simple way to spread the storage of a large number of files over many directories to prevent any single directory from storing too-many files. Optionally, lower level tools can then be utilized to spread the underlying storage points accross different physical devices if necessary.
The number of final storage points available can be calculated by raising 16 to the nth power, where n is the number of nest levels.
Caution: The number of directories generated is actually larger than the number of final storage points because all directories in the hierarchy must be counted, thus the number of directories a store contains is (16^n) + (16^(n-1)) .. (16^1) + (16^0) and a 5 level deep hierarchy for all three storage points would create 3,355,443 directories. For this reason, any number larger than 4 is cautioned against.
SYNOPSYS
use Path::Class qw(file);
use Cantella::Store::UUID;
my $store = Cantella::Store::UUID->new(
root_dir => './test-cantella-store-uuid',
nest_levels => 3,
);
$store->deploy; #create the storage dirs (should only be done once)
my $new_uuid = $store->new_uuid;
{
my $source_file = file './some-file';
my $stored_file = $store->create_file($source_file, $new_uuid, {foo => 'bar'});
$source_file->remove; #it was copied into the storage
}
#this object is identical to the one returned by ->create_file
my $stored_file = $store->from_uuid($new_uuid);
print $stored_file->metadata->{foo}; #prints 'bar'
# $grep_results[0] eq $new_uuid#
my @grep_results = $store->grep_files(sub { exists shift->metadata->{foo}});
# $map_results[0] eq 'bar'
my @map_results = $store->grep_files(sub { $_->metadata->{foo}});ATTRIBUTES
Cantella::Store::UUID is a subclass of Moose::Object. It inherits the new object provided by Moose. All attributes can be set using the new constructor method, or their respecitive writer method, if applicable.
nest_levels
Required, read-only integer representing how many levels of depth to use in the directory structure.
The following methods are associated with this attribute:
root_dir
Required, read-only directory location for the root of the hierarchy.
file_class
Required, read-only class name. The class to use for stored file objects. Defaults to Cantella::Store::UUID::File.
METHODS
new
Constructor.
from_uuid
Return the apropriate file object for $uuid. Please note that this particular file does not neccesarily exist and its presence is not checked for. See exists.
new_uuid
Returns a new UUID object suitable for use with this module. By default, it currently uses Data::GUID.
create_file
Will copy the $original file into the the UUID storage and return the file object representing it. The key original_name will be automatically set on the metadata with the base name of the original file.
deploy
Create directory hierarchy, starting with root_dir. A call to deploy may take a couple of minutes or even hours depending on the value of nest_levels and the speed of the storage being utilized.
grep_files
Recurse the storage testing every file against $code_ref. Return all of the UUIDs where $code_ref returns a true value. The only argument given to $code_ref is a file object. The order in which files are tested and subsequently returned is undefined behavior and may change. Be aware that, depending on the number of @matching_ids and the number of documents stored, this method could take a very, very long time to finish and use considerable amounts of memory.
map_files
Recurse the storage executing $code_ref on every file. Return all of the values returned by $code_ref. The only argument given to $code_ref is a file object. The order in which files are tested and subsequently returned is undefined behavior and may change. Be aware that, depending on the result values and number of documents stored, this method could take a very, very long time to finish and use considerable amounts of memory.
_get_dir_for_uuid
Given a UUID, it returns the apropriate directory;
SEE ALSO
AUTHOR
Guillermo Roditi (groditi) <groditi@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2009, 2010 by Guillermo Roditi.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.