Overview   Class-Group   Class   Use   Tree 
P5EEx-Blue-0.01
 PREV  NEXT FRAMES   NO FRAMES  

P5EEx::Blue::Repository::DBI

NAME

P5EEx::Blue::Repository::DBI - a repository which relies on a DBI interface to a relational database

SYNOPSIS

   use P5EEx::Blue::Repository::DBI;
   (see man page for P5EEx::Blue::Repository for additional methods)
   $rep = P5EEx::Blue::Repository::DBI->new();        # looks for %ENV, then config file
   $rep = P5EEx::Blue::Repository::DBI->new("mysql","mydb","user001","pass001");
   $rep = P5EEx::Blue::Repository::DBI->new("mysql","mydb","user001","pass001","port=3307");
   $rep = P5EEx::Blue::Repository::DBI->new("mysql","mydb","user001","pass001","port=3307","user001");
   ###################################################################
   # methods not defined in the P5EEx::Blue::Repository interface
   ###################################################################
   # UTILITY FUNCTIONS: to support the next level of functionality
   $select_sql = $rep->mk_select_rows_sql($table, \@cols,              \@params, \%paramvalues, \@ordercols);
   $insert_sql = $rep->mk_insert_row_sql ($table, \@cols, \@row);
   $update_sql = $rep->mk_update_row_sql ($table, \@cols, \@row, \@keycolidx);
   $update_sql = $rep->mk_update_rows_sql($table, \@cols, \@row, \@params, \%paramvalues);
   $delete_sql = $rep->mk_delete_row_sql ($table, \@cols, \@row, \@keycolidx);
   $delete_sql = $rep->mk_delete_rows_sql($table,                      \@params, \%paramvalues);
   ###################################################################
   # defined in the P5EEx::Blue::Repository interface, implemented here
   ###################################################################
   $ok = $rep->connect();         # initialize repository (will happen automatically in constructor)
   $ok = $rep->disconnect();      # cleanup repository (will happen automatically in destructor)
   $rep->is_connected();          # returns 1 if connected (ready for use), 0 if not
   $errmsg = $rep->error();       # returns the error string for prev op ("" if no error)
   $numrows = $rep->numrows();    # returns the number of rows affected by prev op
   print $rep->error(), "\n" if (!$rep->connect());
   print $rep->error(), "\n" if ($rep->connect() != $rep->OK);
   # META-DATA: (about the tables)
   $rep->load_rep_metadata_auto();
   $rep->load_table_metadata_auto($tablename);
   # MEDIUM-LEVEL: reads and writes rows, no caching
   $row       = $rep->select_row ($table, \@cols,              \@params, \%paramvalues);
   $rows      = $rep->select_rows($table, \@cols,              \@params, \%paramvalues, \@ordercols, $startrow, $endrow);
   $ok        = $rep->insert_row ($table, \@cols, \@row);
   $ok        = $rep->insert_rows($table, \@cols, \@rows);
   $ok        = $rep->update_row ($table, \@cols, \@row, \@keycolidx);
   $ok        = $rep->update_rows($table, \@cols, \@row, \@params, \%paramvalues);
   $ok        = $rep->store_row  ($table, \@cols, \@row, \@keycolidx, $update_first);
   $ok        = $rep->store_rows ($table, \@cols, \@rows,      \@keycolidx, $update_first);
   $ok        = $rep->delete_row ($table, \@cols, \@row, \@keycolidx);
   $ok        = $rep->delete_rows($table,                      \@params, \%paramvalues);

DESCRIPTION

The P5EEx::Blue::Repository::DBI class encapsulates all access to the database, changing SQL statements into get(), save(), and delete() methods.

store_row()

    * Signature: $ok = $rep->store_row ($table, $cols, $row);
    * Signature: $ok = $rep->store_row ($table, $cols, $row, $keycolidx);
    * Signature: $ok = $rep->store_row ($table, $cols, $row, $keycolidx, $update_first);
    * Param:     $table             string
    * Param:     $cols              []
    * Param:     $row               []
    * Param:     $keycolidx         []
    * Param:     $update_first      boolean
    * Return:    $ok                boolean
    * Throws:    P5EEx::Blue::Exception::Repository
    * Since:     0.01
    Sample Usage:
    $rep->store_row ($table, \@cols, \@rows, \@keycolidx);

The store_row() method ensures that the row of data is stored regardless whether the row exists currently in the table or not. (The $update_first flag may be set as a performance hint that under most conditions, the application would expect a row to be present.)

The method returns the number of rows properly stored (i.e. 0 or 1).

If you have many rows to store, it is probably more efficient to use the store_rows() method so that various implementation-specific issues like locking may only be performed once.

store_rows()

    * Signature: $nrows = $rep->store_rows ($table, $cols, $rows, $keycolidx);
    * Signature: $nrows = $rep->store_rows ($table, $cols, $rows, $keycolidx, $update_first);
    * Signature: $nrows = $rep->store_rows ($table, $cols, $rows, $keycolidx, $update_first, $row_crit);
    * Param:     $table             string
    * Param:     $cols              []
    * Param:     $rows              [][]
    * Param:     $keycolidx         []
    * Param:     $update_first      boolean
    * Param:     $row_crit          {}
    * Return:    $nrows             integer
    * Throws:    P5EEx::Blue::Exception::Repository
    * Since:     0.01
    Sample Usage:
    $rep->store_rows ($table, \@cols, \@rows, \@keycolidx, $update_first);

The store_rows() method ensures that all rows of data are stored regardless whether the row exists currently in the table or not. (The $update_first flag may be set as a performance hint that under most conditions, the application would expect a row to be present.)

If any row fails to be stored, the method will exit immediately, returning the number of rows that were successfully stored.