NAME

File::UStore - Perl extension to store files on a filesystem using a non-hash UUID(Universally Unique Identifier) based randomised storage with depth of storage options.

SYNOPSIS

use File::UStore;
my $store = new File::UStore( path => "/home/shantanu/.teststore", 
                            prefix => "prefix_",
                            depth  => 5
                          );

open( my $FH, "foo.pl" ) or die "Unable to open file ";
# Add a file in the store
my $id = $store->add(*$FH);

# Return the filesystem location of an id
my $location = $store->getpath($id);

# Remove a file by its id from the store
$store->remove("7d4d873e-4bf4-41a5-8696-fd6232f7bdda");

DESCRIPTION

File::UStore is a perl library based on File::HStore module by Alexandre Dulaunoy to store files on a filesystem using a UUID based randomised storage with folder depth control over storage.

File::UStore is a library that allows users to abstract file storage using a UUID based pointer instead of File Hashes to store the file. This is a critical feature for code which requires even duplicate files to get a unique identifier each time they added to a store. A Hash Storage on the other hand will not allow a file to be duplicated if it is stored multiple time in the store. This can cause issues in cases where a files may be deleted regularly as there would be no way of knowing if a second process is still using the file which the first process might be about to delete.

The current version uses UUID Module to generate universally unique identifiers everytime a file is to be stored.

The Module also provides a option to choose the folder depth at which a file is stored. This can be changed from the default value of 3. Increasing depth is advisable if the Store might contain a large number of files in your use case. This helps avoid having an excessive number of files in any single folder.

METHODS

The object oriented interface to File::UStore is described in this section.

The following methods are provided:

$store = File::UStore->new( path => "/home/shantanu/.teststore", prefix => "prefix_", depth => 5 );

This constructor returns a new File::HFile object encapsulating a specific store. The path specifies where the UStore is located on the filesystem. If the path is not specified, the path ~/.hstore is used. The digest specifies the algorithm to be used (SHA-1 or SHA-2 or the submission date called FAT). If not specified, SHA-1 is used. Various digest can be mixed in the same path but the utility is somewhat limited. The $prefix is only an extension used for the FAT (Free Archive Format) format to specify the archive unique name.

$store->add($filename)

The $filename is the file to be added in the store. The return value is the id ($id) of the $filename stored. From this point on the user will only be able to refer to this file using the id. Return undef on error.

$store->getpath($id)

Return the filesystem location of the file from its id.

Return undef on error.

$store->remove($id)

The $id is the file to be removed from the store.

Return false on success and undef on error.

SEE ALSO

An Analysis of Compare-by-hash - for reasons why a UUID based storage may be preferred over hash based solution in certain cases. http://www.usenix.org/events/hotos03/tech/full_papers/henson/henson.pdf

AUTHOR

Shantanu Bhadoria, <shantanu (dot comes here) bhadoria at gmail dot com>

COPYRIGHT AND LICENSE

Copyright (C) 2011 by Shantanu Bhadoria <shantanu (dot comes here) bhadoria at gmail dot com>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of Perl 5 you may have available.

Dependencies

UUID

File::Copy

File::Path

File::Spec