NAME

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

SYNOPSIS

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

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

# 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.

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.

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;

This returns a hash reference containing a list of properties with default values. Currently, the only property avialible in all the drivers is mtime - modification time.

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.