/ 
Elive-0.89
River stage one • 1 direct dependent • 1 total dependent
/ Elive::DAO

NAME

Elive::DAO - Abstract class for Elive Data Access Objects

DESCRIPTION

This is an abstract class for retrieving and managing objects mapped to a datastore.

METHODS

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->url

Abstract 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 set 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 properties

Abstract 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

Elive::Struct
Mouse