NAME

Class::Entity - Object interface for relational databases

DESCRIPTION

Class::Entity allows a developer to create an object interface for a relational database by writing a minimal amount of code in a set of sub-classes which correspond to database tables.

Right now this module only implements a read only interface. Writes will probably come later.

SYNOPSIS

package Table;
use base qw(Class::Entity);

package main;
use DBI;
my $dbh = DBI->connect(...);
my $table = Table->fetch(dbh => $dbh, key => 1234);
print $table->Column;

for (Table->find(dbh => $dbh, where => "Name like 'foo%'")) {
  printf "% %\n", $table->Name, $table->Date;
}

METHODS

new(dbh => $dbh, data => $data)

The constructor creates a new instance of the current class. If you pass in values via data they will be stored in the object for later use.

_primary_key()

Return the primary key for the table the current sub-class of Class::Entity represents. You will normally want to overide this in the sub-class but for convenience it returns id by default.

The value of this method is used to create the query that is run when a call to fetch is made.

_table()

Return the name of the table the current sub-class of Class::Entity represents. You will normally want to overide this in the sub-class but for convenience it returns the final part of the sub-class name; that is: the sub-class name minus the leading /.*:/.

_relation()

This method provides the sub-class author a means of joing accross multiple tables when a call to fetch or find is made. All database fields returned via these methods are stored in an instance of the current sub-class and exposed via the autoloader. By default it returns all fields in the current table represented by the sub-class.

_object_map()

The object map works in conjuction with the autoloader. If you have sub-classes of Class::Entity, which represent tables linked to in the current sub-class, you can overload this method to return a hash where the keys are the table columns and the values are the names of the associated Class::Entity sub-classes.

The object map will only be used for method calls of the form get_Value.

Here's an example:

package Users;
use base qw(Class::Entity);

package Departments;
use base qw(Class::Entity);
sub _object_map({
  UserID => "Users"
})

package main;
use DBI;
my $dbh DBI->connect(...);
my @support = Departments->find(dbh => $dbh, where => "Name = 'Support'");
for (@support) {
  printf "%s %s\n", $_->UserID, $_->get_UserID->name;
}

fetch(dbh => $dbh, key => $key)

Return an instance of the current sub-class. You must provide a database value via dbh and a primary key value via key. The database handle is stored in the returned object for later use and all table fields are exposed via the auoloader.

find(dbh => $dbh, where => $where)

Return an array in array context, or the first item of the array in scalar context, of instances of the current sub-class based on the query modifier passed in via where. You must pass in a database handle via dbh which will be stored in the returned instances for later use.

AUTOLOAD([$value])

The autoloader provides get and set methods for the table values represented in an instance of the current sub-class. For example, if you have a table with the fields: Name, Date, Subject, you would access them like this:

package Table;
use base qw(Class::Entity);

package main;
use DBI;
my $dbh = DBI->connect(...);
my $table = Table->fetch(dbh => $dbh, key => 10);
print $table->Name . "\n";
print $table->Date . "\n";
print $table->Subject . "\n";

If you call an anonymous method of the form get_Value, where Value is a column represented by the current object, the autoloader will attempt to dispatch the call to the fetch method of the corresponding sub-class of Class::Entity, if it's listed in the _bject_map.

SEE ALSO

DBI

AUTHORS

Paddy Newman, <pnewman@cpan.com>

ACKNOWLEDGEMENTS

This is basically a cut-down, slightly modified version of something an ex-colegue of mine wrote and introduced me to. His name is Dan Barlow and he's a much better programmer than me and he deserves all the credit.