Alzabo::Runtime::Row - Row objects

  use Alzabo::Runtime::Row;

  my $row = $table->row_by_pk( pk => 1 );

  $row->select('foo');

  $row->update( bar => 5 );

  $row->delete;

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

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 CWdelete() 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 CWmake_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 CWAlzabo::Runtime::UniqueRowCache class.

Row objects offer the following methods:

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 CWAlzabo::Runtime::Table->columns.

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

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 CWAlzabo::Runtime::NoSuchRowException if called on a deleted row.

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 CWAlzabo::Runtime::NoSuchRowException if called on a deleted row.

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 CWAlzabo::Runtime::NoSuchRowException if called on a deleted row.

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 CWAlzabo::Runtime::NoSuchRowException if called on a deleted row.

Returns the row's id value as a string. This can be passed to the CWAlzabo::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 CWAlzabo::Runtime::NoSuchRowException if called on a deleted row.

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

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

Indicates whether or not the given row has been deleted

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

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

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

It takes the following parameters:

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.

The potential row state is used for rows which do not yet exist in the database. These are created via the CWAlzabo::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 CWmake_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.

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 CWAlzabo::Runtime::Table->insert method.

Any columns already set will be passed to the CWinsert 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 CW(make_live() method.

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

Dave Rolsky, <autarch@urth.org>