NAME
EntityModel::Support::Perl::Base - base class for entity instances
VERSION
version 0.102
SYNOPSIS
say $_->name foreach Entity::Thing->find({name=>'test'});DESCRIPTION
All entities are derived from this base class by default.
ASYNCHRONOUS HANDLING
When data has not yet been loaded for an entity, some additional logic is used to allow asynchronous requests via chained method accessors.
Given a chain $book->author->address->city, where the first three entries are regular entities and the last item in the chain is an accessor for a scalar method:
First, we check $book to see whether it has an author yet. If the author information is loaded (to the extent that ->author contains an entity instance), then we can use this existing instance. If not, we instantiate a new entity of this type, marked as incomplete and as a pending request, and continue.
This means that a chain where some of the elements can be null is still valid. As data is populated, entries in this chain will be filled out, and cases where the foreign key value was null will end up marked as invalid entities.
In general, unless you know beforehand that all entities in the chain have been populated, all access to chained entities should go through the EntityModel::Gather interface to ensure that values are consistent.
This also allows the backend storage to apply optimisations if available - if several pending requests address related storage areas, it may be possible for the storage engine to combine queries and return data faster.
EVENTS
Two types of events can be defined:
task - this is a one-shot event, typically used to call a piece of code after data has been written to or read from storage
event - this is an event handler that will be called every time an event occurs.
These are handled by the "_queue_task" and "_attach_event" methods respectively.
new
Instantiate from an ID or a pre-fabricated object (hashref).
Create a new, empty object:
EntityModel::Support::Perl::Base->new(1)Instantiate from ID:
EntityModel::Support::Perl::Base->new(1) EntityModel::Support::Perl::Base->new('123-456') EntityModel::Support::Perl::Base->new([123,456])Create an object and assign initial values:
EntityModel::Support::Perl::Base->new({ x => 1, y => 2 })
Any remaining options indicate callbacks:
before_commit - just before commit
after_commit - after this has been committed to the database
on_load - when the data has been read from storage
on_not_found - when storage reports that this item is not found
The before_XXX callbacks are also aliased to on_XXX for convenience.
_queue_task
Queues a new one-shot task for the given event type.
Supports the following event types:
on_load - data has been read from storage
on_create - initial data has been written to storage
on_update - values have been updated, but not necessarily written to storage
on_remove - this entry has been removed from storage
on_not_found - could not find this entry in backend storage
_event
Pass the given event through to any defined callbacks.
_spec_from_hashref
Private method to generate hashref containing spec information suitable for bless to requested class, given a hashref which represents the keys/values for the object.
This will flatten any Entity objects down to the required ID key+values.
create
Create a new object.
Takes a hashref, and sets the flag so that ->commit does the insert.
_update
Write current values back to storage.
_select
Populate this instance with values from the database.
_pending_insert
Returns true if this instance is due to be committed to the database.
_pending_update
Returns true if this instance is due to be committed to the database.
_insert
Insert this instance into the db.
commit
Commit any pending changes to the database.
revert
Revert any pending changes to the database.
id
Primary key (id) for this instance.
fromID
Instantiate from an ID.
remove
Remove this instance from the database.
_view
Returns the view corresponding to this object.
INHERITED METHODS
AUTHOR
Tom Molesworth <cpan@entitymodel.com>
LICENSE
Copyright Tom Molesworth 2008-2011. Licensed under the same terms as Perl itself.