view release on metacpan or  search on metacpan

lib/Class/AutoDB.pm  view on Meta::CPAN

  $autodb->put_objects;

  # retrieve existing objects
  #
  use Class::AutoDB;
  use Person;
  my $autodb=new Class::AutoDB(database=>'test');

  # retrieve list of objects
  my @persons=$autodb->get(collection=>'Person');        # everyone
  my @males=$autodb->get(collection=>'Person',sex=>'M'); # just the boys  

  # do something with the retrieved objects, for example, print friends lists
  for my $person (@persons) {
    my @friend_names=map {$_->name} @{$person->friends};
    print $person->name,"'s friends are @friend_names\n";
  }
 
  # retrieve and process objects one-by-one
  my $cursor=$autodb->find(collection=>'Person'); 
  while (my $person=$cursor->get_next) {
    # do what you want with $person, for example, print friends list
    my @friend_names=map {$_->name} @{$person->friends};
    print $person->name,"'s friends are @friend_names\n";
 }

  # connect auto-persistent objects with engineered tables
  # assume database has human-engineered tables
  #   Dept(id int, name varchar(255)), EmpDept(emp_id int, dept_id int)
  # this query retrieves the names of Joe's departments
  use DBI;
  my $dbh=$autodb->dbh;
  my $depts=$dbh->selectcol_arrayref
    (qq(SELECT Dept.name FROM Dept, EmpDept, Person 
        WHERE Dept.id=EmpDept.dept_id AND EmpDept.emp_id=Person.id 
        AND Person.name='Joe'));

  ########################################
  # new features in verion 1.20

  # retrieve objects using SQL
  # assuming the above database (with human-engineered tables Dept and EmpDept),
  # this query retrieves Person objects for employees in the toy department
  my @toy_persons=
  $autodb->get
    (sql=>qq(SELECT oid FROM Dept, EmpDept, Person 
             WHERE Dept.id=EmpDept.dept_id AND EmpDept.emp_id=Person.id 
             AND Dept.name='toy'));

  # retrieve all objects
  my @all_objects=$autodb->get;

  # delete objects
  #
  $autodb->del(@males);                                  # delete the boys  


=head1 DESCRIPTION

This class works closely with L<Class::AutoClass> to provide almost
transparent object persistence that can coexist with a
human-engineered database. The auto-persistence mechanism provides
hooks for connecting the two parts of the database together.

B<Caveat>: The current version only works with MySQL.

For applications where performance is not pressing, you can use this
class for all your persistent data.  In other cases, you can use it
for structurally complex, but low volume, parts of your database,
while storing performance-critical data in carefully engineered
tables.  This class is also handy for prototyping persistent
applications and lets you incrementally replace auto-persistent
components with engineered tables as your design proceeds.

=head2 Persistence model

This section presents a brief overview of the class.  Please see later
sections for details.

You declare a class to be persistent by defining the %AUTODB variable
in the module.  L<Class::AutoClass> (specifically,
Class::AutoClass::declare) uses %AUTODB to set everything up.

In simple cases, you set %AUTODB to 1, eg,

  %AUTODB=1;

This causes your class to be persistent, but provides no way to search
for objects and no convenient hook for connecting these objects to the
engineered parts of your database (unless a superclass provides these
capabilities).

More typically, you set %AUTODB to a hash of the form

  %AUTODB=(
    collection=>'Person', 
    keys=>qq(name string, sex string, id number));

This associates a persistent collection, called 'Person', with your
class and says that the Person collection has three search keys:
'name', 'sex', and 'id'.  Collections provide a way to search for
objects and are the hooks for connecting auto-persistent objects with
the rest of your database.

After setting up your classes to use Class::AutoDB, you use it as follows.

First you connect your program to the database by running
Class::AutoDB's 'new' method.  Then you typically invoke 'get' or
'find' to retrieve some number of "top level" objects.  Then, you
operate on objects as usual. If you touch an object that has not yet
been retrieved from the database, the system will automatically fetch
it for you.

The retrieval process reconstructs the original object network.  You
never get duplicate copies of a persistent object no matter how many
times you retrieve the object and no matter what path you use to reach
it.  In our running example, it doesn't matter whether you get all
Person objects first and then traverse their friends lists, or get
Person objects one-by-one and and traverse their friends lists as you
go.  The end result is the same: you end up with one copy of each
Person object, and the various friends lists point to these objects as