NAME

Storage::Abstract::Driver - Base class for drivers

SYNOPSIS

package Storage::Abstract::Driver::MyDriver;

use Moo;
extends 'Storage::Abstract::Driver';

# consume one of those roles
with 'Storage::Abstract::Role::Driver::Basic';
with 'Storage::Abstract::Role::Driver::Meta';

# these methods need implementing
sub store_impl { ... }
sub is_stored_impl { ... }
sub retrieve_impl { ... }
sub dispose_impl { ... }
sub list_impl { ... }

DESCRIPTION

This class contains the interface of handling files via Storage::Abstract (as discussed in "Delegated methods" in Storage::Abstract), a couple of unimplemented methods which must be implemented in the subclasses, and a couple of helpers which may be used or reimplemented in the subclasses when needed.

This class should never be instantiated directly. Its subclasses should consume one of the roles, either Storage::Abstract::Role::Driver::Basic or Storage::Abstract::Role::Driver::Meta.

INTERFACE

Attributes

These attributes are common to all drivers.

readonly

Boolean - whether this driver is readonly. False by default. May be changed using set_readonly.

This attribute is not applicable to meta drivers. This type of drivers don't store its own readonly status, so this attribute is used as a cache for the underlying drivers readonly status. Calling set_readonly on meta drivers will call set_readonly of the underlying driver and refresh the cache. If the meta driver holds more than one source (for example Storage::Abstract::Driver::Composite), calling set_readonly will throw an exception.

Helper methods

These methods may be used by drivers to make implementation easier.

resolve_path

$path = $obj->resolve_path($path)

This normalizes the path as discussed in "File paths" in Storage::Abstract. It is guaranteed to be called automatically every time one of the delegated methods is called, before the path is used for anything. As such, it can be reimplemented in a driver class to modify its behavior (see Storage::Abstract::Driver::Directory for an example).

common_properties

my $properties = $obj->common_properties($handle);

This returns a hash reference containing a list of properties with default values. Note that this does not get all these properties from $handle, but instead produces a new list of properties for drivers which must create it themselves (like Storage::Abstract::Driver::Memory).

Implementation methods

These methods must be reimplemented in driver classes:

• store_impl

  store_impl($path, $fh)

  The implementation of storing a new file in the storage. It will be passed a normalized path and an open file handle. For drivers implementing Storage::Abstract::Role::Driver::Basic, $fh will be a tied object of Storage::Abstract::Handle.

  Its return value will be ignored.

• is_stored_impl

  is_stored_impl($path)

  The implementation of checking whether a file is stored. It will be passed a normalized path. Must return a boolean.

• retrieve_impl

  retrieve_impl($path, \%properties)

  The implementation of retrieving a file. First argument is a normalized path. Second argument may be undef, but when it is defined, it will be a hash reference to put extra properties of the file into. Drivers may optimize not to fetch properties when the second argument is undefined (if such optimization is possible). Every driver should include at least the same keys as returned by "common_properties".

  Basic drivers should not check is_stored - it will never be called without checking is_stored first. Must return an open file handle to the file. The file handle should be rewound to the beginning (ready to be read without calling seek) and it should read data into memory lazily regardless of the underlying storage type. It is recommended that the file handle is a tied object of Storage::Abstract::Handle or its subclass. Calling retrieve_impl by itself should not cause the storage to perform any IO operations, so that it can be used just to fetch %properties efficiently.

• dispose_impl

  dispose_impl($path)

  The implementation of disposing a file. First argument is a normalized path.

  Basic drivers should not check is_stored - it will never be called without checking is_stored first. Its return value will be ignored.

• list_impl

  list_impl($path)

  The implementation of getting a list of files. Should return an array reference with file names (in Unix format).