Provided by: librose-db-object-perl_0.815-1_all bug

NAME

       Rose::DB::Object - Extensible, high performance object-relational mapper (ORM).

SYNOPSIS

         ## For an informal overview of Rose::DB::Object, please
         ## see the Rose::DB::Object::Tutorial documentation.  The
         ## reference documentation follows.

         ## First, set up your Rose::DB data sources, otherwise you
         ## won't be able to connect to the database at all.  See
         ## the Rose::DB documentation for more information.  For
         ## a quick start, see the Rose::DB::Tutorial documentation.

         ##
         ## Create classes - two possible approaches:
         ##

         #
         # 1. Automatic configuration
         #

         package Category;
         use base qw(Rose::DB::Object);
         __PACKAGE__->meta->setup
         (
           table => 'categories',
           auto  => 1,
         );

         ...

         package Price;
         use base qw(Rose::DB::Object);
         __PACKAGE__->meta->setup
         (
           table => 'prices',
           auto  => 1,
         );

         ...

         package Product;
         use base qw(Rose::DB::Object);
         __PACKAGE__->meta->setup
         (
           table => 'products',
           auto  => 1,
         );

         #
         # 2. Manual configuration
         #

         package Category;

         use base qw(Rose::DB::Object);

         __PACKAGE__->meta->setup
         (
           table => 'categories',

           columns =>
           [
             id          => { type => 'int', primary_key => 1 },
             name        => { type => 'varchar', length => 255 },
             description => { type => 'text' },
           ],

           unique_key => 'name',
         );

         ...

         package Price;

         use base qw(Rose::DB::Object);

         __PACKAGE__->meta->setup
         (
           table => 'prices',

           columns =>
           [
             id         => { type => 'int', primary_key => 1 },
             price      => { type => 'decimal' },
             region     => { type => 'char', length => 3 },
             product_id => { type => 'int' }
           ],

           unique_key => [ 'product_id', 'region' ],
         );

         ...

         package Product;

         use base qw(Rose::DB::Object);

         __PACKAGE__->meta->setup
         (
           table => 'products',

           columns =>
           [
             id          => { type => 'int', primary_key => 1 },
             name        => { type => 'varchar', length => 255 },
             description => { type => 'text' },
             category_id => { type => 'int' },

             status =>
             {
               type      => 'varchar',
               check_in  => [ 'active', 'inactive' ],
               default   => 'inactive',
             },

             start_date  => { type => 'datetime' },
             end_date    => { type => 'datetime' },

             date_created     => { type => 'timestamp', default => 'now' },
             last_modified    => { type => 'timestamp', default => 'now' },
           ],

           unique_key => 'name',

           foreign_keys =>
           [
             category =>
             {
               class       => 'Category',
               key_columns => { category_id => 'id' },
             },
           ],

           relationships =>
           [
             prices =>
             {
               type       => 'one to many',
               class      => 'Price',
               column_map => { id => 'product_id' },
             },
           ],
         );

         ...

         #
         # Example usage
         #

         $product = Product->new(id          => 123,
                                 name        => 'GameCube',
                                 status      => 'active',
                                 start_date  => '11/5/2001',
                                 end_date    => '12/1/2007',
                                 category_id => 5);

         $product->save;

         ...

         $product = Product->new(id => 123);
         $product->load;

         # Load foreign object via "one to one" relationship
         print $product->category->name;

         $product->end_date->add(days => 45);

         $product->save;

         ...

         $product = Product->new(id => 456);
         $product->load;

         # Load foreign objects via "one to many" relationship
         print join ' ', $product->prices;

         ...

DESCRIPTION

       Rose::DB::Object is a base class for objects that encapsulate a single row in a database
       table.  Rose::DB::Object-derived objects are sometimes simply called "Rose::DB::Object
       objects" in this documentation for the sake of brevity, but be assured that derivation is
       the only reasonable way to use this class.

       Rose::DB::Object inherits from, and follows the conventions of, Rose::Object.  See the
       Rose::Object documentation for more information.

       For an informal overview of this module distribution, consult the
       Rose::DB::Object::Tutorial.

   Restrictions
       Rose::DB::Object objects can represent rows in almost any database table, subject to the
       following constraints.

       ·   The database server must be supported by Rose::DB.

       ·   The database table must have a primary key.

       ·   The primary key must not allow null values in any of its columns.

       Although the list above contains the only hard and fast rules, there may be other
       realities that you'll need to work around.

       The most common example is the existence of a column name in the database table that
       conflicts with the name of a method in the Rose::DB::Object API.  There are two possible
       workarounds: either explicitly alias the column, or define a mapping function.  See the
       alias_column and column_name_to_method_name_mapper methods in the
       Rose::DB::Object::Metadata documentation for more details.

       There are also varying degrees of support for data types in each database server supported
       by Rose::DB.  If you have a table that uses a data type not supported by an existing
       Rose::DB::Object::Metadata::Column-derived class, you will have to write your own column
       class and then map it to a type name using Rose::DB::Object::Metadata's column_type_class
       method, yada yada.  (Or, of course, you can map the new type to an existing column class.)

       The entire framework is extensible.  This module distribution contains straight-forward
       implementations of the most common column types, but there's certainly more that can be
       done.  Submissions are welcome.

   Features
       Rose::DB::Object provides the following functions:

       ·   Create a row in the database by saving a newly constructed object.

       ·   Initialize an object by loading a row from the database.

       ·   Update a row by saving a modified object back to the database.

       ·   Delete a row from the database.

       ·   Fetch an object referred to by a foreign key in the current object. (i.e., "one to
           one" and "many to one" relationships.)

       ·   Fetch multiple objects that refer to the current object, either directly through
           foreign keys or indirectly through a mapping table.  (i.e., "one to many" and "many to
           many" relationships.)

       ·   Load an object along with "foreign objects" that are related through any of the
           supported relationship types.

       Objects can be loaded based on either a primary key or a unique key.  Since all tables
       fronted by Rose::DB::Objects must have non-null primary keys, insert, update, and delete
       operations are done based on the primary key.

       In addition, its sibling class, Rose::DB::Object::Manager, can do the following:

       ·   Fetch multiple objects from the database using arbitrary query conditions, limits, and
           offsets.

       ·   Iterate over a list of objects, fetching from the database in response to each step of
           the iterator.

       ·   Fetch objects along with "foreign objects" (related through any of the supported
           relationship types) in a single query by automatically generating the appropriate SQL
           join(s).

       ·   Count the number of objects that match a complex query.

       ·   Update objects that match a complex query.

       ·   Delete objects that match a complex query.

       Rose::DB::Object::Manager can be subclassed and used separately (the recommended
       approach), or it can create object manager methods within a Rose::DB::Object subclass.
       See the Rose::DB::Object::Manager documentation for more information.

       Rose::DB::Object can parse, coerce, inflate, and deflate column values on your behalf,
       providing the most convenient possible data representations on the Perl side of the fence,
       while allowing the programmer to completely forget about the ugly details of the data
       formats required by the database.  Default implementations are included for most common
       column types, and the framework is completely extensible.

       Finally, the Rose::DB::Object::Loader can be used to automatically create a suite of
       Rose::DB::Object and Rose::DB::Object::Manager subclasses based on the contents of the
       database.

   Configuration
       Before Rose::DB::Object can do any useful work, you must register at least one Rose::DB
       data source.  By default, Rose::DB::Object instantiates a Rose::DB object by passing no
       arguments to its constructor.  (See the db method.)  If you register a Rose::DB data
       source using the default type and domain, this will work fine.  Otherwise, you must
       override the meta method in your Rose::DB::Object subclass and have it return the
       appropriate Rose::DB-derived object.

       To define your own Rose::DB::Object-derived class, you must describe the table that your
       class will act as a front-end for.    This is done through the Rose::DB::Object::Metadata
       object associated with each Rose::DB::Object-derived class.  The metadata object is
       accessible via Rose::DB::Object's meta method.

       Metadata objects can be populated manually or automatically.  Both techniques are shown in
       the synopsis above.  The automatic mode works by asking the database itself for the
       information.  There are some caveats to this approach.  See the auto-initialization
       section of the Rose::DB::Object::Metadata documentation for more information.

   Serial and Auto-Incremented Columns
       Most databases provide a way to use a series of arbitrary integers as primary key column
       values.  Some support a native "SERIAL" column data type.  Others use a special auto-
       increment column attribute.

       Rose::DB::Object supports at least one such serial or auto-incremented column type in each
       supported database.  In all cases, the Rose::DB::Object-derived class setup is the same:

           package My::DB::Object;
           ...
           __PACKAGE__->meta->setup
           (
             columns =>
             [
               id => { type => 'serial', primary_key => 1, not_null => 1 },
               ...
             ],
             ...
           );

       (Note that the column doesn't have to be named "id"; it can be named anything.)

       If the database column uses big integers, use "bigserial" column "type" instead.

       Given the column metadata definition above, Rose::DB::Object will automatically generate
       and/or retrieve the primary key column value when an object is save()d.  Example:

           $o = My::DB::Object->new(name => 'bud'); # no id specified
           $o->save; # new id value generated here

           print "Generated new id value: ", $o->id;

       This will only work, however, if the corresponding column definition in the database is
       set up correctly.  The exact technique varies from vendor to vendor.  Below are examples
       of primary key column definitions that provide auto-generated values.  There's one example
       for each of the databases supported by Rose::DB.

       ·   PostgreSQL

               CREATE TABLE mytable
               (
                 id   SERIAL PRIMARY KEY,
                 ...
               );

       ·   MySQL

               CREATE TABLE mytable
               (
                 id   INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
                 ...
               );

       ·   SQLite

               CREATE TABLE mytable
               (
                 id   INTEGER PRIMARY KEY AUTOINCREMENT,
                 ...
               );

       ·   Informix

               CREATE TABLE mytable
               (
                 id   SERIAL NOT NULL PRIMARY KEY,
                 ...
               );

       ·   Oracle

           Since Oracle does not natively support a serial or auto-incremented column data type,
           an explicit sequence and trigger must be created to simulate the behavior.  The
           sequence should be named according to this convention: "<table>_<column>_seq".  For
           example, if the table is named "mytable" and the column is named "id", then the
           sequence should be named "mytable_id_seq".  Here's an example database setup.

               CREATE TABLE mytable
               (
                 id   INT NOT NULL PRIMARY KEY,
                 ...
               );

               CREATE SEQUENCE mytable_id_seq;

               CREATE TRIGGER mytable_insert BEFORE INSERT ON mytable
               FOR EACH ROW
               BEGIN
                  IF :new.id IS NULL THEN
                      :new.id := mytable_id_seq.nextval;
                  END IF;
               END;

           Note the conditional that checks if ":new.id" is null, which allows the value of the
           "id" column to be set explicitly.  If a non-NULL value for the "id" column is
           provided, then a new value is not pulled from the sequence.

           If the sequence is not named according to the "<table>_<column>_seq" convention, you
           can specify the sequence name explicitly in the column metadata.  Example:

               columns =>
               [
                 id => { type => 'serial', primary_key => 1, not_null => 1,
                         sequence => 'some_other_seq' },
                 ...

       If the table has a multi-column primary key or does not use a column type that supports
       auto-generated values, you can define a custom primary key generator function using the
       primary_key_generator method of the Rose::DB::Object::Metadata-derived object that
       contains the metadata for this class.  Example:

           package MyDBObject;

           use base qw(Rose::DB::Object);

           __PACKAGE__->meta->setup
           (
             table => 'mytable',

             columns =>
             [
               k1   => { type => 'int', not_null => 1 },
               k2   => { type => 'int', not_null => 1 },
               name => { type => 'varchar', length => 255 },
               ...
             ],

             primary_key_columns => [ 'k1', 'k2' ],

             primary_key_generator => sub
             {
               my($meta, $db) = @_;

               # Generate primary key values somehow
               my $k1 = ...;
               my $k2 = ...;

               return $k1, $k2;
             },
           );

       See the Rose::DB::Object::Metadata documentation for more information on custom primary
       key generators.

   Inheritance
       Simple, single inheritance between Rose::DB::Object-derived classes is supported.
       (Multiple inheritance is not currently supported.)  The first time the metadata object for
       a given class is accessed, it is created by making a one-time "deep copy" of the base
       class's metadata object (as long that the base class has one or more columns set).  This
       includes all columns, relationships, foreign keys, and other metadata from the base class.
       From that point on, the subclass may add to or modify its metadata without affecting any
       other class.

       Tip: When using perl 5.8.0 or later, the Scalar::Util::Clone module is highly recommended.
       If it's installed, it will be used to more efficiently clone base-class metadata objects.

       If the base class has already been initialized, the subclass must explicitly specify
       whether it wants to create a new set of column and relationship methods, or merely inherit
       the methods from the base class.  If the subclass contains any metadata modifications that
       affect method creation, then it must create a new set of methods to reflect those changes.

       Finally, note that column types cannot be changed "in-place."  To change a column type,
       delete the old column and add a new one with the same name.  This can be done in one step
       with the replace_column method.

       Example:

         package BaseClass;
         use base 'Rose::DB::Object';

         __PACKAGE__->meta->setup
         (
           table => 'objects',

           columns =>
           [
             id    => { type => 'int', primary_key => 1 },
             start => { type => 'scalar' },
           ],
         );

         ...

         package SubClass;
         use base 'BaseClass';

         # Set a default value for this column.
         __PACKAGE__->meta->column('id')->default(123);

         # Change the "start" column into a datetime column.
         __PACKAGE__->meta->replace_column(start => { type => 'datetime' });

         # Initialize, replacing any inherited methods with newly created ones
         __PACKAGE__->meta->initialize(replace_existing => 1);

         ...

         $b = BaseClass->new;

         $id = $b->id; # undef

         $b->start('1/2/2003');
         print $b->start; # '1/2/2003' (plain string)

         $s = SubClass->new;

         $id = $s->id; # 123

         $b->start('1/2/2003'); # Value is converted to a DateTime object
         print $b->start->strftime('%B'); # 'January'

       To preserve all inherited methods in a subclass, do this instead:

         package SubClass;
         use base 'BaseClass';
         __PACKAGE__->meta->initialize(preserve_existing => 1);

   Error Handling
       Error handling for Rose::DB::Object-derived objects is controlled by the error_mode method
       of the Rose::DB::Object::Metadata object associated with the class (accessible via the
       meta method).  The default setting is "fatal", which means that Rose::DB::Object methods
       will croak if they encounter an error.

       PLEASE NOTE: The error return values described in the object method documentation are only
       relevant when the error mode is set to something "non-fatal."  In other words, if an error
       occurs, you'll never see any of those return values if the selected error mode dies or
       croaks or otherwise throws an exception when an error occurs.

CONSTRUCTOR

       new PARAMS
           Returns a new Rose::DB::Object constructed according to PARAMS, where PARAMS are
           name/value pairs.  Any object method is a valid parameter name.

CLASS METHODS

       init_db
           Returns the Rose::DB-derived object used to access the database in the absence of an
           explicit db value.  The default implementation simply calls Rose::DB->new() with no
           arguments.

           Override this method in your subclass in order to use a different default data source.
           Note: This method must be callable as both an object method and a class method.

       meta
           Returns the Rose::DB::Object::Metadata-derived object associated with this class.
           This object describes the database table whose rows are fronted by this class: the
           name of the table, its columns, unique keys, foreign keys, etc.

           See the Rose::DB::Object::Metadata documentation for more information.

       meta_class
           Return the name of the Rose::DB::Object::Metadata-derived class used to store this
           object's metadata.  Subclasses should override this method if they want to use a
           custom Rose::DB::Object::Metadata subclass.  (See the source code for
           Rose::DB::Object::Std for an example of this.)

OBJECT METHODS

       db [DB]
           Get or set the Rose::DB object used to access the database that contains the table
           whose rows are fronted by the Rose::DB::Object-derived class.

           If it does not already exist, this object is created with a simple, argument-less call
           to "Rose::DB->new()".  To override this default in a subclass, override the init_db
           method and return the Rose::DB to be used as the new default.

       init_db
           Returns the Rose::DB-derived object used to access the database in the absence of an
           explicit db value.  The default implementation simply calls Rose::DB->new() with no
           arguments.

           Override this method in your subclass in order to use a different default data source.
           Note: This method must be callable as both an object method and a class method.

       dbh [DBH]
           Get or set the DBI database handle contained in db.

       delete [PARAMS]
           Delete the row represented by the current object.  The object must have been
           previously loaded from the database (or must otherwise have a defined primary key
           value) in order to be deleted.  Returns true if the row was deleted or did not exist,
           false otherwise.

           PARAMS are optional name/value pairs.  Valid PARAMS are:

           cascade TYPE
               Also process related rows.  TYPE must be "delete", "null", or "1".  The value "1"
               is an alias for "delete".  Passing an illegal TYPE value will cause a fatal error.

               For each "one to many" relationship, all of the rows in the foreign ("many") table
               that reference the current object ("one") will be deleted in "delete" mode, or
               will have the column(s) that reference the current object set to NULL in "null"
               mode.

               For each "many to many" relationship, all of the rows in the "mapping table" that
               reference the current object will deleted in "delete" mode, or will have the
               columns that reference the two tables that the mapping table maps between set to
               NULL in "null" mode.

               For each "one to one" relationship or foreign key with a "one to one" relationship
               type, all of the rows in the foreign table that reference the current object will
               deleted in "delete" mode, or will have the column(s) that reference the current
               object set to NULL in "null" mode.

               In all modes, if the db is not currently in a transaction, a new transaction is
               started.  If any part of the cascaded delete fails, the transaction is rolled
               back.

           prepare_cached BOOL
               If true, then DBI's prepare_cached method will be used (instead of the prepare
               method) when preparing the SQL statement that will delete the object.  If omitted,
               the default value is determined by the metadata object's dbi_prepare_cached class
               method.

           The cascaded delete feature described above plays it safe by only deleting rows that
           are not referenced by any other rows (according to the metadata provided by each
           Rose::DB::Object-derived class).  I strongly recommend that you implement "cascaded
           delete" in the database itself, rather than using this feature.  It will undoubtedly
           be faster and more robust than doing it "client-side."  You may also want to cascade
           only to certain tables, or otherwise deviate from the "safe" plan.  If your database
           supports automatic cascaded delete and/or triggers, please consider using these
           features.

       error
           Returns the text message associated with the last error that occurred.

       insert [PARAMS]
           Insert the current object to the database table.  This method should only be used when
           you're absolutely sure that you want to force the current object to be inserted,
           rather than updated.  It is recommended that you use the save method instead of this
           one in most circumstances.  The save method will "do the right thing," executing an
           insert or update as appropriate for the current situation.

           PARAMS are optional name/value pairs.  Valid PARAMS are:

           changes_only BOOL
               If true, then only the columns whose values have been modified will be included in
               the insert query.  Otherwise, all columns will be included.  Note that any column
               that has a default value set in its column metadata is considered "modified"
               during an insert operation.

               If omitted, the default value of this parameter is determined by the metadata
               object's default_insert_changes_only class method, which returns false by default.

           prepare_cached BOOL
               If true, then DBI's prepare_cached method will be used (instead of the prepare
               method) when preparing the SQL statement that will insert the object.  If omitted,
               the default value is determined by the metadata object's dbi_prepare_cached class
               method.

           Returns true if the row was inserted successfully, false otherwise.  The true value
           returned on success will be the object itself.  If the object overloads its boolean
           value such that it is not true, then a true value will be returned instead of the
           object itself.

       load [PARAMS]
           Load a row from the database table, initializing the object with the values from that
           row.  An object can be loaded based on either a primary key or a unique key.

           Returns true if the row was loaded successfully, undef if the row could not be loaded
           due to an error, or zero (0) if the row does not exist.  The true value returned on
           success will be the object itself.  If the object overloads its boolean value such
           that it is not true, then a true value will be returned instead of the object itself.

           When loading based on a unique key, unique keys are considered in the order in which
           they were defined in the metadata for this class.  If the object has defined values
           for every column in a unique key, then that key is used.  If no such key is found,
           then the first key for which the object has at least one defined value is used.

           PARAMS are optional name/value pairs.  Valid PARAMS are:

           for_update BOOL
               If true, this parameter is translated to be the equivalent of passing the lock
               parameter and setting the "type" to "for update".  For example, these are both
               equivalent:

                   $object->load(for_update => 1);
                   $object->load(lock => { type => 'for update' });

               See the lock parameter below for more information.

           lock [ TYPE | HASHREF ]
               Load the object using some form of locking.  These lock directives have database-
               specific behavior and not all directives are supported by all databases.  The
               value should be a reference to a hash or a TYPE string, which is equivalent to
               setting the value of the "type" key in the hash reference form.  For example,
               these are both equivalent:

                   $object->load(lock => 'for update');
                   $object->load(lock => { type => 'for update' });

               Valid hash keys are:

               columns ARRAYREF
                   A reference to an array of column names to lock.  References to scalars will
                   be de-referenced and used as-is, included literally in the SQL locking clause.

               "nowait BOOL"
                   If true, do not wait to acquire the lock.    If supported, this is usually by
                   adding a "NOWAIT" directive to the SQL.

               "type TYPE"
                   The lock type.  Valid values for TYPE are "for update" and "shared".  This
                   parameter is required unless the for_update parameter was passed with a true
                   value.

               "wait TIME"
                   Wait for the specified TIME (generally seconds) before giving up acquiring the
                   lock.  If supported, this is usually by adding a "WAIT ..." clause to the SQL.

           nonlazy BOOL
               If true, then all columns will be fetched from the database, even lazy columns.
               If omitted, the default is false.

           prepare_cached BOOL
               If true, then DBI's prepare_cached method will be used (instead of the prepare
               method) when preparing the SQL query that will load the object.  If omitted, the
               default value is determined by the metadata object's dbi_prepare_cached class
               method.

           speculative BOOL
               If this parameter is passed with a true value, and if the load failed because the
               row was not found, then the error_mode setting is ignored and zero (0) is
               returned.  In the absence of an explicitly set value, this parameter defaults to
               the value returned my the metadata object's default_load_speculative method.

           use_key KEY
               Use the unique key named KEY to load the object.  This overrides the unique key
               selection process described above.  The key must have a defined value in at least
               one of its columns.

           with OBJECTS
               Load the object and the specified "foreign objects" simultaneously.  OBJECTS
               should be a reference to an array of foreign key or relationship names.

           SUBCLASS NOTE: If you are going to override the load method in your subclass, you must
           pass an alias to the actual object as the first argument to the method, rather than
           passing a copy of the object reference.  Example:

               # This is the CORRECT way to override load() while still
               # calling the base class version of the method.
               sub load
               {
                 my $self = $_[0]; # Copy, not shift

                 ... # Do your stuff

                 shift->SUPER::load(@_); # Call superclass
               }

           Now here's the wrong way:

               # This is the WRONG way to override load() while still
               # calling the base class version of the method.
               sub load
               {
                 my $self = shift; # WRONG! The alias to the object is now lost!

                 ... # Do your stuff

                 $self->SUPER::load(@_); # This won't work right!
               }

           This requirement exists in order to preserve some sneaky object-replacement
           optimizations in the base class implementation of load.  At some point, those
           optimizations may change or go away.  But if you follow these guidelines, your code
           will continue to work no matter what.

       not_found
           Returns true if the previous call to load failed because a row in the database table
           with the specified primary or unique key did not exist, false otherwise.

       meta
           Returns the Rose::DB::Object::Metadata object associated with this class.  This object
           describes the database table whose rows are fronted by this class: the name of the
           table, its columns, unique keys, foreign keys, etc.

           See the Rose::DB::Object::Metadata documentation for more information.

       save [PARAMS]
           Save the current object to the database table.  In the absence of PARAMS, if the
           object was previously loaded from the database, the row will be updated.  Otherwise, a
           new row will be inserted.  PARAMS are name/value pairs.  Valid PARAMS are listed
           below.

           Actions associated with sub-objects that were added or deleted using one of the
           "*_on_save" relationship or foreign key method types are also performed when this
           method is called.  If there are any such actions to perform, a new transaction is
           started if the db is not already in one, and rollback() is called if any of the
           actions fail during the save().  Example:

               $product = Product->new(name => 'Sled');
               $vendor  = Vendor->new(name => 'Acme');

               $product->vendor($vendor);

               # Product and vendor records created and linked together,
               # all within a single transaction.
               $product->save;

           See the "making methods" sections of the Rose::DB::Object::Metadata::Relationship and
           Rose::DB::Object::Metadata::ForeignKey documentation for a description of the "method
           map" associated with each relationship and foreign key.  Only the actions initiated
           through one of the "*_on_save" method types are handled when save() is called.  See
           the documentation for each individual "*_on_save" method type for more specific
           information.

           Valid parameters to save() are:

           cascade BOOL
               If true, then sub-objects related to this object through a foreign key or
               relationship that have been previously loaded using methods called on this object
               and that contain unsaved changes will be saved after the parent object is saved.
               This proceeds recursively through all sub-objects.  (All other parameters to the
               original call to save are also passed on when saving sub-objects.)

               All database operations are done within a single transaction.  If the db is not
               currently in a transaction, a new transaction is started.  If any part of the
               cascaded save fails, the transaction is rolled back.

               If omitted, the default value of this parameter is determined by the metadata
               object's default_cascade_save class method, which returns false by default.

               Example:

                   $p = Product->new(id => 123)->load;

                   print join(', ', $p->colors); # related Color objects loaded
                   $p->colors->[0]->code('zzz'); # one Color object is modified

                   # The Product object and the modified Color object are saved
                   $p->save(cascade => 1);

           changes_only BOOL
               If true, then only the columns whose values have been modified will be included in
               the insert or update query.  Otherwise, all eligible columns will be included.
               Note that any column that has a default value set in its column metadata is
               considered "modified" during an insert operation.

               If omitted, the default value of this parameter is determined by the metadata
               object's default_update_changes_only class method on update, and the
               default_insert_changes_only class method on insert, both of which return false by
               default.

           insert BOOL
               If set to a true value, then an insert is attempted, regardless of whether or not
               the object was previously loaded from the database.

           prepare_cached BOOL
               If true, then DBI's prepare_cached method will be used (instead of the prepare
               method) when preparing the SQL statement that will save the object.  If omitted,
               the default value is determined by the metadata object's dbi_prepare_cached class
               method.

           update BOOL
               If set to a true value, then an update is attempted, regardless of whether or not
               the object was previously loaded from the database.

           It is an error to pass both the "insert" and "update" parameters in a single call.

           Returns true if the row was inserted or updated successfully, false otherwise.  The
           true value returned on success will be the object itself.  If the object overloads its
           boolean value such that it is not true, then a true value will be returned instead of
           the object itself.

           If an insert was performed and the primary key is a single column that supports auto-
           generated values, then the object accessor for the primary key column will contain the
           auto-generated value.  See the Serial and Auto-Incremented Columns section for more
           information.

       update [PARAMS]
           Update the current object in the database table.  This method should only be used when
           you're absolutely sure that you want to force the current object to be updated, rather
           than inserted.  It is recommended that you use the save method instead of this one in
           most circumstances.  The save method will "do the right thing," executing an insert or
           update as appropriate for the current situation.

           PARAMS are optional name/value pairs.  Valid PARAMS are:

           changes_only BOOL
               If true, then only the columns whose values have been modified will be updated.
               Otherwise, all columns whose values have been loaded from the database will be
               updated.  If omitted, the default value of this parameter is determined by the
               metadata object's default_update_changes_only class method, which returns false by
               default.

           prepare_cached BOOL
               If true, then DBI's prepare_cached method will be used (instead of the prepare
               method) when preparing the SQL statement that will insert the object.  If omitted,
               the default value of this parameter is determined by the metadata object's
               dbi_prepare_cached class method.

           Returns true if the row was updated successfully, false otherwise.  The true value
           returned on success will be the object itself.  If the object overloads its boolean
           value such that it is not true, then a true value will be returned instead of the
           object itself.

RESERVED METHODS

       As described in the Rose::DB::Object::Metadata documentation, each column in the database
       table has an associated get/set accessor method in the Rose::DB::Object.  Since the
       Rose::DB::Object API already defines many methods (load, save, meta, etc.), accessor
       methods for columns that share the name of an existing method pose a problem.  The
       solution is to alias such columns using Rose::DB::Object::Metadata's  alias_column method.

       Here is a list of method names reserved by the Rose::DB::Object API.  If you have a column
       with one of these names, you must alias it.

           db
           dbh
           delete
           DESTROY
           error
           init_db
           _init_db
           insert
           load
           meta
           meta_class
           not_found
           save
           update

       Note that not all of these methods are public.  These methods do not suddenly become
       public just because you now know their names!  Remember the stated policy of the Rose web
       application framework: if a method is not documented, it does not exist.  (And no, the
       list of method names above does not constitute "documentation.")

DEVELOPMENT POLICY

       The Rose development policy applies to this, and all "Rose::*" modules.  Please install
       Rose from CPAN and then run ""perldoc Rose"" for more information.

SUPPORT

       For an informal overview of Rose::DB::Object, consult the Rose::DB::Object::Tutorial.

           perldoc Rose::DB::Object::Tutorial

       Any Rose::DB::Object questions or problems can be posted to the Rose::DB::Object mailing
       list.  To subscribe to the list or view the archives, go here:

       <http://groups.google.com/group/rose-db-object>

       Although the mailing list is the preferred support mechanism, you can also email the
       author (see below) or file bugs using the CPAN bug tracking system:

       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Rose-DB-Object>

       There's also a wiki and other resources linked from the Rose project home page:

       <http://rosecode.org>

CONTRIBUTORS

       Bradley C Bailey, Graham Barr, Kostas Chatzikokolakis, David Christensen, Lucian Dragus,
       Justin Ellison, Perrin Harkins, Cees Hek, Benjamin Hitz, Dave Howorth, Peter Karman, Ed
       Loehr, Adam Mackler, Michael Reece, Thomas Whaples, Douglas Wilson, Teodor Zlatanov

AUTHOR

       John C. Siracusa (siracusa@gmail.com)

LICENSE

       Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This program is free
       software; you can redistribute it and/or modify it under the same terms as Perl itself.