/ 
DBIx-SQLEngine-0.021
River stage one • 1 direct dependent • 1 total dependent
/ DBIx::SQLEngine::Record::Base

NAME

DBIx::SQLEngine::Record::Base - Class for rows in a table

SYNOPSIS

$sqldb = DBIx::SQLEngine->new( ... );

$class_name = $sqldb->record_class( $table_name );

$record_set = $class_name->fetch_select( criteria => { status => 2 } );

$record = $class_name->fetch_record( $primary_key );
$record->change( somefield => 'New Value' );
$record->update_record();

$record = $class_name->new_with_values(somefield => 'New Value');
$record->insert_record();

$record->delete_record();

DESCRIPTION

This package is not yet complete.

DBIx::SQLEngine::Record::Base is a superclass for 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.

CLASS INSTANTIATION

Record Class Creation

SQLEngine->record_class()
$sqldb->record_class( $tablename ) : $class_name
$sqldb->record_class( $tablename, $name ) : $class_name

Convenience function to create a record class with the given table name.

Table->record_class()
$table->record_class( ) : $class_name
$table->record_class( $name ) : $class_name

Convenience function to create a record class for a given table.

new_subclass()
DBIx::SQLEngine::Record::Base->new_subclass( table=>$table ) : $class_name
DBIx::SQLEngine::Record::Base->new_subclass( table=>$table, name=>$name ) : $class_name

Subclass constructor. You are expected to provde a DBIx::SQLEngine::Schema::Table object.

If you do not supply a class name, one is generated based on the table name.

If the class name does not contain a "::" package separator, it is prepended with DBIx::SQLEngine::Record::.

Table Accessor

table()
$class_name->table() : $table
$class_name->table($table)

Get and set our current DBIx::SQLEngine::Schema::Table. Required value. Establishes the table a specific class of record will be stored in. The table provides the DBI connection and SQL execution capabilities required to talk to the remote data storage.

get_table()
$table->get_table() : $table or exception

Returns the table, or throws an exception if it is not set.

Table Methods

detect_sqlengine()
$class_name->detect_sqlengine : $flag

Detects whether the SQL database is avaialable by attempting to connect.

table_exists()
$class_name->table_exists : $flag

Detects whether the table has been created and has not been dropped.

columnset()
$class_name->columnset () : $columnset

Returns the current columnset, if any.

fetch_one_value()
$table->fetch_one_value( %sql_clauses ) : $scalar

Calls fetch_select, then returns the first value from the first row of results.

count_rows()
$class_name->count_rows ( ) : $number
$class_name->count_rows ( $criteria ) : $number

Return the number of rows in the table. If called with criteria, returns the number of matching rows.

RECORD OBJECTS

Creating Record Objects

new_empty_record()
$class_name->new_empty_record() : $empty_record

Creates and blesses an empty hash object into the given record class.

new_copy()
$record->new_copy() : $new_record

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

Simple Fetch, Change and Save

This interface provides a succinct means of fetching records, making changes to them, and then saving them.

get_record
$class_name->get_record ( ) : $new_empty_record
$class_name->get_record ( $p_key ) : $fetched_record_or_undef

Calls new if no primary key is provided, or if the primary key is zero; otherwise calls fetch_record.

change_values
$record->change_values( key => value1, ... );

Sets the associated key-value pairs in the provided record.

save_record
$record->save_record () : $record_or_undef

Determines whether the record has an primary key assigned to it and then calls either insert_record or update_record. Returns the record unless it fails to save it.

Change and Save Combinations

new_with_values
$class_name->new_with_values ( %key_argument_pairs ) : $record

Calls new_empty_record, and then change_values.

change_and_save
$record->change_and_save ( %key_argument_pairs ) : $record

Calls change_values, and then save_record.

new_and_save
$class_name->new_and_save ( %key_argument_pairs ) : $record

Calls new_empty_record, and then change_and_save.

FETCHING DATA (SQL DQL)

Select to Retrieve Records

fetch_select()
$class_name->fetch_select ( %select_clauses ) : $record_set

Calls the corresponding SQLEngine method with the table name and the provided arguments. Return rows from the table that match the provided criteria, and in the requested order, by executing a SQL select statement.

Each row hash is blessed into the record class before being wrapped in a Record::Set object.

fetch_one_record()
$sqldb->fetch_one_record( %select_clauses ) : $record_hash

Calls fetch_select, then returns only the first row of results.

The row hash is blessed into the record class before being returned.

select_record()
$class_name->select_record ( $primary_key_value ) : $record_obj
$class_name->select_record ( \@compound_primary_key ) : $record_obj
$class_name->select_record ( \%hash_with_primary_key_value ) : $record_obj

Fetches a single record by primary key.

The row hash is blessed into the record class before being returned.

select_records()
$class_name->select_records ( @primary_key_values_or_hashrefs ) : $record_set

Fetches a set of one or more by primary key.

Each row hash is blessed into the record class before being wrapped in a Record::Set object.

visit_select()
$class_name->visit_select ( $sub_ref, %select_clauses ) : @results
$class_name->visit_select ( %select_clauses, $sub_ref ) : @results

Calls the provided subroutine on each matching record as it is retrieved. Returns the accumulated results of each subroutine call (in list context).

Each row hash is blessed into the record class before being the subroutine is called.

Vivifying Records From The Database

These methods are called internally by the various select methods and do not need to be called directly.

record_from_table()
$class_name->record_from_table( $hash_ref )
$class_name->record_from_table( $hash_ref ) : $record
$class_name->record_from_table( %hash_contents ) : $record

Converts a hash retrieved from the table to a Record object.

record_set_from_table()
$class_name->record_set_from_table( $hash_array_ref )
$class_name->record_set_from_table( $hash_array_ref ) : $record_set
$class_name->record_set_from_table( @hash_refs ) : $record_set

Converts an array of hashrefs retrieved from the table to a Record::Set object containing Record objects.

EDITING DATA (SQL DML)

Insert to Add Records

insert_record()
$record_obj->insert_record() : $flag

Adds the values from this record to the table. Returns the number of rows affected, which should be 1 unless there's an error.

Update to Change Records

update_record()
$record_obj->update_record() : $record_count

Update this existing record based on its primary key. Returns the number of rows affected, which should be 1 unless there's an error.

Delete to Remove Records

delete_record()
$record_obj->delete_record() : $record_count

Delete this existing record based on its primary key. Returns the number of rows affected, which should be 1 unless there's an error.

SEE ALSO

See DBIx::SQLEngine for the overall interface and developer documentation.

See DBIx::SQLEngine::Docs::ReadMe for general information about this distribution, including installation and license information.