/ 
EntityModel-0.102
River stage one • 3 direct dependents • 7 total dependents
/ EntityModel::Storage

NAME

EntityModel::Storage - backend storage interface for EntityModel

VERSION

version 0.102

SYNOPSIS

See EntityModel.

DESCRIPTION

See EntityModel for more details.

METHODS

register

Register with EntityModel so that callbacks trigger when further definitions are loaded/processed.

The base storage engine doesn't provide any callbacks - but we define the method anyway so that we don't need to check for ->can.

apply_model

Apply the given model.

apply_model_and_schema

Apply the given model to the storage layer.

This delegates most of the work to "apply_entity".

read

Reads the data for the given entity and returns hashref with the appropriate data.

Parameters:

create

Creates new entry for the given EntityModel::Entity.

Parameters:

store

Stores data to the given entity and ID.

Parameters:

remove

Removes given ID from storage.

Parameters:

find

Find some entities that match the spec.

adjacent

Returns the previous and next element for the given ID.

prev

Returns previous element for the given ID.

next

Returns next element for the given ID.

outer

Returns first and last IDs for the given entity.

first

Returns first active ID for the given entity.

last

Returns last active ID for the given entity.

transaction_start

Mark the start of a transaction.

transaction_rollback

Roll back a transaction.

transaction_commit

Commit this transaction to storage - makes everything done within the transaction permanent (or at least to the level the storage class supports permanence).

transaction_end

Release the transaction on completion.

SUBCLASSING

This module provides the abstract base class for all storage modules. Here's how to build your own.

INITIAL SETUP

"setup" will be called when this storage class is attached to the model via "add_storage" in EntityModel, and this will receive the $model as the first parameter along with any additional options. Typically this will include storage-specific connection information.

Each entity added to the model will be applied to the storage engine through "apply_entity". It is the responsibility of the storage engine to verify that it is able to handle the given entities and fields, either creating the underlying storage structure (database tables, etc.) or raising an error if this isn't appropriate.

USAGE

Most of the work is handled by the following methods:

  • "read" - retrieves data from the backend storage engine for the given entity and ID

  • "create" - writes new data to storage for given entity, data and optional ID

  • "store" - updates an existing entry in storage for the given entity, data and ID

  • "remove" - deletes an existing entry from storage, takes entity and ID

Each of these applies to a single entity instance only. Since they operate on a callback basis, multiple operations can be aggregated if desired:

select * from storage where id in (x,y,z)

Two callbacks are required for each of the above operations:

  • on_complete - the operation completed successfully and the data is guaranteed to have been written to storage. The strength of this guarantee depends on the storage engine but it should be safe for calling code to assume that any further operations will not result in losing the data - for example, a database engine would commit the data before sending this event.

  • on_fail - the operation was not successful and storage has been rolled back to the previous state. This could be the case when trying to create an item with a pre-existing ID or possibly transaction deadlock, although in the latter case it would be preferable to attempt retry some reasonable number of times before signalling a failure.

Neither callback is mandatory - default behaviour if there is no on_fail is to die() on failure, and no-op if on_complete is not specified.

INHERITED METHODS

Mixin::Event::Dispatch

add_handler_for_event, clear_event_handlers, event_handlers, invoke_event, subscribe_to_event, unsubscribe_from_event

EntityModel::BaseClass

clone, dump, new, sap

AUTHOR

Tom Molesworth <cpan@entitymodel.com>

LICENSE

Copyright Tom Molesworth 2008-2011. Licensed under the same terms as Perl itself.