/ 
Persistence-Entity-0.07
River stage zero No dependents
/ Persistence::Entity

NAME

Persistence::Entity - Persistence API for perl classes.

CLASS HIERARCHY

SQL::Entity::Table
   |
   +----SQL::Entity
           |
           +----Persistence::Entity

SYNOPSIS

 use Persistence::Entity ':all';

 my $membership_entity = Persistence::Entity->new(
     name    => 'wsus_user_service',
     alias   => 'us',
     primary_key => ['user_id', 'service_id'],
     columns => [
         sql_column(name => 'user_id'),
         sql_column(name => 'service_id'),
         sql_column(name => 'agreement_flag')
     ],
 );

 my $user_entity = Persistence::Entity->new(
     name    => 'wsus_user',
     alias   => 'ur',
     primary_key => ['id'],
     columns => [
         sql_column(name => 'id'),
         sql_column(name => 'username'),
         sql_column(name => 'password'),
         sql_column(name => 'email'),
     ],
     to_many_relationships => [sql_relationship(target_entity => $membership_entity, join_columns => ['user_id'])]
 );

$entity_manager->add_entities($membership_entity, $user_entity);

LOB's support

my $photo_entity = Persistence::Entity->new(
    name    => 'photo',
    alias   => 'ph',
    primary_key => ['id'],
    columns => [
        sql_column(name => 'id'),
        sql_column(name => 'name', unique => 1),
    ],
    lobs => [
        sql_lob(name => 'blob_content', size_column => 'doc_size'),
    ]
);

DESCRIPTION

This class represents database entity.

EXPORT

sql_relationship
sql_column
sql_lob
sql_index
sql_cond
sql_and
sql_or by ':all' tag

ATTRIBUTES

trigger

Defines tigger that will execute on one of the following event before_insert after_insert before_update after_update before_delete after_delete, on_fetch Takes event name as first parameter, and callback as secound parameter.

$entity->trigger(before_insert => sub {
    my ($self) = @_;
    #do stuff
});
entity_manager
value_generators

Hash that contains pair of column and its value generator.

filter_condition_values

Hash ref that contains filter values, that values will be used as condition values

dml_filter_values

Hash ref that contains columns values that will be added to all dml operations.

METHODS

find

Returns list of objects or resultsets. Takes 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. Condition object always should use entity column.

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

Returns list of objects or resultsets. Takes array ref of requested column to projection, 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. Condition object always should use entity column.

my $entity = $entity_manager->entity('emp');
my ($emp) = $entity->find('Employee', ename => 'adrian');
or
my @emp = $entity->find('Employee', sql_cond('ename', 'LIKE', 'a%'));
#array of Employee objects.
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. Condition object always should use entity column. Locking is forced by SELECT ... FOR UPDATE clause

my $entity = $entity_manager->entity('emp');
my ($emp) = $entity->lock('Employee', ename => 'adrian');
or
my @emp = $entity->lock('Employee', sql_cond('ename', 'LIKE', 'a%'));
#array of Employee objects.
or 
my @emp = $entity->lock(undef, sql_cond('ename', 'LIKE', 'a%'));
#array of resultset (hash ref)
relationship_query

Return rows for relationship. Takes relationship_name, class_name, target_class_name, condition arguments as parameters.

 $user_entity->add_to_many_relationships(sql_relationship(target_entity => $membership_entity, join_columns => ['user_id']));
my $entity_manager = Persistence::Entity::Manager->new(connection_name => 'my_connection');
$entity_manager->add_entities($membership_entity, $user_entity);
my @membership = $user_entity->relationship_query('wsus_user_service', undef => undef, username => 'test');
# returns array of hash refs.
or 
my @membership = $user_entity->relationship_query('wsus_user_service', 'User' => 'ServiceMembership', username => 'test');
# returns array of ServiceMembership objects
insert

Inserts the entity row Takes list of field values.

$entity->insert(col1 => 'val1', col2 => 'val2');
relationship_insert

Inserts the relation rows. Takes relation name, dataset that represents the entity row, array ref where item can be either object or hash ref that represents row to be asssociated .

$user_entity->relationship_insert('wsus_user_service', {username => 'test'} , {service_id => 1}, {service_id => 9});
#or
my $user = User->new(...);
my $membership1 = Membership->new(...);
my $membership2 = Membership->new(...);
$user_entity->relationship_insert('wsus_user_service', $user, $membership1, $membership2);
update

Updates the entity row. Takes field values as hash ref, condition values as hash reference.

 $entity->update({col1 => 'val1', col2 => 'val2'}, {the_rowid => 'xx'});

 my $lob = _load_file('t/bin/data1.bin');
$photo_entity->insert(id => "1", name => "photo1", blob_content => $lob);
merge

Merges the entity row. Takes field values to merge as named parameteres,

$entity->merge(col1 => 'val1', col2 => 'val2', the_rowid => '0xAAFF');
relationship_merge

Merges the relation rows. Takes relation name, dataset that represents the entity row, list of either object or hash ref that represent asssociated row to merge.

$user_entity->relationship_merge('wsus_user_service',
    {username => 'test'} ,
    {service_id => 1, agreement_flag => 1}, {service_id => 5, agreement_flag => 1}
);
delete

Delete entity row. Takes list of condition values.

$entity->delete(the_rowid => 'xx');
relationship_delete

Deletes associated rows. Takes relation name, dataset that represents the entity row, list of either associated object or hash ref that represent asssociated row.

$user_entity->relationship_insert('wsus_user_service', {username => 'test'} , {service_id => 1}, {service_id => 9});
$user_entity->relationship_insert('wsus_user_service', $user, $membership1, $membership1);
primary_key_values

Returns primary key values. Takes field values that will be used as condition to retrive primary key values in case they are not contain primary key values.

has_primary_key_values

Returns true if passed in dataset contains primary key values.

fetch_lob

Fetchs LOBs value. Takes lob column name, condition values.

my $blob = $photo_entity->fetch_lob('blob_content', {id => 10});

PRIVATE METHODS

is_refresh_required

Returns true if refreshis required

run_event

Executes passed in even. Takes event name, event parameters.

validate_trigger

Validates triggers types. The following trigger types are supported: before_insert, after_insert, before_update, after_update, before_delete, after_delete, on_fetch.

_update_lobs

Updates LOB value.

$entity->_update_lobs({name => "photo1", blob_content => $bin_data}, {id => 1,});
_extract_lob_values
_autogenerated_values

Adds autogenerated values. Takes hash ref to field values

_to_many_relationship_insert

Insert data to many relationship. Takes relationship name, hashref of the fileds values for the entity, list of hash ref that contians fileds values of the entities to associate.

_to_one_relationship_merge

Merges data to one relationship. Takes relationship name, hashref of the fileds values for the entity, list of hash ref that contians values fileds of the entities to associate.

_merge_datasets

Mergers tow passed in dataset. Takes source hash_ref, target hash_ref.

_join_columns_values

Returns join columns values for passed in relation

_to_many_relationship_merge

Marges to many relationship rows (insert/update). Takes relationship name, hashref of the fileds values for the entity, list of hash ref that contians values fileds of the entities to merge.

_to_many_relationship_delete

Deletes to many relationship association. Takes relationship name, hashref of the fileds values for the entity, list of hash ref that contians values fileds of the entities to delete.

_to_one_relationship_delete

Deletes to one relationship association. Takes relationship name, hashref of the fileds values for the entity, list of hash ref that contians values fileds of the entities to delete.

retrive_primary_key_values

Retrieves primary key values. Takes hash ref of the entity field values.

_execute_statement

Executes passed in sql statements with all callback defined by decorators (triggers) Takes sql, array ref of the bind varaibles,r event name, event parameters.

_execute_query

Executes query. Takes sql, array ref of the bind varaibles, optionally class name.

SEE ALSO

SQL::Entity

COPYRIGHT AND LICENSE

The Persistence::Entity 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