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::Ta-
       ble" 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::Run-
       time::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 relation-
       ship exist.

       The type of object returned is based on the cardinality of the relationship.  If the relationship says that there could only be one match-
       ing 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::Ta-
       ble->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 col-
       umn 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>

perl v5.8.8							    2007-12-23						 Alzabo::Runtime::Row(3pm)