NAME
Elive::DAO - Abstract class for Elive Data Access ObjectsDESCRIPTION
This is an abstract class for retrieving and managing objects mapped to a datastore.
METHODS
entity_name
my $entity_name = MyApp::Entity::User->entity_name
ok($entity_name eq 'user');collection_name
my $collection_name = MyApp::Entity::User->collecion_name
ok($collection_name eq 'users');id
my @primary_vals = $entity_obj->idReturn primary key values.
primary_key
Setter/getter for primary key field(s) for this entity class
my @pkey = MyApp::Entity::User->primary_keyparams
Setter/getter for parameter field(s) for this entity class
Elive::Entity::User->params(loginName => 'Str');
my %params = MyApp::Entity::User->params;derivable
Setter/getter for derivable field(s) for this entity class
entities
my $entities = Entity::Entity->entities
print "user has entity class: $entities->{user}\n";
print "meetingParticipant entity class has not been loaded\n"
unless ($entities->{meetingParticipant});Return has hash ref of all loaded entity names and classes
properties
my @properties = MyApp::Entity::User->properties;Return the property accessor names for an entity
property_types
my $user_types = MyApp::Entity::User->property_types;
my $type_info = Elive::Util::inspect_type($user_types->{role})Return a hashref of attribute data types.
property_doco
my $user_doc = MyApp::Entity::User->property_doc
my $user_password_doco = $user_doc->{loginPassword}Return a hashref of documentation for properties
stringify
Return a human readable string representation of an object. For database entities, this is the primary key:
if ($user_obj->stringify eq "11223344") {
....
}Arrays of sub-items evaluated, in a string context, to a semi-colon separated string of the individual values sorted.
my $group = Elive::Entity::Group->retrieve([98765]);
if ($group->members->stringify eq "11223344;2222222") {
....
}In particular meeting participants stringify to userId=role, eg
my $participant_list = Elive::Entity::ParticipantList->retrieve([98765]);
if ($participant_list->participants->stringify eq "11223344=3;2222222=2") {
....
}connection
my $default_connection = Elive::Entity::User->connection;
my $connection = $entity_obj->connection;Return a connection. Either the actual connection associated with a entity instance, or the default connection that will be used.
url
my $url = $user->urlAbstract method to compute a restful url for an object instance. This will include both the url of the connection string and the entity class name. It is used internally to uniquely identify and cache objects across repositories.
construct
my $user = Entity::User->construct(
{userId = 123456,
loginName => 'demo_user',
role => {
roleId => 1
}
},
overwrite => 1, # overwrite any unsaved changes in cache
connection => $conn, # connection to use
copy => 1, # return a simple blessed uncached object.
);Abstract method to construct an entity from data. A copy is made of the data for use by the is_changed and revert methods.
is_changed
Abstract method. Returns a list of properties that have been changed since the entity was last retrieved or saved.
set
$obj->set(prop1 => val1, prop2 => val2 [,...])Abstract method to assign values to entity properties.
insert
my $new_user = Elive::Entity::User->insert(
{loginName => 'demo_user',
email => 'demo.user@test.org'}
},
connection => $con, # connection to use,
command => $cmd, # soap command to use
param => \%params, # additional soap params,
);
print "inserted user with id: ".$new_user->userId."\n";Abstract method to insert new entities. The primary key is generally not provided. It is generated for you and returned with the newly created object.
live_entity
my $user_ref
= Elive::Entity->live_entity('http://test.org/User/1234567890');Returns a reference to an object in the Elive::Entity in-memory cache.
live_entities
my $live_entities = Elive::Entity->live_entities;
my $user_ref = $live_entities->{'http://test.org/User/1234567890'};Returns a reference to the Elive::Entity in-memory cache.
update
Abstract method to update entities. The following commits outstanding changes to the object.
$obj->{foo} = 'Foo'; # change foo attribute directly
$foo->update; # save
$obj->bar('Bar'); # change bar via its accessor
$obj->update; # save
Updates may also be passed as parameters:
# change and save foo and bar. All in one go.
$obj->update({foo => 'Foo', bar => 'Bar'});list
my $users = Elive::Entity::User->list(
filter => 'surname = smith', # filter results (server side)
command => $cmd, # soap command to use
connection => $connection, # connection to use
raw => 1, # return unblessed data
);Abstract method to list entity objects.
retrieve
my $user = Elive::Entity::User->retrieve(
$user_id,
reuse => 1, # use cached data if present.
);Abstract method to retrieve a single entity object by primary key.
delete
$user_obj->delete;Abstract method to delete an entity.
revert
$user->revert # revert entire entity
$user->revert(qw/loginName email/); # revert selected propertiesAbstract method to revert an entity to its last constructed value.
ADVANCED
Object Reuse
An in-memory object cache is used to maintain a single unique copy of each object for each entity instance. All references to an entity instance are unified. Hence, if you re-retrieve or re-construct the object, any other references to the object will see the updates.
my $user = Elive::Entity::User->retrieve([11223344]);
#
# returns the same reference, but refetches from the database
#
my $user_copy = Elive::Entity::User->retrieve([11223344]);
#
# same as above, however don't refetch if we already have a copy
#
my $user_copy2 = Elive::Entity::User->retrieve([11223344], reuse => 1);You can access the in-memory cache using the live_entity and live_entities methods.
Entity Manipulation
Through the magic of inside-out objects, all objects are simply blessed structures that contain data and nothing else. You may choose to use the accessors, or work directly with the object data.
The following are all equivalent, and are all ok:
my $p_list = Elive::Entity::ParticipantList->retrieve([98765]);
my $user = Elive::Entity::User->retrieve([11223344]);
$p_list->participants->add($user);
push (@{ $p_list->participants }, $user);
push (@{ $p_list->{participants} }, $user);
push (@{ $p_list->get('participants') }, $user);SEE ALSO
Mouse