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

NAME

       Rose::DB::Object::Metadata - Database object metadata.

SYNOPSIS

         use Rose::DB::Object::Metadata;

         $meta = Rose::DB::Object::Metadata->new(class => 'Product');
         # ...or...
         $meta = Rose::DB::Object::Metadata->for_class('Product');

         #
         # Auto-initialization
         #

         $meta->table('products'); # optional if class name ends with "::Product"
         $meta->auto_initialize;

         #
         # ...or manual setup
         #

         $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 => 'id_product' },
             },
           ],
         );

         #
         # ...or even more verbose manual setup (old-style, not recommended)
         #

         $meta->table('products');

         $meta->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' },
         );

         $meta->unique_key('name');

         $meta->foreign_keys
         (
           category =>
           {
             class       => 'Category',
             key_columns =>
             {
               category_id => 'id',
             }
           },
         );

         $meta->relationships
         (
           prices =>
           {
             type       => 'one to many',
             class      => 'Price',
             column_map => { id => 'id_product' },
           },
         );

         ...

DESCRIPTION

       Rose::DB::Object::Metadata objects store information about a single table in a database:
       the name of the table, the names and types of columns, any foreign or unique keys, etc.
       These metadata objects are also responsible for supplying information to, and creating
       object methods for, the Rose::DB::Object-derived objects to which they belong.

       Rose::DB::Object::Metadata objects also store information about the Rose::DB::Objects that
       front the database tables they describe.  What might normally be thought of as "class
       data" for the Rose::DB::Object is stored in the metadata object instead, in order to keep
       the method namespace of the Rose::DB::Object-derived class uncluttered.

       Rose::DB::Object::Metadata objects are per-class singletons; there is one
       Rose::DB::Object::Metadata object for each Rose::DB::Object-derived class.  Metadata
       objects are almost never explicitly instantiated.  Rather, there are automatically created
       and accessed through Rose::DB::Object-derived objects' meta method.

       Once created, 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 for more information.

       Rose::DB::Object::Metadata objects contain three categories of objects that are
       responsible for creating object methods in Rose::DB::Object-derived classes: columns,
       foreign keys, and relationships.

       Column objects are subclasses of Rose::DB::Object::Metadata::Column.  They are intended to
       store as much information as possible about each column.  The particular class of the
       column object created for a database column is determined by a mapping table.   The column
       class, in turn, is responsible for creating the accessor/mutator method(s) for the column.
       When it creates these methods, the column class can use (or ignore) any information stored
       in the column object.

       Foreign key objects are of the class Rose::DB::Object::Metadata::ForeignKey.  They store
       information about columns that refer to columns in other tables that are fronted by their
       own Rose::DB::Object-derived classes.  A foreign key object is responsible for creating
       accessor method(s) to fetch the foreign object from the foreign table.

       Relationship objects are subclasses of Rose::DB::Object::Metadata::Relationship.  They
       store information about a table's relationship to other tables that are fronted by their
       own Rose::DB::Object-derived classes.  The particular class of the relationship object
       created for each relationship is determined by a mapping table.   A relationship object is
       responsible for creating accessor method(s) to fetch the foreign objects from the foreign
       table.

AUTO-INITIALIZATION

       Manual population of metadata objects can be tedious and repetitive.  Nearly all of the
       information stored in a Rose::DB::Object::Metadata object exists in the database in some
       form.  It's reasonable to consider simply extracting this information from the database
       itself, rather than entering it all manually.  This automatic metadata extraction and
       subsequent Rose::DB::Object::Metadata object population is called "auto-initialization."

       The example of auto-initialization in the synopsis above is the most succinct variant:

           $meta->auto_initialize;

       As you can read in the documentation for the auto_initialize method, that's shorthand for
       individually auto-initializing each part of the metadata object: columns, the primary key,
       unique keys, and foreign keys.  But this brevity comes at a price.  There are many caveats
       to auto-initialization.

   Caveats
       Start-Up Cost

       In order to retrieve the information required for auto-initialization, a database
       connection must be opened and queries must be run.  Sometimes these queries include
       complex joins.  All of these queries must be successfully completed before the
       Rose::DB::Object-derived objects that the Rose::DB::Object::Metadata is associated with
       can be used.

       In an environment like mod_perl, server start-up time is precisely when you want to do any
       expensive operations.  But in a command-line script or other short-lived process, the
       overhead of auto-initializing many metadata objects may become prohibitive.

       Also, don't forget that auto-initialization requires a database connection.
       Rose::DB::Object-derived objects can sometimes be useful even without a database
       connection (e.g., to temporarily store information that will never go into the database,
       or to synthesize data using object methods that have no corresponding database column).
       When using auto-initialization, this is not possible because the  Rose::DB::Object-derived
       class won't even load if auto-initialization fails because it could not connect to the
       database.

       Detail

       First, auto-initialization cannot generate information that exists only in the mind of the
       programmer.  The most common example is a relationship between two database tables that is
       either ambiguous or totally unexpressed by the database itself.

       For example, if a foreign key constraint does not exist, the relationship between rows in
       two different tables cannot be extracted from the database, and therefore cannot be auto-
       initialized.

       Even within the realm of information that, by all rights, should be available in the
       database, there are limitations.  Although there is a handy DBI API for extracting
       metadata from databases, unfortunately, very few DBI drivers support it fully.  Some don't
       support it at all.  In almost all cases, some manual work is required to (often painfully)
       extract information from the database's "system tables" or "catalog."

       More troublingly, databases do not always provide all the metadata that a human could
       extract from the series of SQL statement that created the table in the first place.
       Sometimes, the information just isn't in the database to be extracted, having been lost in
       the process of table creation.  Here's just one example.  Consider this MySQL table
       definition:

           CREATE TABLE mytable
           (
             id    INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
             code  CHAR(6),
             flag  BOOLEAN NOT NULL DEFAULT 1,
             bits  BIT(5) NOT NULL DEFAULT '00101',
             name  VARCHAR(64)
           );

       Now look at the metadata that MySQL 4 stores internally for this table:

           mysql> describe mytable;
           +-------+------------------+------+-----+---------+----------------+
           | Field | Type             | Null | Key | Default | Extra          |
           +-------+------------------+------+-----+---------+----------------+
           | id    | int(10) unsigned |      | PRI | NULL    | auto_increment |
           | code  | varchar(6)       | YES  |     | NULL    |                |
           | flag  | tinyint(1)       |      |     | 1       |                |
           | bits  | tinyint(1)       |      |     | 101     |                |
           | name  | varchar(64)      | YES  |     | NULL    |                |
           +-------+------------------+------+-----+---------+----------------+

       Note the following divergences from the "CREATE TABLE" statement.

       ·   The "code" column has changed from CHAR(6) to VARCHAR(6).  This is troublesome if you
           want the traditional semantics of a CHAR type, namely the padding with spaces of
           values that are less than the column length.

       ·   The "flag" column has changed from BOOLEAN to TINYINT(1).  The default accessor method
           created for boolean columns has value coercion and formatting properties that are
           important to this data type.  The default accessor created for integer columns lacks
           these constraints.  The metadata object has no way of knowing that "flag" was supposed
           to be a boolean column, and thus makes the wrong kind of accessor method.  It is thus
           possible to store, say, a value of "7" in the "flag" column.  Oops.

       ·   The "bits" column has changed from BIT(5) to TINYINT(1).  As in the case of the "flag"
           column above, this type change prevents the correct accessor method from being
           created.  The default bitfield accessor method auto-inflates column values into
           Bit::Vector objects, which provide convenient methods for bit manipulation.  The
           default accessor created for integer columns does no such thing.

       Remember that the auto-initialization process can only consider the metadata actually
       stored in the database.  It has no access to the original "create table" statement.  Thus,
       the semantics implied by the original table definition are effectively lost.

       Again, this is just one example of the kind of detail that can be lost in the process of
       converting your table definition into metadata that is stored in the database.
       Admittedly, MySQL is perhaps the worst case-scenario, having a well-deserved reputation
       for disregarding the wishes of table definitions.  (The use of implicit default values for
       "NOT NULL" columns is yet another example.)

       Thankfully, there is a solution to this dilemma.  Remember that auto-initialization is
       actually a multi-step process hiding behind that single call to the auto_initialize
       method.  To correct the sins of the database, simply break the auto-initialization process
       into its components.  For example, here's how to correctly auto-initialize the "mytable"
       example above:

           # Make a first pass at column setup
           $meta->auto_init_columns;

           # Account for inaccuracies in DBD::mysql's column info by
           # replacing incorrect column definitions with new ones.

           # Fix CHAR(6) column that shows up as VARCHAR(6)
           $meta->column(code => { type => 'char', length => 6 });

           # Fix BIT(5) column that shows up as TINYINT(1)
           $meta->column(bits => { type => 'bits', bits => 5, default => 101 });

           # Fix BOOLEAN column that shows up as TINYINT(1)
           $meta->column(flag => { type => 'boolean', default => 1 });

           # Do everything else
           $meta->auto_initialize;

       Note that auto_initialize was called at the end.  Without the "replace_existing"
       parameter, this call will preserve any existing metadata, rather than overwriting it, so
       our "corrections" are safe.

       Maintenance

       The price of auto-initialization is eternal vigilance.  "What does that mean?  Isn't auto-
       initialization supposed to save time and effort?"  Well, yes, but at a cost.  In addition
       to the caveats described above, consider what happens when a table definition changes.

       "Ah ha!" you say, "My existing class will automatically pick up the changes the next time
       it's loaded!  Auto-initialization at its finest!"  But is it?  What if you added a "NOT
       NULL" column with no default value?  Yes, your existing auto-initialized class will pick
       up the change, but your existing code will no longer be able to save one these objects.
       Or what if you're using MySQL and your newly added column is one of the types described
       above that requires manual tweaking in order to get the desired semantics.  Will you
       always remember to make this change?

       Auto-initialization is not a panacea.  Every time you make a change to your database
       schema, you must also revisit each affected Rose::DB::Object-derived class to at least
       consider whether or not the metadata needs to be corrected or updated.

       The trade-off may be well worth it, but it's still something to think about.  There is,
       however, a hybrid solution that might be even better.  Continue on to the next section to
       learn more.

   Code Generation
       As described in the section above, auto-initializing metadata at runtime by querying the
       database has many caveats.  An alternate approach is to query the database for metadata
       just once, and then generate the equivalent Perl code which can be pasted directly into
       the class definition in place of the call to auto_initialize.

       Like the auto-initialization process itself, perl code generation has a convenient wrapper
       method as well as separate methods for the individual parts.  All of the perl code
       generation methods begin with "perl_", and they support some rudimentary code formatting
       options to help the code conform to you preferred style.  Examples can be found with the
       documentation for each perl_* method.

       This hybrid approach to metadata population strikes a good balance between upfront effort
       and ongoing maintenance.  Auto-generating the Perl code for the initial class definition
       saves a lot of tedious typing.  From that point on, manually correcting and maintaining
       the definition is a small price to pay for the decreased start-up cost, the ability to use
       the class in the absence of a database connection, and the piece of mind that comes from
       knowing that your class is stable, and won't change behind your back in response to an
       "action at a distance" (i.e., a database schema update).

CLASS METHODS

       auto_prime_caches [BOOL]
           Get or set a boolean value that indicates whether or not the prime_caches method will
           be called from within the initialize method.  The default is true if the "MOD_PERL"
           environment variable ($ENV{'MOD_PERL'}) is set to a true value, false otherwise.

       clear_all_dbs
           Clears the db attribute of the metadata object for each registered class.

       column_type_class TYPE [, CLASS]
           Given the column type string TYPE, return the name of the
           Rose::DB::Object::Metadata::Column-derived class used to store metadata and create the
           accessor method(s) for columns of that type.  If a CLASS is passed, the column type
           TYPE is mapped to CLASS.  In both cases, the TYPE argument is automatically converted
           to lowercase.

       column_type_classes [MAP]
           Get or set the hash that maps column type strings to the names of the
           Rose::DB::Object::Metadata::Column-derived classes used to store metadata  and create
           accessor method(s) for columns of that type.

           This hash is class data.  If you want to modify it, I suggest making your own subclass
           of Rose::DB::Object::Metadata and then setting that as the meta_class of your
           Rose::DB::Object subclass.

           If passed MAP (a list of type/class pairs or a reference to a hash of the same) then
           MAP replaces the current column type mapping.  Returns a list of type/class pairs (in
           list context) or a reference to the hash of type/class mappings (in scalar context).

           The default mapping of type names to class names is:

             scalar    => Rose::DB::Object::Metadata::Column::Scalar

             char      => Rose::DB::Object::Metadata::Column::Character
             character => Rose::DB::Object::Metadata::Column::Character
             varchar   => Rose::DB::Object::Metadata::Column::Varchar
             varchar2  => Rose::DB::Object::Metadata::Column::Varchar
             nvarchar  => Rose::DB::Object::Metadata::Column::Varchar
             nvarchar2 => Rose::DB::Object::Metadata::Column::Varchar
             string    => Rose::DB::Object::Metadata::Column::Varchar

             text      => Rose::DB::Object::Metadata::Column::Text
             blob      => Rose::DB::Object::Metadata::Column::Blob
             bytea     => Rose::DB::Object::Metadata::Column::Pg::Bytea

             bits      => Rose::DB::Object::Metadata::Column::Bitfield
             bitfield  => Rose::DB::Object::Metadata::Column::Bitfield

             bool      => Rose::DB::Object::Metadata::Column::Boolean
             boolean   => Rose::DB::Object::Metadata::Column::Boolean

             int       => Rose::DB::Object::Metadata::Column::Integer
             integer   => Rose::DB::Object::Metadata::Column::Integer

             tinyint   => Rose::DB::Object::Metadata::Column::Integer
             smallint  => Rose::DB::Object::Metadata::Column::Integer
             mediumint => Rose::DB::Object::Metadata::Column::Integer

             bigint    => Rose::DB::Object::Metadata::Column::BigInt

             serial    => Rose::DB::Object::Metadata::Column::Serial
             bigserial => Rose::DB::Object::Metadata::Column::BigSerial

             enum      => Rose::DB::Object::Metadata::Column::Enum

             num       => Rose::DB::Object::Metadata::Column::Numeric
             numeric   => Rose::DB::Object::Metadata::Column::Numeric
             decimal   => Rose::DB::Object::Metadata::Column::Numeric
             float     => Rose::DB::Object::Metadata::Column::Float
             float8    => Rose::DB::Object::Metadata::Column::DoublePrecision

             'double precision' =>
               Rose::DB::Object::Metadata::Column::DoublePrecision

             time      => Rose::DB::Object::Metadata::Column::Time
             interval  => Rose::DB::Object::Metadata::Column::Interval

             date      => Rose::DB::Object::Metadata::Column::Date
             datetime  => Rose::DB::Object::Metadata::Column::Datetime
             timestamp => Rose::DB::Object::Metadata::Column::Timestamp

             timestamptz =>
               Rose::DB::Object::Metadata::Column::TimestampWithTimeZone

             'timestamp with time zone' =>
               Rose::DB::Object::Metadata::Column::TimestampWithTimeZone

             'datetime year to fraction' =>
               Rose::DB::Object::Metadata::Column::DatetimeYearToFraction

             'datetime year to fraction(1)' =>
               Rose::DB::Object::Metadata::Column::DatetimeYearToFraction1

             'datetime year to fraction(2)' =>
               Rose::DB::Object::Metadata::Column::DatetimeYearToFraction2

             'datetime year to fraction(3)' =>
               Rose::DB::Object::Metadata::Column::DatetimeYearToFraction3

             'datetime year to fraction(4)' =>
               Rose::DB::Object::Metadata::Column::DatetimeYearToFraction4

             'datetime year to fraction(5)' =>
               Rose::DB::Object::Metadata::Column::DatetimeYearToFraction5

             'timestamp with time zone' =>
               Rose::DB::Object::Metadata::Column::Timestamp

             'timestamp without time zone' =>
               Rose::DB::Object::Metadata::Column::Timestamp

             'datetime year to second' =>
               Rose::DB::Object::Metadata::Column::DatetimeYearToSecond

             'datetime year to minute' =>
               Rose::DB::Object::Metadata::Column::DatetimeYearToMinute

             'datetime year to month' =>
               Rose::DB::Object::Metadata::Column::DatetimeYearToMonth

             'epoch'       => Rose::DB::Object::Metadata::Column::Epoch
             'epoch hires' => Rose::DB::Object::Metadata::Column::Epoch::HiRes

             array     => Rose::DB::Object::Metadata::Column::Array
             set       => Rose::DB::Object::Metadata::Column::Set

             chkpass   => Rose::DB::Object::Metadata::Column::Pg::Chkpass

       column_type_names
           Returns the list (in list context) or reference to an array (in scalar context) of
           registered column type names.

       convention_manager_class NAME [, CLASS]
           Given the string NAME, return the name of the
           Rose::DB::Object::ConventionManager-derived class mapped to that name.

           If a CLASS is passed, then NAME is mapped to CLASS.

       convention_manager_classes [MAP]
           Get or set the hash that maps names to Rose::DB::Object::ConventionManager-derived
           class names.

           This hash is class data.  If you want to modify it, I suggest making your own subclass
           of Rose::DB::Object::Metadata and then setting that as the meta_class of your
           Rose::DB::Object subclass.

           If passed MAP (a list of name/class pairs or a reference to a hash of the same) then
           MAP replaces the current mapping.  Returns a list of name/class pairs (in list
           context) or a reference to the hash of name/class mappings (in scalar context).

           The default mapping of names to classes is:

             default => Rose::DB::Object::ConventionManager
             null    => Rose::DB::Object::ConventionManager::Null

       dbi_prepare_cached [BOOL]
           Get or set a boolean value that indicates whether or not the Rose::DB::Object-derived
           class will use DBI's prepare_cached method by default (instead of the prepare method)
           when loading, saving, and deleting objects.  The default value is true.

       default_column_undef_overrides_default [BOOL]
           Get or set the default value of the column_undef_overrides_default attribute.
           Defaults to undef.

       default_manager_base_class [CLASS]
           Get or set the default name of the base class used by this metadata class when
           generating a manager classes.  The default value is "Rose::DB::Object::Manager".  See
           the "default_manager_base_class()" object method to override this value for a specific
           metadata object.

       for_class CLASS
           Returns (or creates, if needed) the single Rose::DB::Object::Metadata object
           associated with CLASS, where CLASS is the name of a Rose::DB::Object-derived class.

       init_column_name_to_method_name_mapper
           This class method should return a reference to a subroutine that maps column names to
           method names, or false if it does not want to do any custom mapping.  The default
           implementation returns zero (0).

           If defined, the subroutine should take four arguments: the metadata object, the column
           name, the column method type, and the method name that would be used if the mapper
           subroutine did not exist.  It should return a method name.

       prime_all_caches [PARAMS]
           Call prime_caches on all registered_classes, passing PARAMS to each call.  PARAMS are
           name/value pairs.  Valid parameters are:

           db DB
               A Rose::DB-derived object used to determine which data source the cached metadata
               will be generated on behalf of.  (Each data source has its own set of cached
               metadata.)  This parameter is optional.  If it is not passed, then the
               Rose::DB-derived object returned by the init_db method for each class will be used
               instead.

       relationship_type_class TYPE
           Given the relationship type string TYPE, return the name of the
           Rose::DB::Object::Metadata::Relationship-derived class used to store metadata and
           create the accessor method(s) for relationships of that type.

       relationship_type_classes [MAP]
           Get or set the hash that maps relationship type strings to the names of the
           Rose::DB::Object::Metadata::Relationship-derived classes used to store metadata and
           create object methods fetch and/or manipulate objects from foreign tables.

           This hash is class data.  If you want to modify it, I suggest making your own subclass
           of Rose::DB::Object::Metadata and then setting that as the meta_class of your
           Rose::DB::Object subclass.

           If passed MAP (a list of type/class pairs or a reference to a hash of the same) then
           MAP replaces the current relationship type mapping.  Returns a list of type/class
           pairs (in list context) or a reference to the hash of type/class mappings (in scalar
           context).

           The default mapping of type names to class names is:

             'one to one'   => Rose::DB::Object::Metadata::Relationship::OneToOne
             'one to many'  => Rose::DB::Object::Metadata::Relationship::OneToMany
             'many to one'  => Rose::DB::Object::Metadata::Relationship::ManyToOne
             'many to many' => Rose::DB::Object::Metadata::Relationship::ManyToMany

       registered_classes
           Return a list (in list context) or reference to an array (in scalar context) of the
           names of all Rose::DB::Object-derived classes registered under this metadata class's
           registry_key.

       registry_key
           Returns the string used to group Rose::DB::Object-derived class names in the class
           registry.  The default is "Rose::DB::Object::Metadata".

CONSTRUCTOR

       new PARAMS
           Returns (or creates, if needed) the single Rose::DB::Object::Metadata associated with
           a particular Rose::DB::Object-derived class, modifying or initializing it according to
           PARAMS, where PARAMS are name/value pairs.

           Any object method is a valid parameter name, but PARAMS must include a value for the
           "class" parameter, since that's how Rose::DB::Object::Metadata objects are mapped to
           their corresponding Rose::DB::Object-derived class.

OBJECT METHODS

       add_column ARGS
           This is an alias for the add_columns method.

       add_columns ARGS
           Add the columns specified by ARGS to the list of columns for the table.  Returns the
           list of columns added in list context, or a reference to an array of columns added in
           scalar context.  Columns can be specified in ARGS in several ways.

           If an argument is a subclass of Rose::DB::Object::Metadata::Column, it is added as-is.

           If an argument is a plain scalar, it is taken as the name of a scalar column.  A
           column object of the class returned by the method call
           "$obj->column_type_class('scalar')" is constructed and then added.

           Otherwise, only name/value pairs are considered, where the name is taken as the column
           name and the value must be a reference to a hash.

           If the hash contains the key "primary_key" with a true value, then the column is
           marked as a primary_key_member and the column name is added to the list of primary key
           columns by calling the add_primary_key_column method with the column name as its
           argument.

           If the hash contains the key "alias", then the value of that key is used as the alias
           for the column.  This is a shorthand equivalent to explicitly calling the alias_column
           column method.

           If the hash contains the key "temp" and its value is true, then the column is actually
           added to the list of non-persistent columns.

           If the hash contains a key with the same name as a column trigger event type (e.g.,
           "on_set", "on_load", "inflate") then the value of that key must be a code reference or
           a reference to an array of code references, which will be added to the list of the
           column's triggers for the specified event type.

           If the hash contains the key "methods", then its value must be a reference to an array
           or a reference to a hash.  The auto_method_types of the column are then set to the
           values of the referenced array, or the keys of the referenced hash.  The values of the
           referenced hash are used to set the method_name for their corresponding method types.

           If the hash contains the key "add_methods", then its value must be a reference to an
           array or a reference to a hash.  The values of the referenced array or the keys of the
           referenced hash are added to the column's auto_method_types.  The values of the
           referenced hash are used to set the method_name for their corresponding method types.

           If the "methods" and "add_methods" keys are both set, a fatal error will occur.

           Then the column_type_class method is called with the value of the "type" hash key as
           its argument (or "scalar" if that key is missing), returning the name of a column
           class.  Finally, a new column object of that class is constructed and is passed all
           the remaining pairs in the hash reference, along with the name and type of the column.
           That column object is then added to the list of columns.

           This is done until there are no more arguments to be processed, or until an argument
           does not conform to one of the required formats, in which case a fatal error occurs.

           Example:

               $meta->add_columns
               (
                 # Add a scalar column
                 'name',

                 # which is roughly equivalent to:
                 #
                 # $class = $meta->column_type_class('scalar');
                 # $col = $class->new(name => 'name');
                 # (then add $col to the list of columns)

                 # Add by name/hashref pair with explicit method types
                 age => { type => 'int', default => 5, methods => [ 'get', 'set' ] },

                 # which is roughly equivalent to:
                 #
                 # $class = $meta->column_type_class('int');
                 # $col = $class->new(name    => 'age',
                 #                    type    => 'int',
                 #                    default => 5);
                 # $col->auto_method_types('get', 'set');
                 # (then add $col to the list of columns)

                 # Add by name/hashref pair with additional method type and name
                 size => { type => 'int', add_methods => { 'set' => 'set_my_size' } },

                 # which is roughly equivalent to:
                 #
                 # $class = $meta->column_type_class('int');
                 # $col = $class->new(name    => 'size',
                 #                    type    => 'int',);
                 # $col->add_auto_method_types('set');
                 # $col->method_name(set => 'set_my_size');
                 # (then add $col to the list of columns)

                 # Add a column object directly
                 Rose::DB::Object::Metadata::Column::Date->new(
                   name => 'start_date'),
               );

       add_nonpersistent_column ARGS
           This is an alias for the add_nonpersistent_columns method.

       add_nonpersistent_columns ARGS
           This method behaves like the add_columns method, except that it adds to the list of
           non-persistent columns.  See the documentation for the nonpersistent_columns method
           for more information.

       add_foreign_keys ARGS
           Add foreign keys as specified by ARGS.  Each foreign key must have a name that is
           unique among all other foreign keys in this class.

           Foreign keys can be specified in ARGS in several ways.

           If an argument is a Rose::DB::Object::Metadata::ForeignKey object (or subclass
           thereof), it is added as-is.

           Otherwise, only name/value pairs are considered, where the name is taken as the
           foreign key name and the value must be a reference to a hash.

           If the hash contains the key "methods", then its value must be a reference to an array
           or a reference to a hash.  The auto_method_types of the foreign key are then set to
           the values of the referenced array, or the keys of the referenced hash.  The values of
           the referenced hash are used to set the method_name for their corresponding method
           types.

           If the hash contains the key "add_methods", then its value must be a reference to an
           array or a reference to a hash.  The values of the referenced array or the keys of the
           referenced hash are added to the foreign key's auto_method_types.  The values of the
           referenced hash are used to set the method_name for their corresponding method types.

           If the "methods" and "add_methods" keys are both set, a fatal error will occur.

           A new Rose::DB::Object::Metadata::ForeignKey object is constructed and is passed all
           the remaining pairs in the hash reference, along with the name of the foreign key as
           the value of the "name" parameter.  That foreign key object is then added to the list
           of foreign keys.

           This is done until there are no more arguments to be processed, or until an argument
           does not conform to one of the required formats, in which case a fatal error occurs.

           Example:

               $meta->add_foreign_keys
               (
                 # Add by name/hashref pair with explicit method type
                 category =>
                 {
                   class       => 'Category',
                   key_columns => { category_id => 'id' },
                   methods => [ 'get' ],
                 },

                 # which is roughly equivalent to:
                 #
                 # $fk = Rose::DB::Object::Metadata::ForeignKey->new(
                 #         class       => 'Category',
                 #         key_columns => { category_id => 'id' },
                 #         name        => 'category');
                 # $fk->auto_method_types('get');
                 # (then add $fk to the list of foreign keys)

                 # Add by name/hashref pair with additional method type and name
                 color =>
                 {
                   class       => 'Color',
                   key_columns => { color_id => 'id' },
                   add_methods => { set => 'set_my_color' },
                 },

                 # which is roughly equivalent to:
                 #
                 # $fk = Rose::DB::Object::Metadata::ForeignKey->new(
                 #         class       => 'Color',
                 #         key_columns => { color_id => 'id' },
                 #         name        => 'color');
                 # $fk->add_auto_method_types('set');
                 # $fk->method_name(set => 'set_my_color');
                 # (then add $fk to the list of foreign keys)

                 # Add a foreign key object directly
                 Rose::DB::Object::Metadata::ForeignKey->new(...),
               );

           For each foreign key added, a corresponding relationship with the same name is added
           if it does not already exist.  The relationship type is determined by the value of the
           foreign key object's relationship attribute.  The default is "many to one".  The class
           of the relationship is chosen by calling relationship_type_class with the relationship
           type as an argument.

       add_primary_key_column COLUMN
           This method is an alias for add_primary_key_columns.

       add_primary_key_columns COLUMNS
           Add COLUMNS to the list of columns that make up the primary key.  COLUMNS can be a
           list or reference to an array of column names.

       add_relationship ARGS
           This is an alias for the add_relationships method.

       add_relationships ARGS
           Add relationships as specified by ARGS.  Each relationship must have a name that is
           unique among all other relationships in this class.

           Relationships can be specified in ARGS in several ways.

           If an argument is a subclass of Rose::DB::Object::Metadata::Relationship, it is added
           as-is.

           Otherwise, only name/value pairs are considered, where the name is taken as the
           relationship name and the value must be a reference to a hash.

           If the hash contains the key "methods", then its value must be a reference to an array
           or a reference to a hash.  The auto_method_types of the relationship are then set to
           the values of the referenced array, or the keys of the referenced hash.  The values of
           the referenced hash are used to set the method_name for their corresponding method
           types.

           If the hash contains the key "add_methods", then its value must be a reference to an
           array or a reference to a hash.  The values of the referenced array or the keys of the
           referenced hash are added to the relationship's auto_method_types.  The values of the
           referenced hash are used to set the method_name for their corresponding method types.

           If the "methods" and "add_methods" keys are both set, a fatal error will occur.

           Then the relationship_type_class method is called with the value of the "type" hash
           key as its argument, returning the name of a relationship class.

           Finally, a new relationship object of that class is constructed and is passed all the
           remaining pairs in the hash reference, along with the name and type of the
           relationship.  That relationship object is then added to the list of relationships.

           This is done until there are no more arguments to be processed, or until an argument
           does not conform to one of the required formats, in which case a fatal error occurs.

           Example:

               $meta->add_relationships
               (
                 # Add by name/hashref pair with explicit method type
                 category =>
                 {
                   type       => 'many to one',
                   class      => 'Category',
                   column_map => { category_id => 'id' },
                   methods    => [ 'get' ],
                 },

                 # which is roughly equivalent to:
                 #
                 # $class = $meta->relationship_type_class('many to one');
                 # $rel = $class->new(class      => 'Category',
                 #                    column_map => { category_id => 'id' },
                 #                    name       => 'category');
                 # $rel->auto_method_types('get');
                 # (then add $rel to the list of relationships)

                 # Add by name/hashref pair with additional method type and name
                 color =>
                 {
                   type        => 'many to one',
                   class       => 'Color',
                   column_map  => { color_id => 'id' },
                   add_methods => { set => 'set_my_color' },
                 },

                 # which is roughly equivalent to:
                 #
                 # $class = $meta->relationship_type_class('many to one');
                 # $rel = $class->new(class      => 'Color',
                 #                    column_map => { color_id => 'id' },
                 #                    name       => 'color');
                 # $rel->add_auto_method_types('set');
                 # $fk->method_name(set => 'set_my_color');
                 # (rel add $fk to the list of foreign keys)

                 # Add a relationship object directly
                 Rose::DB::Object::Metadata::Relationship::OneToOne->new(...),
               );

       add_unique_key KEY
           This method is an alias for add_unique_keys.

       add_unique_keys KEYS
           Add new unique keys specified by KEYS.  Unique keys can be specified in KEYS in two
           ways.

           If an argument is a Rose::DB::Object::Metadata::UniqueKey object (or subclass
           thereof), then its parent is set to the metadata object itself, and it is added.

           Otherwise, an argument must be a single column name or a reference to an array of
           column names that make up a unique key.  A new Rose::DB::Object::Metadata::UniqueKey
           is created, with its parent set to the metadata object itself, and then the unique key
           object is added to this list of unique keys for this class.

       alias_column NAME, ALIAS
           Set the alias for the column named NAME to ALIAS.  It is sometimes necessary to use an
           alias for a column because the column name conflicts with an existing Rose::DB::Object
           method name.

           For example, imagine a column named "save".  The Rose::DB::Object API already defines
           a method named save, so obviously that name can't be used for the accessor method for
           the "save" column.  To solve this, make an alias:

               $meta->alias_column(save => 'save_flag');

           See the Rose::DB::Object documentation or call the method_name_is_reserved method to
           determine if a method name is reserved.

       allow_inline_column_values [BOOL]
           Get or set the boolean flag that indicates whether or not the associated
           Rose::DB::Object-derived class should try to inline column values that DBI does not
           handle correctly when they are bound to placeholders using bind_columns.  The default
           value is false.

           Enabling this flag reduces the performance of the update and insert operations on the
           Rose::DB::Object-derived object.  But it is sometimes necessary to enable the flag
           because some DBI drivers do not (or cannot) always do the right thing when binding
           values to placeholders in SQL statements.  For example, consider the following SQL for
           the Informix database:

               CREATE TABLE test (d DATETIME YEAR TO SECOND);
               INSERT INTO test (d) VALUES (CURRENT);

           This is valid Informix SQL and will insert a row with the current date and time into
           the "test" table.

           Now consider the following attempt to do the same thing using DBI placeholders (assume
           the table was already created as per the CREATE TABLE statement above):

               $sth = $dbh->prepare('INSERT INTO test (d) VALUES (?)');
               $sth->execute('CURRENT'); # Error!

           What you'll end up with is an error like this:

               DBD::Informix::st execute failed: SQL: -1262: Non-numeric
               character in datetime or interval.

           In other words, DBD::Informix has tried to quote the string "CURRENT", which has
           special meaning to Informix only when it is not quoted.

           In order to make this work, the value "CURRENT" must be "inlined" rather than bound to
           a placeholder when it is the value of a "DATETIME YEAR TO SECOND" column in an
           Informix database.

       auto_load_related_classes [BOOL]
           Get or set a flag that indicates whether or not classes related to this class through
           a foreign key or other relationship will be automatically loaded when this class is
           initialized.  The default value is true.

       cached_objects_expire_in [DURATION]
           This method is only applicable if this metadata object is associated with a
           Rose::DB::Object::Cached-derived class.  It simply calls the class method of the same
           name that belongs to the Rose::DB::Object::Cached-derived class associated with this
           metadata object.

       catalog [CATALOG]
           Get or set the database catalog for this class.  This setting will override any
           setting in the db object.  Use this method only if you know that the class will always
           point to a specific catalog, regardless of what the Rose::DB-derived database handle
           object specifies.

       class [CLASS]
           Get or set the Rose::DB::Object-derived class associated with this metadata object.
           This is the class where the accessor methods for each column will be created (by
           make_methods).

       class_for PARAMS
           Returns the name of the Rose::DB::Object-derived class associated with the "catalog",
           "schema", and "table" specified by the name/value paris in PARAMS.  Catalog and/or
           schema maybe omitted if unknown or inapplicable, and the "best" match will be
           returned.  Returns undef if there is no class name registered under the specified
           PARAMS.

           Note: This method may also be called as a class method, but may require explicit
           "catalog" and/or "schema" arguments when dealing with databases that support these
           concepts and have default implicit values for them.

       clear_object_cache
           This method is only applicable if this metadata object is associated with a
           Rose::DB::Object::Cached-derived class.  It simply calls the class method of the same
           name that belongs to the Rose::DB::Object::Cached-derived class associated with this
           metadata object.

       column NAME [, COLUMN | HASHREF]
           Get or set the column named NAME.  If just NAME is passed, the
           Rose::DB::Object::Metadata::Column-derived column object for the column of that name
           is returned.  If no such column exists, undef is returned.

           If both NAME and COLUMN are passed, then COLUMN must be a
           Rose::DB::Object::Metadata::Column-derived object.  COLUMN has its name set to NAME,
           and is then stored as the column metadata object for NAME, replacing any existing
           column.

           If both NAME and HASHREF are passed, then the combination of NAME and HASHREF must
           form a name/value pair suitable for passing to the add_columns method.  The new column
           specified by NAME and HASHREF replaces any existing column.

       columns [ARGS]
           Get or set the full list of columns.  If ARGS are passed, the column list is cleared
           and then ARGS are passed to the add_columns method.

           Returns a list of column objects in list context, or a reference to an array of column
           objects in scalar context.

       column_accessor_method_name NAME
           Returns the name of the "get" method for the column named NAME.  This is just a
           shortcut for "$meta->column(NAME)->accessor_method_name".

       column_accessor_method_names
           Returns a list (in list context) or a reference to the array (in scalar context) of
           the names of the "set" methods for all the columns, in the order that the columns are
           returned by column_names.

       column_aliases [MAP]
           Get or set the hash that maps column names to their aliases.  If passed MAP (a list of
           name/value pairs or a reference to a hash) then MAP replaces the current alias
           mapping.  Returns a reference to the hash that maps column names to their aliases.

           Note that modifying this map has no effect if initialize, make_methods, or
           make_column_methods has already been called for the current class.

       column_mutator_method_name NAME
           Returns the name of the "set" method for the column named NAME.  This is just a
           shortcut for "$meta->column(NAME)->mutator_method_name".

       column_mutator_method_names
           Returns a list (in list context) or a reference to the array (in scalar context) of
           the names of the "set" methods for all the columns, in the order that the columns are
           returned by column_names.

       column_names
           Returns a list (in list context) or a reference to an array (in scalar context) of
           column names.

       column_name_to_method_name_mapper [CODEREF]
           Get or set the code reference to the subroutine used to map column names to  method
           names.  If undefined, then the init_column_name_to_method_name_mapper class method is
           called in order to initialize it.  If still undefined or false, then the "default"
           method name is used.

           If defined, the subroutine should take four arguments: the metadata object, the column
           name, the column method type, and the method name that would be used if the mapper
           subroutine did not exist.  It should return a method name.

       column_rw_method_name NAME
           Returns the name of the "get_set" method for the column named NAME.  This is just a
           shortcut for "$meta->column(NAME)->rw_method_name".

       column_rw_method_names
           Returns a list (in list context) or a reference to the array (in scalar context) of
           the names of the "get_set" methods for all the columns, in the order that the columns
           are returned by column_names.

       column_undef_overrides_default [BOOL]
           Get or set a boolean value that influences the default value of the
           undef_overrides_default attribute for each column in this class.  See the
           documentation for Rose::DB::Object::Metadata::Column's undef_overrides_default
           attribute for more information.

           Defaults to the value returned by the default_column_undef_overrides_default class
           method.

       convention_manager [ OBJECT | CLASS | NAME ]
           Get or set the convention manager for this class.  Defaults to the return value of the
           init_convention_manager method.

           If undef is passed, then a Rose::DB::Object::ConventionManager::Null object is stored
           instead.

           If a Rose::DB::Object::ConventionManager-derived object is passed, its meta attribute
           set to this metadata object and then it is used as the convention manager for this
           class.

           If a Rose::DB::Object::ConventionManager-derived class name is passed, a new object of
           that class is created with its meta attribute set to this metadata object.  Then it is
           used as the convention manager for this class.

           If a convention manager name is passed, then the corresponding class is looked up in
           the convention manager class map, a new object of that class is constructed, its meta
           attribute set to this metadata object, and it is used as the convention manager for
           this class.  If there is no class mapped to NAME, a fatal error will occur.

           See the Rose::DB::Object::ConventionManager documentation for more information on
           convention managers.

       db  Returns the Rose::DB-derived object associated with this metadata object's class.  A
           fatal error will occur if class is undefined or if the Rose::DB object could not be
           created.

       default_cascade_save [BOOL]
           Get or set a boolean value that indicates whether or not the class associated with
           this metadata object will save related objects when the parent object is saved.  See
           the documentation for Rose::DB::Object's save() method for details.  The default value
           is false.

       default_load_speculative [BOOL]
           Get or set a boolean value that indicates whether or not the class associated with
           this metadata object will load speculatively by default.  See the documentation for
           Rose::DB::Object's load() method for details.  The default value is false.

       default_update_changes_only [BOOL]
           Get or set a boolean value that indicates whether or not the class associated with
           this metadata object will update only an object's modified columns by default (instead
           of updating all columns).  See the documentation for Rose::DB::Object's update()
           method for details.  The default value is false.

       delete_column NAME
           Delete the column named NAME.

       delete_columns
           Delete all of the columns.

       delete_column_type_class TYPE
           Delete the type/class mapping entry for the column type TYPE.

       delete_convention_manager_class NAME
           Delete the name/class mapping entry for the convention manager class mapped to NAME.

       delete_nonpersistent_column NAME
           Delete the non-persistent column named NAME.

       delete_nonpersistent_columns
           Delete all of the nonpersistent_columns.

       delete_relationship NAME
           Delete the relationship named NAME.

       delete_relationships
           Delete all of the relationships.

       delete_relationship_type_class TYPE
           Delete the type/class mapping entry for the relationship type TYPE.

       delete_unique_keys
           Delete all of the unique key definitions.

       error_mode [MODE]
           Get or set the error mode of the Rose::DB::Object that fronts the table described by
           this Rose::DB::Object::Metadata object.  If the error mode is false, then it defaults
           to the return value of the "init_error_mode" method, which is "fatal" by default.

           The error mode determines what happens when a Rose::DB::Object method encounters an
           error.  The "return" error mode causes the methods to behave as described in the
           Rose::DB::Object documentation.  All other error modes cause an action to be performed
           before (possibly) returning as per the documentation (depending on whether or not the
           "action" is some variation on "throw an exception.")

           Valid values of MODE are:

           carp
               Call Carp::carp with the value of the object error as an argument.

           cluck
               Call Carp::cluck with the value of the object error as an argument.

           confess
               Call Carp::confess with the value of the object error as an argument.

           croak
               Call Carp::croak with the value of the object error as an argument.

           fatal
               An alias for the "croak" mode.

           return
               Return a value that indicates that an error has occurred, as described in the
               documentation for each method.

           In all cases, the object's error attribute will also contain the error message.

       first_column
           Returns the first column, determined by the order that columns were added, or undef if
           there are no columns.

       foreign_key NAME [, FOREIGNKEY | HASHREF ]
           Get or set the foreign key named NAME.  NAME should be the name of the thing being
           referenced by the foreign key, not the name of any of the columns that make up the
           foreign key.  If called with just a NAME argument, the foreign key stored under that
           name is returned.  Undef is returned if there is no such foreign key.

           If both NAME and FOREIGNKEY are passed, then FOREIGNKEY must be a
           Rose::DB::Object::Metadata::ForeignKey-derived object.  FOREIGNKEY has its name set to
           NAME, and is then stored, replacing any existing foreign key with the same name.

           If both NAME and HASHREF are passed, then the combination of NAME and HASHREF must
           form a name/value pair suitable for passing to the add_foreign_keys method.  The new
           foreign key specified by NAME and HASHREF replaces any existing foreign key with the
           same name.

       foreign_keys [ARGS]
           Get or set the full list of foreign keys.  If ARGS are passed, the foreign key list is
           cleared and then ARGS are passed to the add_foreign_keys method.

           Returns a list of foreign key objects in list context, or a reference to an array of
           foreign key objects in scalar context.

       generate_primary_key_value DB
           This method is the same as generate_primary_key_values except that it only returns the
           generated value for the first primary key column, rather than the entire list of
           values.  Use this method only when there is a single primary key column (or not at
           all).

       generate_primary_key_values DB
           Given the Rose::DB-derived object DB, generate and return a list of new primary key
           column values for the table described by this metadata object.

           If a primary_key_generator is defined, it will be called (passed this metadata object
           and the DB) and its value returned.

           If no primary_key_generator is defined, new primary key values will be generated, if
           possible, using the native facilities of the current database.  Note that this may not
           be possible for databases that auto-generate such values only after an insertion.  In
           that case, undef will be returned.

       include_predicated_unique_indexes [BOOL]
           Get or set a boolean value that indicates whether or not the auto_init_unique_keys
           method will create unique keys for unique indexes that have predicates.  The default
           value is false.  This feature is currently only supported for PostgreSQL.

           Here's an example of a unique index that has a predicate:

               CREATE UNIQUE INDEX my_idx ON mytable (mycolumn) WHERE mycolumn > 123;

           The predicate in this case is "WHERE mycolumn > 123".

           Predicated unique indexes differ semantically from unpredicated unique indexes in that
           predicates generally cause the index to only  apply to part of a table.
           Rose::DB::Object expects unique indexes to uniquely identify a row within a table.
           Predicated indexes that fail to do so due to their predicates should therefore not
           have Rose::DB::Object::Metadata::UniqueKey objects created for them, thus the false
           default for this attribute.

       init_convention_manager
           Returns the default Rose::DB::Object::ConventionManager-derived object used as the
           convention manager for this class.  This object will be of the class returned by
           convention_manager_class('default').

           Override this method in your Rose::DB::Object::Metadata subclass, or re-map the
           "default" convention manager class, in order to use a different convention manager
           class.  See the tips and tricks section of the Rose::DB::Object::ConventionManager
           documentation for an example of the subclassing approach.

       initialize [ARGS]
           Initialize the Rose::DB::Object-derived class associated with this metadata object by
           creating accessor methods for each column and foreign key.  The table name and the
           primary_key_columns must be defined or a fatal error will occur.

           If any column name in the primary key or any of the unique keys does not exist in the
           list of columns, then that primary or unique key is deleted.  (As per the above, this
           will trigger a fatal error if any column in the primary key is not in the column
           list.)

           ARGS, if any, are passed to the call to make_methods that actually creates the
           methods.

           If auto_prime_caches is true, then the prime_caches method will be called at the end
           of the initialization process.

       is_initialized [BOOL]
           Get or set a boolean value that indicates whether or not this class was initialized.
           A successful call to the initialize method will automatically set this flag to true.

       make_manager_class [PARAMS | CLASS]
           This method creates a Rose::DB::Object::Manager-derived class to manage objects of
           this class.  To do so, it simply calls perl_manager_class, passing all arguments, and
           then evaluates the result.  See the perl_manager_class documentation for more
           information.

       make_methods [ARGS]
           Create object methods in class for each column, foreign key, and relationship.  This
           is done by calling make_column_methods, make_nonpersistent_column_methods,
           make_foreign_key_methods, and make_relationship_methods, in that order.

           ARGS are name/value pairs which are passed on to the other "make_*_methods" calls.
           They are all optional.  Valid ARGS are:

           ·   "preserve_existing"

               If set to a true value, a method will not be created if there is already an
               existing method with the same named.

           ·   "replace_existing"

               If set to a true value, override any existing method with the same name.

           In the absence of one of these parameters, any method name that conflicts with an
           existing method name will cause a fatal error.

       make_column_methods [ARGS]
           Create accessor/mutator methods in class for each column.  ARGS are name/value pairs,
           and are all optional.  Valid ARGS are:

           ·   "preserve_existing"

               If set to a true value, a method will not be created if there is already an
               existing method with the same named.

           ·   "replace_existing"

               If set to a true value, override any existing method with the same name.

           For each auto_method_type in each column, the method name is determined by passing the
           column name and the method type to method_name_from_column_name.  If the resulting
           method name is reserved (according to method_name_is_reserved, a fatal error will
           occur.  The object methods for each column are created by calling the column object's
           make_methods method.

       make_foreign_key_methods [ARGS]
           Create object methods in class for each foreign key.  ARGS are name/value pairs, and
           are all optional.  Valid ARGS are:

           ·   "preserve_existing"

               If set to a true value, a method will not be created if there is already an
               existing method with the same named.

           ·   "replace_existing"

               If set to a true value, override any existing method with the same name.

           For each auto_method_type in each foreign key, the method name is determined by
           passing the method type to the method_name method of the foreign key object, or the
           build_method_name_for_type method if the method_name call returns a false value.  If
           the method name is reserved (according to method_name_is_reserved), a fatal error will
           occur.  The object methods for each foreign key are created by calling the foreign key
           object's make_methods method.

           Foreign keys and relationships with the type "one to one" or "many to one" both
           encapsulate essentially the same information.  They are kept in sync when this method
           is called by setting the foreign_key attribute of each "one to one" or "many to one"
           relationship object to be the corresponding foreign key object.

       make_nonpersistent_column_methods [ARGS]
           This method behaves like the make_column_methods method, except that it works with
           non-persistent columns.  See the documentation for the nonpersistent_columns method
           for more information on non-persistent columns.

       make_relationship_methods [ARGS]
           Create object methods in class for each relationship.  ARGS are name/value pairs, and
           are all optional.  Valid ARGS are:

           ·   "preserve_existing"

               If set to a true value, a method will not be created if there is already an
               existing method with the same named.

           ·   "replace_existing"

               If set to a true value, override any existing method with the same name.

           For each auto_method_type in each relationship, the method name is determined by
           passing the method type to the method_name method of the relationship object, or the
           build_method_name_for_type method if the method_name call returns a false value.  If
           the method name is reserved (according to method_name_is_reserved), a fatal error will
           occur.  The object methods for each relationship are created by calling the
           relationship  object's make_methods method.

           Foreign keys and relationships with the type "one to one" or "many to one" both
           encapsulate essentially the same information.  They are kept in sync when this method
           is called by setting the foreign_key attribute of each "one to one" or "many to one"
           relationship object to be the corresponding foreign key object.

           If a relationship corresponds exactly to a foreign key, and that foreign key already
           made an object method, then the relationship is not asked to make its own method.

       default_manager_base_class [CLASS]
           Get or set the default name of the base class used by this specific metadata object
           when generating a manager class, using either the perl_manager_class or
           make_manager_class methods.  The default value is determined by the
           "default_manager_base_class|/default_manager_base_class()" class method.

       method_column METHOD
           Returns the name of the column manipulated by the method named METHOD.

       method_name_from_column_name NAME, TYPE
           Looks up the column named NAME and calls method_name_from_column with the column and
           TYPE as argument.  If no such column exists, a fatal error will occur.

       method_name_from_column COLUMN, TYPE
           Given a Rose::DB::Object::Metadata::Column-derived column object and a column type
           name, return the corresponding method name that should be used for it.  Several
           entities are given an opportunity to determine the name.  They are consulted in the
           following order.

           1. If a custom-defined column_name_to_method_name_mapper exists, then it is used to
           generate the method name and this name is returned.
           2. If a method name has been explicitly set, for this type in the column object
           itself, then this name is returned.
           3. If the convention manager's auto_column_method_name method returns a defined value,
           then this name is returned.
           4. Otherwise, the default naming rules as defined in the column class itself are used.
       method_name_is_reserved NAME, CLASS
           Given the method name NAME and the class name CLASS, returns true if the method name
           is reserved (i.e., is used by the CLASS API), false otherwise.

       nonpersistent_column NAME [, COLUMN | HASHREF]
           This method behaves like the column method, except that it works with non-persistent
           columns.  See the documentation for the nonpersistent_columns method for more
           information on non-persistent columns.

       nonpersistent_columns [ARGS]
           Get or set the full list of non-persistent columns.  If ARGS are passed, the non-
           persistent column list is cleared and then ARGS are passed to the
           add_nonpersistent_columns method.

           Returns a list of non-persistent column objects in list context, or a reference to an
           array of non-persistent column objects in scalar context.

           Non-persistent columns allow the creation of object attributes and associated
           accessor/mutator methods exactly like those associated with columns, but without ever
           sending any of these attributes to (or pulling any these attributes from) the
           database.

           Non-persistent columns are tracked entirely separately from columns.  Adding,
           deleting, and listing non-persistent columns has no affect on the list of normal
           (i.e., "persistent") columns.

           You cannot query the database (e.g., using Rose::DB::Object::Manager) and filter on a
           non-persistent column; non-persistent columns do not exist in the database.  This
           feature exists solely to leverage the method creation abilities of the various column
           classes.

       nonpersistent_column_accessor_method_name NAME
           Returns the name of the "get" method for the non-persistent column named NAME.  This
           is just a shortcut for "$meta->nonpersistent_column(NAME)->accessor_method_name".

       nonpersistent_column_accessor_method_names
           Returns a list (in list context) or a reference to the array (in scalar context) of
           the names of the "set" methods for all the non-persistent columns, in the order that
           the columns are returned by nonpersistent_column_names.

       nonpersistent_column_mutator_method_name NAME
           Returns the name of the "set" method for the non-persistent column named NAME.  This
           is just a shortcut for "$meta->nonpersistent_column(NAME)->mutator_method_name".

       nonpersistent_column_mutator_method_names
           Returns a list (in list context) or a reference to the array (in scalar context) of
           the names of the "set" methods for all the non-persistent columns, in the order that
           the columns are returned by nonpersistent_column_names.

       nonpersistent_column_names
           Returns a list (in list context) or a reference to an array (in scalar context) of
           non-persistent column names.

       pk_columns [COLUMNS]
           This is an alias for the primary_key_columns method.

       post_init_hook [ CODEREF | ARRAYREF ]
           Get or set a reference to a subroutine or a reference to an array of code references
           that will be called just after the initialize method runs.  Each referenced subroutine
           will be passed the metadata object itself and any arguments passed to the call to
           initialize.

       pre_init_hook [ CODEREF | ARRAYREF ]
           Get or set a reference to a subroutine or a reference to an array of code references
           that will be called just before the initialize method runs.  Each referenced
           subroutine will be passed the metadata object itself and any arguments passed to the
           call to initialize.

       primary_key [PK]
           Get or set the Rose::DB::Object::Metadata::PrimaryKey object that stores the list of
           column names that make up the primary key for this table.

       primary_key_columns [COLUMNS]
           Get or set the list of columns that make up the primary key.  COLUMNS should be a list
           of column names or Rose::DB::Object::Metadata::Column-derived objects.

           Returns all of the columns that make up the primary key.  Each column is a
           Rose::DB::Object::Metadata::Column-derived column object if a column object with the
           same name exists, or just the column name otherwise.  In scalar context, a reference
           to an array of columns is returned.  In list context, a list is returned.

           This method is just a shortcut for the code:

               $meta->primary_key->columns(...);

           See the primary_key method and the Rose::DB::Object::Metadata::PrimaryKey class for
           more information.

       primary_key_column_names [NAMES]
           Get or set the names of the columns that make up the table's primary key.  NAMES
           should be a list or reference to an array of column names.

           Returns the list of column names (in list context) or a reference to the array of
           column names (in scalar context).

           This method is just a shortcut for the code:

               $meta->primary_key->column_names(...);

           See the primary_key method and the Rose::DB::Object::Metadata::PrimaryKey class for
           more information.

       primary_key_generator [CODEREF]
           Get or set the subroutine used to generate new primary key values for the primary key
           columns of this table.  The subroutine will be passed two arguments: the current
           metadata object and the Rose::DB-derived object that points to the current database.

           The subroutine is expected to return a list of values, one for each primary key
           column.  The values must be in the same order as the corresponding columns returned by
           primary_key_columns. (i.e., the first value belongs to the first column returned by
           primary_key_columns, the second value belongs to the second column, and so on.)

       primary_key_sequence_names [NAMES]
           Get or set the list of database sequence names used to populate the primary key
           columns.  The sequence names must be in the same order as the primary_key_columns.
           NAMES may be a list or reference to an array of sequence names.  Returns a list (in
           list context) or reference to the array (in scalar context) of sequence names.

           If you do not set this value, it will be derived for you based on the name of the
           primary key columns.  In the common case, you do not need to be concerned about this
           method.  If you are using the built-in SERIAL or AUTO_INCREMENT types in your database
           for your primary key columns, everything should just work.

       prime_caches [PARAMS]
           By default, secondary metadata derived from the attributes of this object is created
           and cached on demand.  Call this method to pre-cache this metadata all at once.  This
           method is useful when running in an environment like mod_perl where it's advantageous
           to load as much data as possible on start-up.

           PARAMS are name/value pairs.  Valid parameters are:

           db DB
               A Rose::DB-derived object used to determine which data source the cached metadata
               will be generated on behalf of.  (Each data source has its own set of cached
               metadata.)  This parameter is optional.  If it is not passed, then the
               Rose::DB-derived object returned by the init_db method for this class will be used
               instead.

       relationship NAME [, RELATIONSHIP | HASHREF]
           Get or set the relationship named NAME.  If just NAME is passed, the
           Rose::DB::Object::Metadata::Relationship-derived relationship object for that NAME is
           returned.  If no such relationship exists, undef is returned.

           If both NAME and RELATIONSHIP are passed, then RELATIONSHIP must be a
           Rose::DB::Object::Metadata::Relationship-derived object.  RELATIONSHIP has its name
           set to NAME, and is then stored as the relationship metadata object for NAME,
           replacing any existing relationship.

           If both NAME and HASHREF are passed, then the combination of NAME and HASHREF must
           form a name/value pair suitable for passing to the add_relationships method.  The new
           relationship specified by NAME and HASHREF replaces any existing relationship.

       relationships [ARGS]
           Get or set the full list of relationships.  If ARGS are passed, the relationship list
           is cleared and then ARGS are passed to the add_relationships method.

           Returns a list of relationship objects in list context, or a reference to an array of
           relationship objects in scalar context.

       replace_column NAME, [COLUMN | HASHREF]
           Replace the column named NAME with a newly constructed column.  This method is
           equivalent to deleting any existing column named NAME and then adding a new one.  In
           other words, this:

               $meta->replace_column($name => $value);

           is equivalent to this:

               $meta->delete_column($name);
               $meta->add_column($name => $value);

           The value of the new column may be a Rose::DB::Object::Metadata::Column-derived object
           or a reference to a hash suitable for passing to the add_columns method.

       schema [SCHEMA]
           Get or set the database schema for this class.  This setting will override any setting
           in the db object.  Use this method only if you know that the class will always point
           to a specific schema, regardless of what the Rose::DB-derived database handle object
           specifies.

       setup PARAMS
           Set up all the metadata for this class in a single method call.  This method is a
           convenient shortcut.  It does its work by delegating to other methods.

           The setup() method does nothing if the metadata object is already initialized
           (according to the is_initialized method).

           PARAMS are method/arguments pairs.  In general, the following transformations apply.

           Given a method/arrayref pair:

               METHOD => [ ARG1, ARG2 ]

           The arguments will be removed from their array reference and passed to METHOD like
           this:

               $meta->METHOD(ARG1, ARG2);

           Given a method/value pair:

               METHOD => ARG

           The argument will be passed to METHOD as-is:

               $meta->METHOD(ARG);

           There are two exceptions to these transformation rules.

           If METHOD is "unique_key" or "add_unique_key" and the argument is a reference to an
           array containing only non-reference values, then the array reference itself is passed
           to the method.  For example, this pair:

               unique_key => [ 'name', 'status' ]

           will result in this method call:

               $meta->unique_key([ 'name', 'status' ]);

           (Note that these method names are singular.  This exception does not apply to the
           plural variants, "unique_keys" and "add_unique_keys".)

           If METHOD is "helpers", then the argument is dereferenced (if it's an array reference)
           and passed on to Rose::DB::Object::Helpers.  That is, this:

               helpers => [ 'load_or_save', { load_or_insert => 'find_or_create' } ],

           Is equivalent to having this in your class:

               use Rose::DB::Object::Helpers
                 'load_or_save', { load_or_insert => 'find_or_create' };

           Method names may appear more than once in PARAMS.  The methods are called in the order
           that they appear in PARAMS, with the exception of the initialize (or auto_initialize)
           method, which is always called last.

           If "initialize" is not one of the method names, then it will be called automatically
           (with no arguments) at the end.  If you do not want to pass any arguments to the
           initialize method, standard practice is to omit it.

           If "auto_initialize" is one of the method names, then the  auto_initialize method will
           be called instead of the initialize method.  This is useful if you want to manually
           set up a few pieces of metadata, but want the auto-initialization system to set up the
           rest.

           The name "auto" is considered equivalent to "auto_initialize", but any arguments are
           ignored unless they are encapsulated in a reference to an array.  For example, these
           are equivalent:

               $meta->setup(
                 table => 'mytable',
                 # Call auto_initialize() with no arguments
                 auto_initialize => [],
               );

               # This is another way of writing the same thing as the above
               $meta->setup(
                 table => 'mytable',
                 # The value "1" is ignored because it's not an arrayref,
                 # so auto_initialize() will be called with no arguments.
                 auto => 1,
               );

           Finally, here's a full example of a setup() method call followed by the equivalent
           "long-hand" implementation.

               $meta->setup
               (
                 table => 'colors',

                 columns =>
                 [
                   code => { type => 'character', length => 3, not_null => 1 },
                   name => { type => 'varchar', length => 255 },
                 ],

                 primary_key_columns => [ 'code' ],

                 unique_key => [ 'name' ],
               );

           The setup() method call above is equivalent to the following code:

               unless($meta->is_initialized)
               {
                 $meta->table('colors');

                 $meta->columns(
                 [
                   code => { type => 'character', length => 3, not_null => 1 },
                   name => { type => 'varchar', length => 255 },
                 ]);

                 $meta->primary_key_columns('code');

                 $meta->unique_key([ 'name' ]),

                 $meta->initialize;
               }

       sql_qualify_column_names_on_load [BOOL]
           Get or set a boolean value that indicates whether or not to prefix the columns with
           the table name in the SQL used to load() an object.  The default value is false.

           For example, here is some SQL that might be used to load an object, as generated with
           sql_qualify_column_names_on_load set to false:

               SELECT id, name FROM dogs WHERE id = 5;

           Now here's how it would look with sql_qualify_column_names_on_load set to true:

               SELECT dogs.id, dogs.name FROM dogs WHERE dogs.id = 5;

       table [TABLE]
           Get or set the name of the database table.  The table name should not include any sort
           of prefix to indicate the schema or catalog.

       unique_key KEY
           This method is an alias for add_unique_keys.

       unique_keys KEYS
           Get or set the list of unique keys for this table.  If KEYS is passed, any existing
           keys will be deleted and KEYS will be passed to the add_unique_keys method.

           Returns the list (in list context) or reference to an array (in scalar context) of
           Rose::DB::Object::Metadata::UniqueKey objects.

       unique_key_by_name NAME
           Return the unique key named NAME, or undef if no such key exists.

       unique_keys_column_names
           Returns a list (in list context) or a reference to an array (in scalar context) or
           references to arrays of the column names that make up each unique key.  That is:

               # Example of a scalar context return value
               [ [ 'id', 'name' ], [ 'code' ] ]

               # Example of a list context return value
               ([ 'id', 'name' ], [ 'code' ])

AUTO-INITIALIZATION METHODS

       These methods are associated with the auto-initialization process.  Calling any of them
       will cause the auto-initialization code to be loaded, which costs memory.  This should be
       considered an implementation detail for now.

       Regardless of the implementation details, you should still avoid calling any of these
       methods unless you plan to do some auto-initialization.  No matter how generic they may
       seem (e.g., default_perl_indent), rest assured that none of these methods are remotely
       useful unless you are doing auto-initialization.

   CLASS METHODS
       default_perl_braces [STYLE]
           Get or set the default brace style used in the Perl code generated by the perl_*
           object methods.  STYLE must be either "k&r" or "bsd".  The default value is "k&r".

       default_perl_indent [INT]
           Get or set the default integer number of spaces used for each level of indenting in
           the Perl code generated by the perl_* object methods.  The default value is 4.

       default_perl_unique_key_style [STYLE]
           Get or set the default style of the unique key initialization used in the Perl code
           generated by the perl_unique_keys_definition method.  STYLE must be "array" or
           "object".  The default value is "array".  See the perl_unique_keys_definition method
           for examples of the two styles.

   OBJECT METHODS
       auto_generate_columns
           Auto-generate Rose::DB::Object::Metadata::Column-derived objects for each column in
           the table.  Note that this method does not modify the metadata object's list of
           columns.  It simply returns a list of column objects.    Calling this method in void
           context will cause a fatal error.

           Returns a list of column objects (in list context) or a reference to a hash of column
           objects, keyed by column name (in scalar context).  The hash reference return value is
           intended to allow easy modification of the auto-generated column objects.  Example:

               $columns = $meta->auto_generate_columns; # hash ref return value

               # Make some changes
               $columns->{'name'}->length(10); # set different length
               $columns->{'age'}->default(5);  # set different default
               ...

               # Finally, set the column list
               $meta->columns(values %$columns);

           If you do not want to modify the auto-generated columns, you should use the
           auto_init_columns method instead.

           A fatal error will occur unless at least one column was auto-generated.

       auto_generate_foreign_keys [PARAMS]
           Auto-generate Rose::DB::Object::Metadata::ForeignKey objects for each foreign key in
           the table.  Note that this method does not modify the metadata object's list of
           foreign_keys.  It simply returns a list of foreign key objects.  Calling this method
           in void context will cause a fatal error.  A warning will be issued if a foreign key
           could not be generated because no Rose::DB::Object-derived class was found for the
           foreign table.

           PARAMS are optional name/value pairs.  If a "no_warnings" parameter is passed with a
           true value, then the warning described above will not be issued.

           Returns a list of foreign key objects (in list context) or a reference to an array of
           foreign key objects (in scalar context).

           If you do not want to inspect or modify the auto-generated foreign keys, but just want
           them to populate the metadata object's foreign_keys list, you should use the
           auto_init_foreign_keys method instead.

           Note: This method works with MySQL only when using the InnoDB storage type.

       auto_generate_unique_keys
           Auto-generate Rose::DB::Object::Metadata::UniqueKey objects for each unique key in the
           table.  Note that this method does not modify the metadata object's list of
           unique_keys.  It simply returns a list of unique key objects.  Calling this method in
           void context will cause a fatal error.

           Returns a list of unique key objects (in list context) or a reference to an array of
           unique key objects (in scalar context).

           If you do not want to inspect or modify the auto-generated unique keys, but just want
           them to populate the metadata object's unique_keys list, you should use the
           auto_init_unique_keys method instead.

       auto_retrieve_primary_key_column_names
           Returns a list (in list context) or a reference to an array (in scalar context) of the
           names of the columns that make up the primary key for this table.  Note that this
           method does not modify the metadata object's primary_key.  It simply returns a list of
           column names.  Calling this method in void context will cause a fatal error.

           This method is rarely called explicitly.  Usually, you will use the
           auto_init_primary_key_columns method instead.

           A fatal error will occur unless at least one column name can be retrieved.

           (This method uses the word "retrieve" instead of "generate" like its sibling methods
           above because it does not generate objects; it simply returns column names.)

       auto_initialize [PARAMS]
           Auto-initialize the entire metadata object.  This is a wrapper for the individual
           "auto_init_*" methods, and is roughly equivalent to this:

             $meta->auto_init_columns(...);
             $meta->auto_init_primary_key_columns;
             $meta->auto_init_unique_keys(...);
             $meta->auto_init_foreign_keys(...);
             $meta->auto_init_relationships(...);
             $meta->initialize;

           PARAMS are optional name/value pairs.  When applicable, these parameters are passed on
           to each of the "auto_init_*" methods.  Valid parameters are:

           include_map_class_relationships BOOL
               By default, if a class is a map class (according to the is_map_class method of the
               convention manager), then relationships directly between that class and the
               current class will not be created.  Set this parameter to true to allow such
               relationships to be created.

               Note: If some classes that are not actually map classes are being skipped, you
               should not use this parameter to force them to be included.  It's more appropriate
               to make your own custom convention manager subclass and then override the
               is_map_class method to make the correct determination.

           replace_existing BOOL
               If true, then the auto-generated columns, unique keys, foreign keys, and
               relationships entirely replace any existing columns, unique keys, foreign keys,
               and relationships, respectively.

           stay_connected BOOL
               If true, then any database connections retained by the metadata objects belonging
               to the various Rose::DB::Object-derived classes participating in the auto-
               initialization process will remain connected until an explicit call to the
               clear_all_dbs class method.

           with_foreign_keys BOOL
               A boolean value indicating whether or not foreign key metadata will be auto-
               initialized.  Defaults to true.

           with_relationships [ BOOL | ARRAYREF ]
               A boolean value or a reference to an array of relationship type names.  If set to
               a simple boolean value, then the all types of relationships will be considered for
               auto-initialization.  If set to a list of relationship type names, then only
               relationships of those types will be considered.  Defaults to true.

           with_unique_keys BOOL
               A boolean value indicating whether or not unique key metadata will be auto-
               initialized.  Defaults to true.

           During initialization, if one of the columns has a method name that clashes with a
           reserved method name, then the column_alias_generator will be called to remedy the
           situation by aliasing the column.  If the name still conflicts, then a fatal error
           will occur.

           A fatal error will occur if auto-initialization fails.

       auto_init_columns [PARAMS]
           Auto-generate Rose::DB::Object::Metadata::Column objects for this table, then populate
           the list of columns.  PARAMS are optional name/value pairs.  If a "replace_existing"
           parameter is passed with a true value, then the auto-generated columns replace any
           existing columns.  Otherwise, any existing columns are left as-is.

       auto_init_foreign_keys [PARAMS]
           Auto-generate Rose::DB::Object::Metadata::ForeignKey objects for this table, then
           populate the list of foreign_keys.  PARAMS are optional name/value pairs.  If a
           "replace_existing" parameter is passed with a true value, then the auto-generated
           foreign keys replace any existing foreign keys.  Otherwise, any existing foreign keys
           are left as-is.

           Note: This method works with MySQL only when using the InnoDB storage type.

       auto_init_primary_key_columns
           Auto-retrieve the names of the columns that make up the primary key for this table,
           then populate the list of primary_key_column_names.  A fatal error will occur unless
           at least one primary key column name could be retrieved.

       auto_init_relationships [PARAMS]
           Auto-populate the list of relationships for this class.  PARAMS are optional
           name/value pairs.

           include_map_class_relationships BOOL
               By default, if a class is a map class (according to the is_map_class method of the
               convention manager), then relationships directly between that class and the
               current class will not be created.  Set this parameter to true to allow such
               relationships to be created.

               Note: If some classes that are not actually map classes are being skipped, you
               should not use this parameter to force them to be included.  It's more appropriate
               to make your own custom convention manager subclass and then override the
               is_map_class method to make the correct determination.

           replace_existing BOOL
               If true, then the auto-generated relationships replace any existing relationships.
               Otherwise, any existing relationships are left as-is.

           relationship_types ARRAYREF
               A reference to an array of relationship type names.  Only relationships of these
               types will be created.  If omitted, relationships of all types will be created.
               If passed a reference to an empty array, no relationships will be created.

           types ARRAYREF
               This is an alias for the "relationship_types" parameter.

           with_relationships [ BOOL | ARRAYREF ]
               This is the same as the "relationship_types" parameter except that it also accepts
               a boolean value.  If true, then relationships of all types will be created.  If
               false, then none will be created.

           Assume that this class is called "Local" and any hypothetical foreign class is called
           "Remote".  Relationships are auto-generated according to the following rules.

           ·   A one-to-many relationship is created between "Local" and "Remote" if "Remote" has
               a foreign key that points to "Local".  This is not done, however, if "Local" has a
               one-to-one relationship pointing to "Remote" that references the same columns as
               the foreign key in "Remote" that points to "Local", or if "Local" is a map class
               (according to the convention manager's is_map_class method).  The relationship
               name is generated by the convention manager's auto_relationship_name_one_to_many
               method.

           ·   A many-to-many relationship is created between "Local" and "Remote" if there
               exists a map class (according to the convention manager's is_map_class method)
               with exactly two foreign keys, one pointing to Local and on pointing to "Remote".
               The relationship name is generated by creating a plural version of the name of the
               foreign key in the map class that points to "Remote".

           In all cases, if there is an existing, semantically identical relationship, then a new
           relationship is not auto-generated.  Similarly, any existing methods with the same
           names are not overridden by methods associated with auto-generated relationships.

       auto_init_unique_keys [PARAMS]
           Auto-generate Rose::DB::Object::Metadata::UniqueKey objects for this table, then
           populate the list of unique_keys.  PARAMS are name/value pairs.  If a
           "replace_existing" parameter is passed with a true value, then the auto-generated
           unique keys replace any existing unique keys.  Otherwise, any existing unique keys are
           left as-is.

       column_alias_generator [CODEREF]
           Get or set the code reference to the subroutine used to alias columns have, or would
           generate, one or more method names that clash with reserved method names.

           The subroutine should take two arguments: the metadata object and the column name.
           The $_ variable will also be set to the column name at the time of the call.  The
           subroutine should return an alias for the column.

           The default column alias generator simply appends the string "_col" to the end of the
           column name and returns that as the alias.

       foreign_key_name_generator [CODEREF]
           Get or set the code reference to the subroutine used to generate foreign key names.
           Note: This code will only be called if the convention_manager's auto_foreign_key_name
           method fails to (or declines to) produce a defined foreign key name.

           The subroutine should take two arguments: a metadata object and a
           Rose::DB::Object::Metadata::ForeignKey object.  It should return a name for the
           foreign key.

           Each foreign key must have a name that is unique within the class.  By default, this
           name will also be the name of the method generated to access the object referred to by
           the foreign key, so it must be unique among method names in the class as well.

           The default foreign key name generator uses the following algorithm:

           If the foreign key has only one column, and if the name of that column ends with an
           underscore and the name of the referenced column, then that part of the column name is
           removed and the remaining string is used as the foreign key name.  For example, given
           the following tables:

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

               CREATE TABLE products
               (
                 category_id  INT REFERENCES categories (id),
                 ...
               );

           The foreign key name would be "category", which is the name of the referring column
           ("category_id") with an underscore and the name of the referenced column ("_id")
           removed from the end of it.

           If the foreign key has only one column, but it does not meet the criteria described
           above, then "_object" is appended to the name of the referring column and the
           resulting string is used as the foreign key name.

           If the foreign key has more than one column, then the foreign key name is generated by
           replacing double colons and case-transitions in the referenced class name with
           underscores, and then converting to lowercase.  For example, if the referenced table
           is fronted by the class My::TableOfStuff, then the generated foreign key name would be
           "my_table_of_stuff".

           In all of the scenarios above, if the generated foreign key name is still not unique
           within the class, then a number is appended to the end of the name.  That number is
           incremented until the name is unique.

           In practice, rather than setting a custom foreign key name generator, it's usually
           easier to simply set the foreign key name(s) manually after auto-initializing the
           foreign keys (but before calling initialize or auto_initialize, of course).

       perl_class_definition [PARAMS]
           Auto-initialize the columns, primary key, foreign keys, and unique keys, then return
           the Perl source code for a complete Rose::DB::Object-derived class definition.  PARAMS
           are optional name/value pairs that may include the following:

           braces STYLE
               The brace style to use in the generated Perl code.  STYLE must be either "k&r" or
               "bsd".  The default value is determined by the return value of the
               default_perl_braces class method.

           indent INT
               The integer number of spaces to use for each level of indenting in the generated
               Perl code.  The default value is determined by the return value of the
               default_perl_indent class method.

           isa CLASSES
               The list of base classes to use in the generated class definition.  CLASSES should
               be a single class name, or a reference to an array of class names.  The default
               base class is Rose::DB::Object.

           use_setup BOOL
               If true, then the generated class definition will include a call to the setup
               method.  Otherwise, the generated code will contain individual methods calls.  The
               default value for this parameter is true; the setup method is the recommended way
               to initialize a class.

           This method is simply a wrapper (with some glue) for the following methods:
           perl_columns_definition, perl_primary_key_columns_definition,
           perl_unique_keys_definition,  perl_foreign_keys_definition, and
           perl_relationships_definition.  The "braces" and "indent" parameters are passed on to
           these other methods.

           Here's a complete example, which also serves as an example of the individual "perl_*"
           methods that this method wraps.  First, the table definitions.

               CREATE TABLE topics
               (
                 id    SERIAL PRIMARY KEY,
                 name  VARCHAR(32)
               );

               CREATE TABLE codes
               (
                 k1    INT NOT NULL,
                 k2    INT NOT NULL,
                 k3    INT NOT NULL,
                 name  VARCHAR(32),

                 PRIMARY KEY(k1, k2, k3)
               );

               CREATE TABLE products
               (
                 id             SERIAL PRIMARY KEY,
                 name           VARCHAR(32) NOT NULL,
                 flag           BOOLEAN NOT NULL DEFAULT 't',
                 status         VARCHAR(32) DEFAULT 'active',
                 topic_id       INT REFERENCES topics (id),
                 fk1            INT,
                 fk2            INT,
                 fk3            INT,
                 last_modified  TIMESTAMP,
                 date_created   TIMESTAMP,

                 FOREIGN KEY (fk1, fk2, fk3) REFERENCES codes (k1, k2, k3)
               );

               CREATE TABLE prices
               (
                 id          SERIAL PRIMARY KEY,
                 product_id  INT REFERENCES products (id),
                 price       DECIMAL(10,2) NOT NULL DEFAULT 0.00,
                 region      CHAR(2) NOT NULL DEFAULT 'US'
               );

           First we'll auto-initialize the classes.

               package Code;
               use base qw(Rose::DB::Object);
               __PACKAGE__->meta->auto_initialize;

               package Category;
               use base qw(Rose::DB::Object);
               # Explicit table name required because the class name
               # does not match up with the table name in this case.
               __PACKAGE__->meta->table('topics');
               __PACKAGE__->meta->auto_initialize;

               package Product;
               use base qw(Rose::DB::Object);
               __PACKAGE__->meta->auto_initialize;

               package Price;
               use base qw(Rose::DB::Object);
               __PACKAGE__->meta->auto_initialize;

           Now we'll print the "Product" class definition;

               print Product->meta->perl_class_definition(braces => 'bsd',
                                                          indent => 2);

           The output looks like this:

             package Product;

             use strict;

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

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

               columns =>
               [
                 id            => { type => 'integer', not_null => 1 },
                 name          => { type => 'varchar', length => 32, not_null => 1 },
                 flag          => { type => 'boolean', default => 'true', not_null => 1 },
                 status        => { type => 'varchar', default => 'active', length => 32 },
                 topic_id      => { type => 'integer' },
                 fk1           => { type => 'integer' },
                 fk2           => { type => 'integer' },
                 fk3           => { type => 'integer' },
                 last_modified => { type => 'timestamp' },
                 date_created  => { type => 'timestamp' },
               ],

               primary_key_columns => [ 'id' ],

               foreign_keys =>
               [
                 code =>
                 {
                   class => 'Code',
                   key_columns =>
                   {
                     fk1 => 'k1',
                     fk2 => 'k2',
                     fk3 => 'k3',
                   },
                 },

                 topic =>
                 {
                   class => 'Category',
                   key_columns =>
                   {
                     topic_id => 'id',
                   },
                 },
               ],

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

             1;

           Here's the output when the "use_setup" parameter is explicitly set to false.

               print Product->meta->perl_class_definition(braces    => 'bsd',
                                                          indent    => 2,
                                                          use_setup => 0);

           Note that this approach is not recommended, but exists for historical reasons.

             package Product;

             use strict;

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

             __PACKAGE__->meta->table('products');

             __PACKAGE__->meta->columns
             (
               id            => { type => 'integer', not_null => 1 },
               name          => { type => 'varchar', length => 32, not_null => 1 },
               flag          => { type => 'boolean', default => 'true', not_null => 1 },
               status        => { type => 'varchar', default => 'active', length => 32 },
               topic_id      => { type => 'integer' },
               fk1           => { type => 'integer' },
               fk2           => { type => 'integer' },
               fk3           => { type => 'integer' },
               last_modified => { type => 'timestamp' },
               date_created  => { type => 'timestamp' },
             );

             __PACKAGE__->meta->primary_key_columns([ 'id' ]);

             __PACKAGE__->meta->foreign_keys
             (
               code =>
               {
                 class => 'Code',
                 key_columns =>
                 {
                   fk1 => 'k1',
                   fk2 => 'k2',
                   fk3 => 'k3',
                 },
               },

               topic =>
               {
                 class => 'Category',
                 key_columns =>
                 {
                   topic_id => 'id',
                 },
               },
             );

             __PACKAGE__->meta->relationships
             (
               prices =>
               {
                 class       => 'Price',
                 key_columns => { id => 'product_id' },
                 type        => 'one to many',
               },
             );

             __PACKAGE__->meta->initialize;

             1;

           See the auto-initialization section for more discussion of Perl code generation.

       perl_columns_definition [PARAMS]
           Auto-initialize the columns (if necessary), then return the Perl source code that is
           equivalent to the auto-initialization.  PARAMS are optional name/value pairs that may
           include the following:

           braces STYLE
               The brace style to use in the generated Perl code.  STYLE must be either "k&r" or
               "bsd".  The default value is determined by the return value of the
               default_perl_braces class method.

           for_setup BOOL
               If true, then the generated Perl code will be a method/arguments pair suitable for
               use as a parameter to setup method.  The default is false.

           indent INT
               The integer number of spaces to use for each level of indenting in the generated
               Perl code.  The default value is determined by the return value of the
               default_perl_indent class method.

           To see examples of the generated code, look in the documentation for the
           perl_class_definition method.

       perl_foreign_keys_definition [PARAMS]
           Auto-initialize the foreign keys (if necessary), then return the Perl source code that
           is equivalent to the auto-initialization.  PARAMS are optional name/value pairs that
           may include the following:

           braces STYLE
               The brace style to use in the generated Perl code.  STYLE must be either "k&r" or
               "bsd".  The default value is determined by the return value of the
               default_perl_braces class method.

           for_setup BOOL
               If true, then the generated Perl code will be a method/arguments pair suitable for
               use as a parameter to setup method.  The default is false.

           indent INT
               The integer number of spaces to use for each level of indenting in the generated
               Perl code.  The default value is determined by the return value of the
               default_perl_indent class method.

           To see examples of the generated code, look in the documentation for the
           perl_class_definition method.

       perl_manager_class [ PARAMS | BASE_NAME ]
           Returns a Perl class definition for a Rose::DB::Object::Manager-derived class to
           manage objects of this class.  If a single string is passed, it is taken as the value
           of the "base_name" parameter.  PARAMS are optional name/value pairs that may include
           the following:

           base_name NAME
               The value of the base_name parameter that will be passed to the call to
               Rose::DB::Object::Manager's make_manager_methods method.  Defaults to the return
               value of the convention manager's auto_manager_base_name method.

           class CLASS
               The name of the manager class.  Defaults to the return value of the convention
               manager's auto_manager_class_name method.

           isa [ LIST | ARRAYREF ]
               The name of a single class or a reference to an array of class names to be
               included in the @ISA array for the manager class.  One of these classes must
               inherit from Rose::DB::Object::Manager.  Defaults to the return value of the
               "default_manager_base_class()" object method.

           For example, given this class:

               package Product;

               use Rose::DB::Object;
               our @ISA = qw(Rose::DB::Object);
               ...

               print Product->meta->perl_manager_class(
                                      class     => 'Prod::Mgr',
                                      base_name => 'prod');

           The following would be printed:

               package Prod::Mgr;

               use Rose::DB::Object::Manager;
               our @ISA = qw(Rose::DB::Object::Manager);

               sub object_class { 'Product' }

               __PACKAGE__->make_manager_methods('prod');

               1;

       perl_primary_key_columns_definition
           Auto-initialize the primary key column names (if necessary), then return the Perl
           source code that is equivalent to the auto-initialization.

           See the larger example in the documentation for the perl_class_definition method to
           see what the generated Perl code looks like.

       perl_relationships_definition [PARAMS]
           Auto-initialize the relationships (if necessary), then return the Perl source code
           that is equivalent to the auto-initialization.  PARAMS are optional name/value pairs
           that may include the following:

           braces STYLE
               The brace style to use in the generated Perl code.  STYLE must be either "k&r" or
               "bsd".  The default value is determined by the return value of the
               default_perl_braces class method.

           for_setup BOOL
               If true, then the generated Perl code will be a method/arguments pair suitable for
               use as a parameter to setup method.  The default is false.

           indent INT
               The integer number of spaces to use for each level of indenting in the generated
               Perl code.  The default value is determined by the return value of the
               default_perl_indent class method.

           To see examples of the generated code, look in the documentation for the
           perl_class_definition method.

       perl_table_definition [PARAMS]
           Auto-initialize the table name (if necessary), then return the Perl source code that
           is equivalent to the auto-initialization.  PARAMS are optional name/value pairs that
           may include the following:

           braces STYLE
               The brace style to use in the generated Perl code.  STYLE must be either "k&r" or
               "bsd".  The default value is determined by the return value of the
               default_perl_braces class method.

           for_setup BOOL
               If true, then the generated Perl code will be a method/arguments pair suitable for
               use as a parameter to setup method.  The default is false.

           indent INT
               The integer number of spaces to use for each level of indenting in the generated
               Perl code.  The default value is determined by the return value of the
               default_perl_indent class method.

           To see examples of the generated code, look in the documentation for the
           perl_class_definition method.

       perl_unique_keys_definition [PARAMS]
           Auto-initialize the unique keys, then return the Perl source code that is equivalent
           to the auto-initialization.  PARAMS are optional name/value pairs that may include the
           following:

           braces STYLE
               The brace style to use in the generated Perl code.  STYLE must be either "k&r" or
               "bsd".  The default value is determined by the return value of the
               default_perl_braces class method.

           for_setup BOOL
               If true, then the generated Perl code will be a method/arguments pair suitable for
               use as a parameter to setup method.  The default is false.

           indent INT
               The integer number of spaces to use for each level of indenting in the generated
               Perl code.  The default value is determined by the return value of the
               default_perl_indent class method.

           style STYLE
               Determines the style the initialization used in the generated Perl code.  STYLE
               must be "array" or "object".  The default is determined by the return value of the
               class method default_perl_unique_key_style.

               The "array" style passes references to arrays of column names:

                 __PACKAGE__->meta->unique_keys
                 (
                   [ 'id', 'name' ],
                   [ 'flag', 'status' ],
                 );

               The "object" style sets unique keys using calls to the
               Rose::DB::Object::Metadata::UniqueKey constructor:

                 __PACKAGE__->meta->unique_keys
                 (
                   Rose::DB::Object::Metadata::UniqueKey->new(
                     name    => 'products_id_key',
                     columns => [ 'id', 'name' ]),

                   Rose::DB::Object::Metadata::UniqueKey->new(
                     name    => 'products_flag_key',
                     columns => [ 'flag', 'status' ]),
                 );

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.