Scroll to navigation

Alzabo::Runtime::Row(3pm)

User Contributed Perl Documentation

Alzabo::Runtime::Row(3pm)

NAME¶

Alzabo::Runtime::Row - Row objects

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, <autarch@urth.org>

2022-06-14

perl v5.34.0