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::Delegate
- For the actual serialization of entries, there are a number
of serialization roles.
- KiokuDB::Backend::Role::Clear
- API for clearing all entries.
- KiokuDB::Backend::Role::Scan
- API for enumerating entries.
- 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.