/ 
Elive-0.87.2
/ Elive::DAO
Security Advisories (1)
CPANSA-Elive-2011-01 (2011-10-15)

Elive::DAO->set() did not die on tainted data.

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

Return 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.
       );

Construct an entity from data. A copy is made of the data for use by the c<is_changed> and c<revert> methods.

is_changed

Returns a list of properties that have been changed since the entity was last retrieved or saved.

set

$obj->set(prop1 => val1, prop2 => val2 [,...])

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";

Inserts a new entity. The primary key should not be specified. 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 the contents of Elive::Entity in-memory cache.

update

Apply updates. 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'},
                command => $cmd,      # soap command to use
                params => \%params,   # additional soap params,
                changed => \@props,   # properties to update,
               );

list

    my $users = Elive::Entity::Users->list(
		    filter => 'surname = smith',  # filter results (server side)
		    command => $cmd,              # soap command to use
		    connection => $connection,    # connection to use
		    raw => 1,                     # return unblessed data
                );

Retrieve a list of objects from a table.

retrieve

my $user = Elive::Entity::User->retrieve(
                    $user_id,
                    reuse => 1,  # use cached data if present.
                    );

Retrieve a single entity objects by primary key.

delete

$user_obj->delete;

Delete an entity from the database.

revert

$user->revert                        # revert entire entity
$user->revert(qw/loginName email/);  # revert selected properties

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