NAME

FusqlFS::Artifact::Table::Lazy - lazily created table artifact abstract class

SYNOPSIS

package FusqlFS::Backend::PgSQL::Table::Indices;
use parent 'FusqlFS::Artifact::Table::Lazy';

sub new
{
    my $class = shift;
    my $self = $class->SUPER::new(@_);

    $self->{template} = { '.order' => [] };

    # Initialize indices specific resources
    bless $self, $class;
}

sub get
{
    my $self = shift;
    unless ($self->SUPER::get(@_))
    {
        # get and return object from database
    }
}

sub list
{
    my $self = shift;
    my ($table) = @_;
    return [ @{$self->do($self->{list_expr}, [$table])}, @{$self->SUPER::list($table)} ];
}

sub store
{
    my $self = shift;
    my ($table, $name, $data) = @_;

    # validate input $data and build query, e.g.
    # my $struct = $self->validate($data, { ... }) or return;

    $self->drop($table, $name) and $self->do($self->{store_expr}, [$table, $name, $struct]);
}

sub drop
{
    my $self = shift;
    my ($table, $name) = @_;
    $self->SUPER::drop($table, $name) or $self->do($self->{drop_expr}, [$table, $name]);
}

sub rename
{
    my $self = shift;
    my ($table, $name, $newname) = @_;
    $self->SUPER::rename($table, $name, $newname) or $self->do($self->{rename_expr}, [$table, $name, $newname]);
}

DESCRIPTION

Some database artifacts can't be created without any initial data, like indices, so it is impossible to implement "create" in FusqlFS::Artifact to create "empty" artifact.

This class implements "lazy" table artifacts creation. When new database object is to be created, this class's create() creates empty placeholder in special inner cache by cloning template instance property you should initialize in new() (default is empty hashref, so new object will be visible as empty directory), so no actual database object is created at all. It should be created in overriden store method or this object will disappear after file system is unmounted, as there's no corresponding database artifact behind it.

Overriden store method should also either remove cache entry on successful object creation by calling $self->SUPER::drop or update this cache entry by calling $self->SUPER::store with already available data if these data are not enough to create actual database artifact.

All the other methods of this class should be consulted by overriden methods to make sure user will see underlying "creation" cache entry in case there's no actual database object by given name.

The rule of thumb is to drop this cache's entry with drop when database artifact is created, so every time this cache is checked, no entry for already created object should be found in it.

METHODS

new

Constructor.

Output: $lazy_artifact_instance.

You should usually override this constructor, to set $self->{template} to artifact placeholder template.

clone

Static method, clones given structure and returns this clone.

Input: $data. Output: $cloned_data.

This method implements deep recursive cloning of input data. It is used to clone template property to keep it intact and avoid it's erroneous modification.

create

Create cache entry using template instance property as a template for placeholder.

Input: $table, $name. Output: $success.

This methods uses "clone" method to clone $self->{template} and put this fresh placeholder value into creation cache, returns true on success or undef on failure.

drop

Drops given item from creation cache by name.

Input: $table, $name. Output: $success.

This method removes given object from inner creation cache and returns true on success or undef on failure (in case given cache entry doesn't exist).

You should use this method in your own store method in this class's subclass to drop creation cache item if it was correctly created in database.

rename

Renames given item in creation cache.

Input: $table, $name, $newname. Output: $success.

This method drops old creation cache entry by given name and stores it under new name. It returns true on success or undef on failure (in case given cache entry doesn't exist).

list

Returns arrayref with all objects contained in creation cache under given table name.

Input: $table, $name. Output: $arrayref.

This method accepts table name on input and returns keys from creation cache stored under this name packed into single arrayref. Returns empty arrayref if no objects in creation cache under given table name.

get

Returns cache entry by given name or undef it cache is missed.

Input: $table, $name. Output: $cache_entry.

This method checks creation cache and returns cache entry by given name. If cache entry by the name is absent, it returns undef.

store

Updates creation cache under given name with new data.

Input: $table, $name, $data. Output: $success.

This method stores new data in creation cache under given name and returns true on success or undef on failure (which should never happen).

You should use this method in your own store method in this class's subclass to update creation cache item if there were not enough data to create the object in database immediately.