NAME

KiokuDB::Backend - Backend interface role

SYNOPSIS

    package KiokuDB::Backend::Foo;
    use Moose;

    # load the core api and additional interfaces based on backend capabilities
    with qw(
        KiokuDB::Backend

        KiokuDB::Backend::Role::TXN
        KiokuDB::Backend::Role::Clear
        KiokuDB::Backend::Role::Scan
        KiokuDB::Backend::Role::UnicodeSafe
        KiokuDB::Backend::Role::BinarySafe
    );

    sub insert { ... }

    sub get { ... }

    sub delete { ... }

    sub exists { ... }



    # use the backend like this:

    my $dir = KiokuDB->new(
        backend => KiokuDB::Backend::Foo->new( );
    );

DESCRIPTION

KiokuDB is designed to be fairly backend agnostic.

This role defines the minimal API for writing new backends.

TRANSACTIONS

This role is supplemented by KiokuDB::Backend::Role::TXN, a role for first class transaction support that issues rollbacks using the KiokuDB::Entry objects.

QUERYING

This role is supplemented by KiokuDB::Backend::Role::Query, a role for backend specific queries.

KiokuDB::Backend::Role::Query::Simple provides a universal query api for backends that can perform property based lookup.

KiokuDB::Backend::Role::Query::GIN is a role for using Search::GIN based indexing/querying with backends that do not natively support querying.

REQUIRED METHODS

get @ids

Retrieve the KiokuDB::Entry objects associated with the @ids.

If any other error is encountered, this method should die.

The backend may store private data in backend_data, to be used in a subsequent update.

Returns a list of KiokuDB::Entry, with the order corresponding to @ids. If an entry does not exist then undef should be returned in place of it. The backend may abort retrieval on the first non existent entry.

insert @entries

Insert entries to the store.

If the backend is transactional this operation should be atomic with respect to the inserted/updated data.

The backend is required to store the data in the fields data, class using the key in id.

Entries which have an entry in prev denote updates (either objects that have been previously stored, or objects that were looked up). The previous entry may be used to compare state for issuing a partial update, and will contain the value of backend_data for any other state tracking.

object is a weak reference to the object this entry is representing, and may be used for high level indexing. Do not use this field for storage.

If this backend implements some form of garbage collection, root denotes that the objects is part of the root set.

After all entries have been successfully written, backend_data should be set if necessary just as in get.

Has no return value.

If insert does not die the write is assumed to be successful.

delete @ids_or_entries

Delete the specified IDs or entries.

If the user provided objects then entries will be passed in. Any associated state the entries may have (e.g. a revision) should be used in order to enforce atomicity with respect to the time when the objects were loaded.

After all entries have been successfully deleted, deleted should be set. The entry passed in is the same one as was loaded by get or last written by insert, so it is already up to date in the live objects.

Has no return value.

If delete does not die the write is assumed to be successful.

exists @ids

Check for existence of the specified IDs, without retrieving their data.

Returns a list of true or false values.

METHODS

These methods are provided by the KiokuDB::Backend role, and may be overridden.

new_from_dsn

Parses the second half of the DSN using parse_dsn_params and instantiates a new object using new_from_dsn.

See KiokuDB::Util.

new_from_dsn_params @args

Takes DSN parameters and converts them to arguments suitable for new

parse_dsn_params $str

The string is split on ; to produce arguments. Arguments in the form foo=bar are split on = into a key/value pair, and other arguments are treated as a boolean key and returned as $arg => 1.

ADDITIONAL INTERFACES

Your backend may include more roles, based on its capabilities.

KiokuDB::Backend::Serialize

KiokuDB::Backend::Serialize::Storable

KiokuDB::Backend::Serialize::JSPON

For the actual serialization of entries, there are a number of serialization roles.

KiokuDB::Backend::Role::BinarySafe

KiokuDB::Backend::Role::UnicodeSafe

If your serialization is able to store arbitrary binary data and/or unicode strings, these informational roles should be included.

KiokuDB::Backend::Role::TXN

If your storage supports nested transactions (txn_begin, txn_commit etc) this role provides the api to expose that functionality to the high level KiokuDB api.

KiokuDB::Backend::Role::Query

KiokuDB::Backend::Role::Query::GIN

If your backend supports querying of some sort, these are the roles to include.

The querying API uses backend specific lookups to fetch entries, which KiokuDB will then relink into result objects.

SHARED BACKENDS

A backend may be shared by several KiokuDB instances, each with its own distinct live object set. The backend may choose to share cached entry data, as that is not mutated by KiokuDB::Linker, but not the KiokuDB::Entry instances themselves.