SYNOPSIS

use Alzabo::Runtime::Row;
my $row = $table->row_by_pk( pk => 1 );
$row->select('foo');
$row->update( bar => 5 );
$row->delete;

DESCRIPTION

These objects represent actual rows from the database containing actual data. In general, you will want to use the "Alzabo::Runtime::Table" object to retrieve rows. The "Alzabo::Runtime::Table" object can return either single rows or row cursors.

ROW STATES

Row objects can have a variety of states. Most row objects are ``live'', which means they represent an actual row object. A row can be changed to the ``deleted'' state by calling its "delete()" method. This is a row that no longer exists in the database. Most method calls on rows in this state cause an exception.

There is also a ``potential'' state, for objects which do not represent actual database rows. You can call "make_live()" on these rows in order to change their state to ``live''.

Finally, there is an ``in cache'' state, which is identical to the ``live'' state, except that it is used for object's that are cached via the "Alzabo::Runtime::UniqueRowCache" class.

METHODS

Row objects offer the following methods:

select (@list_of_column_names)

Returns a list of values matching the specified columns in a list context. In scalar context it returns only a single value (the first column specified).

If no columns are specified, it will return the values for all of the columns in the table, in the order that are returned by "Alzabo::Runtime::Table->columns".

This method throws an "Alzabo::Runtime::NoSuchRowException" if called on a deleted row.

select_hash (@list_of_column_names)

Returns a hash of column names to values matching the specified columns.

If no columns are specified, it will return the values for all of the columns in the table.

This method throws an "Alzabo::Runtime::NoSuchRowException" if called on a deleted row.

update (%hash_of_columns_and_values)

Given a hash of columns and values, attempts to update the database to and the object to represent these new values.

It returns a boolean value indicating whether or not any data was actually modified.

This method throws an "Alzabo::Runtime::NoSuchRowException" if called on a deleted row.

refresh

Refreshes the object against the database. This can be used when you want to ensure that a row object is up to date in regards to the database state.

This method throws an "Alzabo::Runtime::NoSuchRowException" if called on a deleted row.

delete

Deletes the row from the RDBMS and changes the object's state to deleted.

For potential rows, this method simply changes the object's state.

This method throws an "Alzabo::Runtime::NoSuchRowException" if called on a deleted row.

id_as_string

Returns the row's id value as a string. This can be passed to the "Alzabo::Runtime::Table->row_by_id" method to recreate the row later.

For potential rows, this method always return an empty string.

This method throws an "Alzabo::Runtime::NoSuchRowException" if called on a deleted row.

is_live

Indicates whether or not the given row represents an actual row in the database.

is_potential

Indicates whether or not the given row represents an actual row in the datatbase.

is_deleted

Indicates whether or not the given row has been deleted

table

Returns the "Alzabo::Runtime::Table" object that this row belongs to.

schema

Returns the "Alzabo::Runtime::Schema" object that this row's table belongs to. This is a shortcut for "$row->table->schema".

rows_by_foreign_key

This method is used to retrieve row objects from other tables by ``following'' a relationship between two tables.

It takes the following parameters:

• foreign_key => "Alzabo::Runtime::ForeignKey" object

Given a foreign key object, this method returns either a row object or a row cursor object the row(s) in the table to which the relationship exist.

The type of object returned is based on the cardinality of the relationship. If the relationship says that there could only be one matching row, then a row object is returned, otherwise it returns a cursor.

POTENTIAL ROWS

The ``potential'' row state is used for rows which do not yet exist in the database. These are created via the "Alzabo::Runtime::Table->potential_row" method.

They are useful when you need a placeholder object which you can update and select from, but you don't actually want to commit the data to the database.

These objects are not cached.

Once "make_live()" is called, the object's state becomes ``live''.

Potential rows have looser constraints for column values than regular rows. When creating a new potential row, it is ok if none of the columns are defined. If a column has a default, and a value for that column is not given, then the default will be used. However, you cannot update a column in a potential row to undef (NULL) if the column is not nullable.

No attempt is made to enforce referential integrity constraints on these objects.

You cannot set a column's value to a database function like ``NOW()'', because this requires interaction with the database.

make_live

This method inserts the row into the database and changes the object's state to ``live''.

This means that all references to the potential row object will now be references to the real object (which is a good thing).

This method can take any parameters that can be passed to the "Alzabo::Runtime::Table->insert" method.

Any columns already set will be passed to the "insert" method, including primary key values. However, these will be overridden, on a column by column basis, by a ``pk'' or ``values'' parameters given to the "(make_live()" method.

Calling this method on a row object that is not in the ``potential'' state will cause an "Alzabo::Runtime::LogicException"

AUTHOR

Dave Rolsky, <[email protected]>