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';
with 'Storage::Abstract::Role::Metadriver';

# these methods need implementing
sub store_impl { ... }
sub is_stored_impl { ... }
sub retrieve_impl { ... }
sub dispose_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 or Storage::Abstract::Role::Metadriver.

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 metadrivers. This type of drivers don't store its own readonly status, but instead reports the status of its source via readonly. Calling set_readonly on metadrivers will call set_readonly of the underlying driver. If the metadriver 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).

open_handle

$fh = $obj->open_handle(\$content);
$fh = $obj->open_handle($filename);

This tries to create a readonly, binary handle from its argument. It will not do anything if the argument is a class of IO::Handle.

copy_handle

$obj->copy_handle($fh_from, $fh_to)

This copies the data from $fh_from to $fh_to. Based on the fileno result on the handles, it uses either sysread + syswrite or read + print. Use this to move data between filehandles in driver classes.

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 opened file 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".

  It should not check is_stored - it will never be called without checking is_stored first. Must return an opened file handle to the file.

• dispose_impl

  dispose_impl($path)

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

  It 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).