NAME

Persistence::Entity::Manager - Persistence entity manager.

SYNOPSIS

use Persistence::Entity::Manager; use SQL::Entity; use SQL::Entity::Column ':all'; use SQL::Entity::Condition ':all';

my $entity_manager = Persistence::Entity::Manager->new(
    name            => 'my_manager'
    connection_name => 'my_connection'
);

$entity_manager->add_entities(SQL::Entity->new(
    name                  => 'emp',
    primary_key          => ['empno'],
    columns               => [
        sql_column(name => 'ename'),
        sql_column(name => 'empno'),
        sql_column(name => 'deptno')
    ],
    triggers => {
    on_fetch => sub { ... },
    before_insert => sub { ... ]
));

{
    package Employee;
    use Abstract::Meta::Class ':all';
    use Persistence::ORM ':all';

    entity 'emp';
    column empno => has('$.no') ;
    column ename => has('$.name');
}

{
    my ($emp) = $entity_manager->find(emp => 'Employee', name => 'foo');
    #object attribute name as part of the condition

    my (@emp) = $entity_manager->find(emp => 'Employee', sql_cond('ename', 'LIKE' 'a%');
}

{
    $entity_manager->begin_work;
    eval {
        my $emp = Employee->new(name => 'foo');
        $entity_manager->insert($user);


        $emp->set_deptno(10);
        $entity_manager->update($emp);

        $entity_manager->delete($emp)

        my ($emp) = $entity_manager->find(emp => 'Employee', name => 'foo');

        $entity_manager->commit;
     };

     $entity_manager->rollback if($@);
}

DESCRIPTION

Represets entity manager.

EXPORT

None.

ATTRIBUTES

name

active_transaction

Flag that stores information if manager is in active transaction.

entities

entities

connection_name

_connection

persitence_mangement

If this option is set, then state of the all fetched, merged or created object by entity manager will be tracked (it's database state is stored in local cache), unless they become detached by calling $entity_manager->detach($obj) or $entity_manager->detach_all or for persitence_mangement = transaction

$entity_manager->commit;
$entity_manager->rollback;

Note: Using this option you must ensure that there are not obsolete objects in the local cache by detching all objects that are no longer in use, it may be resource consuming (memory).

If the persitence_mangement option is not set then extra sql will be issued to get object state from database for update, delete.

_persistence_cache

Stores datebase state of the object. The key is the object reference, the values database row.

_lazy_fetch_flag

Hash that stores information about lazy retrieve for objects attribute

METHODS

initialise

manager

Return entity manger object, takes entity manager name as parameter.

Persistence::Entity::Manager->new(name => 'manager_name', connection_name => 'connection_nane');
#
my $entity_manager = Persistence::Entity::Manager->manager('manager_name');

find

Returns list of objects or resultsets. Takes entity name, class name to which resultset will be casted, (if class name is undef then hash ref will be return instead), list of names parameters that will be used as condition or condition object. For non empty class name resulset state is cached - persitence_mangement option.

Note: If class name has the ORM mapping, then name parameters must be objects' attributs . Condition object always should use entity column.

my ($emp) = $entity_manager->find(emp => 'Employee', name => 'adrian');
or

my @emp = $entity_manager->find(emp => 'Employee', sql_cond('ename', 'LIKE', 'a%'));
#array of Employee objects.

or 
my @emp = $entity_manager->find(emp => undef, sql_cond('ename', 'LIKE', 'a%'));
#array of resultset (hash ref)

lock

Returns and locks list and of objects or resultsets. Takes entity name, class name to which resultset will be casted, (if class name is undef then hash ref will be return instead), list of names parameters that will be used as condition or condition object. For non empty class name resulset state is cached - persitence_mangement option.

Note: If class name has the ORM mapping, then name parameters must be objects' attributs . Condition object always should use entity column.

my ($emp) = $entity_manager->find(emp => 'Employee', name => 'adrian');
or

my @emp = $entity_manager->find(emp => 'Employee', sql_cond('ename', 'LIKE', 'a%'));
#array of Employee objects.

or 
my @emp = $entity_manager->find(emp => undef, sql_cond('ename', 'LIKE', 'a%'));
#array of resultset (hash ref)

condition_converter

Converts list of parameters to condition object. Takes class name, list of condition parameters. Note: If class name has the ORM mapping, then name parameters must be objects' attributs . Condition object always should use entity column.

my $sql_condition = $entity_manager->condition_converter('Employee', name => 'adrian');
#creates ename = 'adrian'  sql condition (given that there is mapping between ename column to name attribute).

See also SQL::Entity::Condition

query

Returns new query object. Takes entity name, optionally class name to which resultset will be casted, (if class name is undef then hash ref will be return instead), For non empty class name resulset state is cached - persitence_mangement option.

my $query = $entity_manager->query(emp => undef);
$query->set_offset(20);
$query->set_limit(5);
my @emp = $query->execute(['empno', 'ename']);

$query->set_offset(120);
$query->set_limit(5);
my @emp = $query->execute(undef, deptnp => 10);

See also Persistence::Entity::Query

refersh

Refresh object's state. Takes object as parameter.

my $emp = Emp->new(id => 10);
$entity_manager->refresh($emp);

Refresh operation caches object - persitence_mangement option.

insert

Inserts object that is mapped to the entity, takes the object as parameter

my $emp = Emp->new(id => 10, name => 'scott');
$entity_manager->insert($emp);

update

Updates object that is mapped to the entity, takes the object as parameter

my $emp = Emp->new(id => 10, name => 'scott');
$entity_manager->update($emp);

merge

Merges object that is mapped to the entity, takes the object as parameter Is robject exists in database the updates, otherwise inserts.

my $emp = Emp->new(id => 10, name => 'scott');
$entity_manager->merge($emp);

delete

Delets object that is mapped to the entity, takes object as parameter

my $emp = Emp->new(id => 10, name => 'scott');
$entity_manager->delete($emp);

begin_work

Begins a new transaction.

$entity_manager->begin_work;
 eval {
     my $emp = Employee->new(name => 'foo');
     $entity_manager->insert($user);
     $entity_manager->commit;
 }
 $entity_manager->rollback if $@;

commit

Commits current transaction.

$entity_manager->commit;

rollback

Rollbacks current transaction.

$entity_manager->reollback;

detach

Removes database object state from cache.

....$entity_manager->search() $entity_manager->detach

detach_all

Clears entity cache.

connection

Returns connection object.

PRIVATE METHODS

initialise_operation

has_pending_operation

complete_operation

find_entity_mappings

Returns entity mapping object Takes object or class name, and optionally must_exists_validation flag that will raise an error if mapping object does not exist.

_update_generated_values

Updates object by generated values.

_to_many_insert_relationship

_insert_to_one_relationship

_update_pk_values

_update_to_many_relationship

_update_to_one_relationship

_delete_to_many_relationship

_delete_to_one_relationship

_deserialise_object

Casts result set to passed in class name, optionally uses Object-relational mapping.

changed_column_values

Returns hash ref of fields_values that have been changed.

_manage_object

Creates database state of the object in the persistence cache. Takes object, resultset as parameters.

add_lazy_fetch_flag

Adds lazy flag. Takes object and attirubte for lazy retrieval.

has_lazy_fetch_flag

Returns true if passed in object has lazy flag for passed in attribute.

_reset_lazy_relation_attributes

SEE ALSO

Abstract::Meta::Class Persistence::ORM SQL::Entity SQL::Entity::Condition

COPYRIGHT

The SQL::EntityManager module is free software. You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

AUTHOR

Adrian Witas, adrian@webapp.strefa.pl

See also Abstract::Meta::Class.