Badger::Storage::Filesystem

NAME

Top Close Open

Badger::Storage::Filesystem - filesystem-based persistent storage

SYNOPSIS

Top Close Open
use Badger::Storage::Filesystem;

# create a storage object - path is required, codec is optional
my $storage = Badger::Storage::Filesystem->new(
    path  => '/path/to/dir',
    codec => 'yaml',            # default codec is Storable
);

# some sample data
my $data = {
    message => 'Hello World!',
    numbers => [1.618, 2.718, 3.142],
};

# create a new record
my $id = $storage->create($data);

# fetch data for identifier - returns undef if not found
$data = $storage->fetch($id)
    || die $storage->error;

# insert/update data using identifier
$storage->store($id, $data);

# delete data using identifier
$storage->store($id, $data);

DESCRIPTION

Top Close Open

The Badger::Storage::Filesystem module is a subclass of Badger::Storage for storing data in files on your local filesystem.

METHODS

Top Close Open

The following methods are implemented in addition to those inherited from the Badger::Storage, Badger::Prototype and Badger::Base base classes.

All the methods listed below raise errors by throwing Badger::Exception objects (as is the convention for all Badger modules). Note that in the specific cases of the fetch() and delete() methods, it is not considered an error to attempt to fetch or delete a record that does not exists. In this case, the methods will call decline() and return undef.

If your application logic dictates that a particular resource must exist then you should add your own code to test the return value and upgrade it to an error if necessary.

my $data = $storage->fetch($id)
    || die "Could not fetch data: ", $storage->error;

In all other cases you can effectively ignore error handling at the lower level. For example, there is no need to check the return value of the store() method. If it returns then it has succeeded. If it fails then an exception will be thrown.

$storage->store;

Depending on the environment you're programming in, you can either let the exception terminate the program with the error message (e.g. for a command line script), or trap it at a higher level using eval or try() and present it to the user in an appropriate way (e.g. generating an error page for a web application).

create($data)

Top Close Open

The create() method first calls the the generate_id() method to generate a new identifier for the data. It then call the store() method, passing the identifier along with the data passed to it as an argument. It returns the newly created identifier.

my $id = $storage->create($data);

It returns the newly created identifier for the data record. Errors are thrown as exceptions. You can use the try() method inherited from Badger::Base if you want to catch any exceptions.

my $id = $storage->try->create($data)
    || warn $storage->error;

This is equivalent to:

my $id = eval { $storage->create($data) }
    || warn $storage->error;

store($id,$data)

Top Close Open

This method is used to store data. The first argument is a unique identifier for the data. The second argument should be a reference to the data to be stored (e.g. a hash or list reference).

$storage->store($id, $data);

It returns a true value which you can test if you want the warm glow of satisfaction that it performed its job as expected.

if ($storage->store($id, $data)) {
    # phew!
}

However, all errors are thrown as exceptions so there's no need to test the return value at all. If the method returns, then it succeeded. You can use eval { } if you want to trap errors, or the try() method, as shown in the documentation for create().

fetch($id)

Top Close Open

This method is used to fetch data. The single argument is a unique identifier for the data, such as that returned by a previous call to the create() method, or passed as the first argument in a call to the store() method.

my $data = $storage->fetch($id);

If the data cannot be found then the method returns undef by calling its own decline() method (inherited from Badger::Base). You can call the error() method to view the message generated.

my $data = $storage->fetch('foo')
    || print $storage->error;       # e.g. File not found: foo

It is important to understand the difference between the method declining to return a value and an error. If the data for the requested identifier cannot be found then the method returns undef by calling its own decline() method. This is considered part of its normal operation. It is not an error to ask for something that doesn't exists. The method will politely turn you away.

On the other hand, if the method is prevented from looking for the data and either returning it or declining, for whatever reason, then an exceptions will be thrown. It could be that the the file contents got mangled, the database is offline, the network is down, or maybe you forgot to pass an identifier as a parameter. These are all error conditions that are considered outside of normal operation.

If your application dictates that a missing resource is an error then you should add the appropriate code to any call to fetch(). For example, if your application is loading a configuration file then you probably want to know right away if the configuration file is missing, misnamed, or otherwise unloaded for whatever reason.

my $config = $storage->fetch( $config_file_name )
    || die $storage->error;

delete($id)

Top Close Open

Permanently deletes the data associated with the identifier passed as an argument.

$storage->delete($id);

Returns a true value on success. If the data does not exist then it returns undef. All errors are thrown as exceptions. As with fetch(), deleting a resource that does not exists is not considered an error. The method will decline() gracefully.

INTERNAL METHODS

Top Close Open

init_storage($config)

Top Close Open

This method should be redefined by subclasses to perform any storage-specific initialisation.

generate_id(@args)

Top Close Open

This method is called by the create() method to generate a new identifier for the data record. It is passed all the arguments that were passed to the create() method. In the base class this method generates a random MD5 hex string. Subclasses can redefine it to do something different.

AUTHOR

Top Close Open

Andy Wardley http://wardley.org

COPYRIGHT

Top Close Open

Copyright (C) 2007-2009 Andy Wardley. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Fork Me on Github