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:

nest_levels - reader

root_dir

root_dir - reader

Required, read-only directory location for the root of the hierarchy.

file_class

file_class - reader

Required, read-only class name. The class to use for stored file objects. Defaults to Cantella::Store::UUID::File.

METHODS

new

arguments: \%arguments

return value: $object_instance

Constructor.

from_uuid

arguments: $uuid

return value: $file_object

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

arguments: none

return value: $uuid

Returns a new UUID object suitable for use with this module. By default, it currently uses Data::GUID.

create_file

arguments: $original, $uuid, $metadata

return value: $file_object

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

arguments: none

return value: none

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

arguments: $code_ref

return value: @matching_uuids

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

arguments: $code_ref

return value: @return_values

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

arguments: $uuid

return value: Path::Class::Dir $dir

Given a UUID, it returns the apropriate directory;

SEE ALSO

Cantella::Store::UUID::File

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.

cpanm Cantella::Store::UUID

perl -MCPAN -e shell
install Cantella::Store::UUID