NAME

DBIx::DBO2::Record - A row in a table in a datasource

SYNOPSIS

  package MyRecord;
  use DBIx::DBO2::Record '-isasubclass';
  MyRecord->table( DBIx::DBO2::Table->new( name=>'foo', datasource=>$ds ) );

  package main;
  my $results = MyRecord->fetch_all;
  foreach ( $results->records ) {
    
  }

DESCRIPTION

The DBIx::DBO2::Record class represents database records in tables accessible via DBIx::SQLEngine.

By subclassing this package, you can easily create a class whose instances represent each of the rows in a SQL database table.

REFERENCE

Subclass Factory

import

  package My::Record;
  use DBIx::DBO2::Record '-isasubclass';

Allows for a simple declaration of inheritance.

Table and SQLEngine

Each Record class stores a reference to the table its instances are stored in.

table

  RecordClass->table ( $table )
  RecordClass->table () : $table

Establishes the table a specific class of record will be stored in.

count_rows

  RecordClass->count_rows () : $integer

Delegated to table.

datasource

  RecordClass->datasource () : $datasource

Delegated to table. Returns the table's SQLEngine.

do_sql

  RecordClass->do_sql ( $sql_statement )

Delegated to datasource.

Constructor

Record objects are constructed when they are fetched from their table as described in the next section, or you may create your own for new instances.

new

  my $obj = MyRecord->new( method1 => value1, ... ); 

  my $shallow_copy = $record->new;

Create a new instance. (Class::MakeMethods::Standard::Hash:new).

clone

  my $similar_record = $record->clone;

Makes a copy of a record and then clears its id so that it will be recognized as a distinct, new row in the database rather than overwriting the original when you save it.

post_new

Inheritable Hook. Subclasses should override this with any functions they wish performed immediately after each record is created and initialized.

Selecting Records

fetch_records

  $recordset = My::Students->fetch_records( criteria => {status=>'active'} );

Fetch all matching records and return them in a RecordSet.

fetch_one

  $dave = My::Students->fetch_one( criteria => { name => 'Dave' } );

Fetch a single matching record.

fetch_id

  $prisoner = My::Students->fetch_id( 6 );

Fetch a single record based on its primary key.

refetch_record

  $record->refetch_record();

Re-retrieve the values for this record from the database based on its primary key.

post_fetch

Inheritable Hook. Subclasses should override this with any functions they wish performed immediately after each record is retrieved from the database.

Row Inserts

After constructing a record, you may save any changes by calling insert_record.

insert_record

  $record->insert_record ()

pre_insert

Inheritable Hook. Subclasses should override this with any functions they wish performed before a row is written out to the database.

post_insert

Inheritable Hook. Subclasses should override this with any functions they wish performed after a row is written out to the database.

Row Updates

After retrieving a record, you may save any changes by calling update_record.

update_record

  $record->update_record ()

pre_update

Inheritable Hook. Subclasses should override this with any functions they wish performed before a row is written out to the database.

post_update

Inheritable Hook. Subclasses should override this with any functions they wish performed after a row is written out to the database.

Deletion

delete_record

  $record->delete_record () : $boolean_completed

Checks to see if pre_delete returns a false value. If not, asks the table to delete the row.

pre_delete

  $record->pre_delete () : $boolean_is_ok

Subclasses may override this to provide validation or other behavior

post_delete

  $record->post_delete ()

Called after a record has been deleted from the datasource.

Load and Save Wrappers

Wrappers for new/fetch and insert/update.

get_record

  RecordClass->get_record ( $id_or_undef ) : $new_or_fetched_record_or_undef

Calls new if no ID is provided, or if the ID is the special string "-new"; otherwise calls fetch_id.

save_record

  $record->save_record () : $boolean_completed

Determines whether the record has an id assigned to it and then calls either insert_record or update_record.

Modification Wrappers

Simple interface for applying changes.

call_methods

  $record->call_methods( method1 => value1, ... );

Call provided method names with supplied values. (Class::MakeMethods::Standard::Universal:call_methods).

change_and_save

  RecordClass->new_and_save ( %method_argument_pairs ) : $record

Calls call_methods, and then save_record.