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>