• NAME
• INTRODUCTION
• ENTITY
• OBJECT TO RELATIONAL DATABASE MAPPING
  • The Programming Model

NAME

Persisistence::Entity::Introduction - Introduction to Persistence::Entity.

INTRODUCTION

We'll take a thorough look at the process of developing entities, perl classes and mapping between them to a relational database.

ENTITY

Entity represents logical unit of data in the database. It doesn't need to be just a simple mapping to a table, but it may represent comlex SQL epressions, with subqueries, joins, etc, this is especailly important to limit database calls for all those information to one call, rather then using separtes cursors with many fetch executions.

Examples of entities:

    my $dept_entity = Persistence::Entity->new(
        name    => 'dept',
        alias   => 'dt',
        primary_key => ['deptno'],
        columns => [
            sql_column(name => 'deptno'),
            sql_column(name => 'dname'),
        ]
    );

    my $emp_entity = Persistence::Entity->new(
        name    => 'emp',
        alias   => 'ur',
        primary_key => ['empno'],
        columns => [
            sql_column(name => 'empno'),
            sql_column(expression => 'SYSDATE - dob', alias => 'age'),
            sql_column(name => 'ename', unique => 1),
            sql_column(name => 'job'),
            sql_column(name => 'deptno'),
        ],
        subquery_columns => [
            $dept_entity->column('dname'),
        ]
    );

    $entity_manager->add_entities($dept_entity, $emp_entity);

OBJECT TO RELATIONAL DATABASE MAPPING

The purpose of an object relational mapping is to provide programmers with a simpler mechanism for accessing and changing data using plain perl classes, so when creating a new object or changing existing one it must be inserted into the database or synchronized accordingly. The process of coordinating the data represented by a object instance with the database is called persistence.

You have to delcare mapping between you class and entity, then you can use your classes like any other perl classes.

Class itself shouldn't be aware about database mapping and database operation underneath, thus you interact with the entity manager to persist, update, remove, locate, and query for objects. The entity manager is responsible for automatically managing the object' state. It takes care of managing the object in transactions and persisting its state to the database.

    $entity_manager->begin_work;
    eval {
        my $emp = Employee->new(id => 100, name => 'Scott');
        $entity_manager->insert($emp);

        #you can delcare mapping between many object to the same entity (for different inheritance strategy)
        #so this is find take entity_name, class_name as two first parameters.

        my @emp = $entity_manager->find(emp => 'Employee', deptnp => 10);
        for my $emp (@emp) {
            $emp->set_sallary($emp->salary + $emp->salary * 0.05)  ;
            $entity_manager->update($emp);
        }
        $entity_manager->commit;
    }
    $entity_manager->rollback if $@;

The Programming Model

Classes defined with Meta Object Protocol

This module currenly suppport Abstract::Meta::Class class generator, but it may be extended if needed.

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

    column empno => has('$.id') ;
    column ename => has('$.name') ;
    column job => has('$.job') ;

Plain perl classes

    use Persistence::ORM;

    Persistence::ORM->new(
        entity_name => 'emp',
        class       => 'Employee',
        columns     => {
            empno => {name => 'id'},
            ename => {name => 'name'},
            job   => {name => 'job'},
        }
    );


    package Employee;

    sub new {
        my $class = shift;
        bless {@_}, $class;
    }


    sub id {
        shift()->{id};
    }

    sub set_id {
        my ($self, $value) = @_;
        $self->{id} = $value;
        $self;
    }

    sub name {
        shift()->{name};
    }

    sub set_name {
        my ($self, $value) = @_;
        $self->{name} = $value;
        $self;
    }

    #or setter/getter in one approach

    sub job {
        my ($self, $value) = @_;
        $self->{job} = $value if (@_ > 1);
        $self->{job};
    }

XML Mapping File

If you do not want to interact directly with ORM or Entity meta protocal to declare map between your class and entity, or entity and database you can alternatively use an XML mapping file to declare this metadata.

Perl class

    package Employee;
    use Abstract::Meta::Class ':all';
    has '$.id';
    has '$.name';
    has '$.salary';
    has $.job';

XML injection of the persistence metadata.

    use Persistence::Meta::XML;
    my $meta = Persistence::Meta::XML->new(persistence_dir => 'meta/');
    $meta->inject('persistence.xml');

XML definitions:

    persistence.xml
    <?xml version="1.0" encoding="UTF-8"?>
    <persistence name="test"  connection_name="test" >
        <entities>
            <entity_file  file="emp.xml"  />
        </entities>
        <mapping_rules>
            <orm_file file="Employee.xml" />
        </mapping_rules>
    </persistence>

    emp.xml
    <?xml version="1.0" encoding="UTF-8"?>
    <entity name="emp" alias="e">
        <primary_key>empno</primary_key>
        <columns>
            <column name="empno" />
            <column name="ename" unique="1" />
            <column name="sal" />
            <column name="job" />
            <column name="deptno" />
        </columns>
    </entity>


    Employee.xml
    <?xml version="1.0" encoding="UTF-8"?>
    <orm entity="emp"  class="Employee" >
        <column name="empno"  attribute="id" />
        <column name="ename"  attribute="name" />
        <column name="job"    attribute="job" />
        <column name="sal"    attribute="salary" />
    </orm>