1Rose::DB::Object::MetadUastear(3C)ontributed Perl DocumeRnotsaet:i:oDnB::Object::Metadata(3)
2
3
4

NAME

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

SYNOPSIS

9         use Rose::DB::Object::Metadata;
10
11         $meta = Rose::DB::Object::Metadata->new(class => 'Product');
12         # ...or...
13         $meta = Rose::DB::Object::Metadata->for_class('Product');
14
15         #
16         # Auto-initialization
17         #
18
19         $meta->table('products'); # optional if class name ends with "::Product"
20         $meta->auto_initialize;
21
22         #
23         # ...or manual setup
24         #
25
26         $meta->setup
27         (
28           table => 'products',
29
30           columns =>
31           [
32             id          => { type => 'int', primary_key => 1 },
33             name        => { type => 'varchar', length => 255 },
34             description => { type => 'text' },
35             category_id => { type => 'int' },
36
37             status =>
38             {
39               type      => 'varchar',
40               check_in  => [ 'active', 'inactive' ],
41               default   => 'inactive',
42             },
43
44             start_date  => { type => 'datetime' },
45             end_date    => { type => 'datetime' },
46
47             date_created  => { type => 'timestamp', default => 'now' },
48             last_modified => { type => 'timestamp', default => 'now' },
49           ],
50
51           unique_key => 'name',
52
53           foreign_keys =>
54           [
55             category =>
56             {
57               class       => 'Category',
58               key_columns =>
59               {
60                 category_id => 'id',
61               }
62             },
63           ],
64
65           relationships =>
66           [
67             prices =>
68             {
69               type       => 'one to many',
70               class      => 'Price',
71               column_map => { id => 'id_product' },
72             },
73           ],
74         );
75
76         #
77         # ...or even more verbose manual setup (old-style, not recommended)
78         #
79
80         $meta->table('products');
81
82         $meta->columns
83         (
84           id          => { type => 'int', primary_key => 1 },
85           name        => { type => 'varchar', length => 255 },
86           description => { type => 'text' },
87           category_id => { type => 'int' },
88
89           status =>
90           {
91             type      => 'varchar',
92             check_in  => [ 'active', 'inactive' ],
93             default   => 'inactive',
94           },
95
96           start_date  => { type => 'datetime' },
97           end_date    => { type => 'datetime' },
98
99           date_created  => { type => 'timestamp', default => 'now' },
100           last_modified => { type => 'timestamp', default => 'now' },
101         );
102
103         $meta->unique_key('name');
104
105         $meta->foreign_keys
106         (
107           category =>
108           {
109             class       => 'Category',
110             key_columns =>
111             {
112               category_id => 'id',
113             }
114           },
115         );
116
117         $meta->relationships
118         (
119           prices =>
120           {
121             type       => 'one to many',
122             class      => 'Price',
123             column_map => { id => 'id_product' },
124           },
125         );
126
127         ...
128

DESCRIPTION

130       Rose::DB::Object::Metadata objects store information about a single
131       table in a database: the name of the table, the names and types of
132       columns, any foreign or unique keys, etc.  These metadata objects are
133       also responsible for supplying information to, and creating object
134       methods for, the Rose::DB::Object-derived objects to which they belong.
135
136       Rose::DB::Object::Metadata objects also store information about the
137       Rose::DB::Objects that front the database tables they describe.  What
138       might normally be thought of as "class data" for the Rose::DB::Object
139       is stored in the metadata object instead, in order to keep the method
140       namespace of the Rose::DB::Object-derived class uncluttered.
141
142       Rose::DB::Object::Metadata objects are per-class singletons; there is
143       one Rose::DB::Object::Metadata object for each Rose::DB::Object-derived
144       class.  Metadata objects are almost never explicitly instantiated.
145       Rather, there are automatically created and accessed through
146       Rose::DB::Object-derived objects' meta method.
147
148       Once created, metadata objects can be populated manually or
149       automatically.  Both techniques are shown in the synopsis above.  The
150       automatic mode works by asking the database itself for the information.
151       There are some caveats to this approach.  See the auto-initialization
152       section for more information.
153
154       Rose::DB::Object::Metadata objects contain three categories of objects
155       that are responsible for creating object methods in
156       Rose::DB::Object-derived classes: columns, foreign keys, and
157       relationships.
158
159       Column objects are subclasses of Rose::DB::Object::Metadata::Column.
160       They are intended to store as much information as possible about each
161       column.  The particular class of the column object created for a
162       database column is determined by a mapping table.   The column class,
163       in turn, is responsible for creating the accessor/mutator method(s) for
164       the column.  When it creates these methods, the column class can use
165       (or ignore) any information stored in the column object.
166
167       Foreign key objects are of the class
168       Rose::DB::Object::Metadata::ForeignKey.  They store information about
169       columns that refer to columns in other tables that are fronted by their
170       own Rose::DB::Object-derived classes.  A foreign key object is
171       responsible for creating accessor method(s) to fetch the foreign object
172       from the foreign table.
173
174       Relationship objects are subclasses of
175       Rose::DB::Object::Metadata::Relationship.  They store information about
176       a table's relationship to other tables that are fronted by their own
177       Rose::DB::Object-derived classes.  The particular class of the
178       relationship object created for each relationship is determined by a
179       mapping table.   A relationship object is responsible for creating
180       accessor method(s) to fetch the foreign objects from the foreign table.
181

AUTO-INITIALIZATION

183       Manual population of metadata objects can be tedious and repetitive.
184       Nearly all of the information stored in a Rose::DB::Object::Metadata
185       object exists in the database in some form.  It's reasonable to
186       consider simply extracting this information from the database itself,
187       rather than entering it all manually.  This automatic metadata
188       extraction and subsequent Rose::DB::Object::Metadata object population
189       is called "auto-initialization."
190
191       The example of auto-initialization in the synopsis above is the most
192       succinct variant:
193
194           $meta->auto_initialize;
195
196       As you can read in the documentation for the auto_initialize method,
197       that's shorthand for individually auto-initializing each part of the
198       metadata object: columns, the primary key, unique keys, and foreign
199       keys.  But this brevity comes at a price.  There are many caveats to
200       auto-initialization.
201
202   Caveats
203       Start-Up Cost
204
205       In order to retrieve the information required for auto-initialization,
206       a database connection must be opened and queries must be run.
207       Sometimes these queries include complex joins.  All of these queries
208       must be successfully completed before the Rose::DB::Object-derived
209       objects that the Rose::DB::Object::Metadata is associated with can be
210       used.
211
212       In an environment like mod_perl, server start-up time is precisely when
213       you want to do any expensive operations.  But in a command-line script
214       or other short-lived process, the overhead of auto-initializing many
215       metadata objects may become prohibitive.
216
217       Also, don't forget that auto-initialization requires a database
218       connection.  Rose::DB::Object-derived objects can sometimes be useful
219       even without a database connection (e.g., to temporarily store
220       information that will never go into the database, or to synthesize data
221       using object methods that have no corresponding database column).  When
222       using auto-initialization, this is not possible because the
223       Rose::DB::Object-derived class won't even load if auto-initialization
224       fails because it could not connect to the database.
225
226       Detail
227
228       First, auto-initialization cannot generate information that exists only
229       in the mind of the programmer.  The most common example is a
230       relationship between two database tables that is either ambiguous or
231       totally unexpressed by the database itself.
232
233       For example, if a foreign key constraint does not exist, the
234       relationship between rows in two different tables cannot be extracted
235       from the database, and therefore cannot be auto-initialized.
236
237       Even within the realm of information that, by all rights, should be
238       available in the database, there are limitations.  Although there is a
239       handy DBI API for extracting metadata from databases, unfortunately,
240       very few DBI drivers support it fully.  Some don't support it at all.
241       In almost all cases, some manual work is required to (often painfully)
242       extract information from the database's "system tables" or "catalog."
243
244       More troublingly, databases do not always provide all the metadata that
245       a human could extract from the series of SQL statement that created the
246       table in the first place.  Sometimes, the information just isn't in the
247       database to be extracted, having been lost in the process of table
248       creation.  Here's just one example.  Consider this MySQL table
249       definition:
250
251           CREATE TABLE mytable
252           (
253             id    INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
254             code  CHAR(6),
255             flag  BOOLEAN NOT NULL DEFAULT 1,
256             bits  BIT(5) NOT NULL DEFAULT '00101',
257             name  VARCHAR(64)
258           );
259
260       Now look at the metadata that MySQL 4 stores internally for this table:
261
262           mysql> describe mytable;
263           +-------+------------------+------+-----+---------+----------------+
264           | Field | Type             | Null | Key | Default | Extra          |
265           +-------+------------------+------+-----+---------+----------------+
266           | id    | int(10) unsigned |      | PRI | NULL    | auto_increment |
267           | code  | varchar(6)       | YES  |     | NULL    |                |
268           | flag  | tinyint(1)       |      |     | 1       |                |
269           | bits  | tinyint(1)       |      |     | 101     |                |
270           | name  | varchar(64)      | YES  |     | NULL    |                |
271           +-------+------------------+------+-----+---------+----------------+
272
273       Note the following divergences from the "CREATE TABLE" statement.
274
275The "code" column has changed from CHAR(6) to VARCHAR(6).  This is
276           troublesome if you want the traditional semantics of a CHAR type,
277           namely the padding with spaces of values that are less than the
278           column length.
279
280The "flag" column has changed from BOOLEAN to TINYINT(1).  The
281           default accessor method created for boolean columns has value
282           coercion and formatting properties that are important to this data
283           type.  The default accessor created for integer columns lacks these
284           constraints.  The metadata object has no way of knowing that "flag"
285           was supposed to be a boolean column, and thus makes the wrong kind
286           of accessor method.  It is thus possible to store, say, a value of
287           "7" in the "flag" column.  Oops.
288
289The "bits" column has changed from BIT(5) to TINYINT(1).  As in the
290           case of the "flag" column above, this type change prevents the
291           correct accessor method from being created.  The default bitfield
292           accessor method auto-inflates column values into Bit::Vector
293           objects, which provide convenient methods for bit manipulation.
294           The default accessor created for integer columns does no such
295           thing.
296
297       Remember that the auto-initialization process can only consider the
298       metadata actually stored in the database.  It has no access to the
299       original "create table" statement.  Thus, the semantics implied by the
300       original table definition are effectively lost.
301
302       Again, this is just one example of the kind of detail that can be lost
303       in the process of converting your table definition into metadata that
304       is stored in the database.  Admittedly, MySQL is perhaps the worst
305       case-scenario, having a well-deserved reputation for disregarding the
306       wishes of table definitions.  (The use of implicit default values for
307       "NOT NULL" columns is yet another example.)
308
309       Thankfully, there is a solution to this dilemma.  Remember that auto-
310       initialization is actually a multi-step process hiding behind that
311       single call to the auto_initialize method.  To correct the sins of the
312       database, simply break the auto-initialization process into its
313       components.  For example, here's how to correctly auto-initialize the
314       "mytable" example above:
315
316           # Make a first pass at column setup
317           $meta->auto_init_columns;
318
319           # Account for inaccuracies in DBD::mysql's column info by
320           # replacing incorrect column definitions with new ones.
321
322           # Fix CHAR(6) column that shows up as VARCHAR(6)
323           $meta->column(code => { type => 'char', length => 6 });
324
325           # Fix BIT(5) column that shows up as TINYINT(1)
326           $meta->column(bits => { type => 'bits', bits => 5, default => 101 });
327
328           # Fix BOOLEAN column that shows up as TINYINT(1)
329           $meta->column(flag => { type => 'boolean', default => 1 });
330
331           # Do everything else
332           $meta->auto_initialize;
333
334       Note that auto_initialize was called at the end.  Without the
335       "replace_existing" parameter, this call will preserve any existing
336       metadata, rather than overwriting it, so our "corrections" are safe.
337
338       Maintenance
339
340       The price of auto-initialization is eternal vigilance.  "What does that
341       mean?  Isn't auto-initialization supposed to save time and effort?"
342       Well, yes, but at a cost.  In addition to the caveats described above,
343       consider what happens when a table definition changes.
344
345       "Ah ha!" you say, "My existing class will automatically pick up the
346       changes the next time it's loaded!  Auto-initialization at its finest!"
347       But is it?  What if you added a "NOT NULL" column with no default
348       value?  Yes, your existing auto-initialized class will pick up the
349       change, but your existing code will no longer be able to save one these
350       objects.  Or what if you're using MySQL and your newly added column is
351       one of the types described above that requires manual tweaking in order
352       to get the desired semantics.  Will you always remember to make this
353       change?
354
355       Auto-initialization is not a panacea.  Every time you make a change to
356       your database schema, you must also revisit each affected
357       Rose::DB::Object-derived class to at least consider whether or not the
358       metadata needs to be corrected or updated.
359
360       The trade-off may be well worth it, but it's still something to think
361       about.  There is, however, a hybrid solution that might be even better.
362       Continue on to the next section to learn more.
363
364   Code Generation
365       As described in the section above, auto-initializing metadata at
366       runtime by querying the database has many caveats.  An alternate
367       approach is to query the database for metadata just once, and then
368       generate the equivalent Perl code which can be pasted directly into the
369       class definition in place of the call to auto_initialize.
370
371       Like the auto-initialization process itself, perl code generation has a
372       convenient wrapper method as well as separate methods for the
373       individual parts.  All of the perl code generation methods begin with
374       "perl_", and they support some rudimentary code formatting options to
375       help the code conform to you preferred style.  Examples can be found
376       with the documentation for each perl_* method.
377
378       This hybrid approach to metadata population strikes a good balance
379       between upfront effort and ongoing maintenance.  Auto-generating the
380       Perl code for the initial class definition saves a lot of tedious
381       typing.  From that point on, manually correcting and maintaining the
382       definition is a small price to pay for the decreased start-up cost, the
383       ability to use the class in the absence of a database connection, and
384       the piece of mind that comes from knowing that your class is stable,
385       and won't change behind your back in response to an "action at a
386       distance" (i.e., a database schema update).
387

CLASS METHODS

389       auto_prime_caches [BOOL]
390           Get or set a boolean value that indicates whether or not the
391           prime_caches method will be called from within the initialize
392           method.  The default is true if the "MOD_PERL" environment variable
393           ($ENV{'MOD_PERL'}) is set to a true value, false otherwise.
394
395       clear_all_dbs
396           Clears the db attribute of the metadata object for each registered
397           class.
398
399       column_type_class TYPE [, CLASS]
400           Given the column type string TYPE, return the name of the
401           Rose::DB::Object::Metadata::Column-derived class used to store
402           metadata and create the accessor method(s) for columns of that
403           type.  If a CLASS is passed, the column type TYPE is mapped to
404           CLASS.  In both cases, the TYPE argument is automatically converted
405           to lowercase.
406
407       column_type_classes [MAP]
408           Get or set the hash that maps column type strings to the names of
409           the Rose::DB::Object::Metadata::Column-derived classes used to
410           store metadata  and create accessor method(s) for columns of that
411           type.
412
413           This hash is class data.  If you want to modify it, I suggest
414           making your own subclass of Rose::DB::Object::Metadata and then
415           setting that as the meta_class of your Rose::DB::Object subclass.
416
417           If passed MAP (a list of type/class pairs or a reference to a hash
418           of the same) then MAP replaces the current column type mapping.
419           Returns a list of type/class pairs (in list context) or a reference
420           to the hash of type/class mappings (in scalar context).
421
422           The default mapping of type names to class names is:
423
424             scalar    => Rose::DB::Object::Metadata::Column::Scalar
425
426             char      => Rose::DB::Object::Metadata::Column::Character
427             character => Rose::DB::Object::Metadata::Column::Character
428             varchar   => Rose::DB::Object::Metadata::Column::Varchar
429             varchar2  => Rose::DB::Object::Metadata::Column::Varchar
430             nvarchar  => Rose::DB::Object::Metadata::Column::Varchar
431             nvarchar2 => Rose::DB::Object::Metadata::Column::Varchar
432             string    => Rose::DB::Object::Metadata::Column::Varchar
433
434             text      => Rose::DB::Object::Metadata::Column::Text
435             blob      => Rose::DB::Object::Metadata::Column::Blob
436             bytea     => Rose::DB::Object::Metadata::Column::Pg::Bytea
437
438             bits      => Rose::DB::Object::Metadata::Column::Bitfield
439             bitfield  => Rose::DB::Object::Metadata::Column::Bitfield
440
441             bool      => Rose::DB::Object::Metadata::Column::Boolean
442             boolean   => Rose::DB::Object::Metadata::Column::Boolean
443
444             int       => Rose::DB::Object::Metadata::Column::Integer
445             integer   => Rose::DB::Object::Metadata::Column::Integer
446
447             tinyint   => Rose::DB::Object::Metadata::Column::Integer
448             smallint  => Rose::DB::Object::Metadata::Column::Integer
449             mediumint => Rose::DB::Object::Metadata::Column::Integer
450
451             bigint    => Rose::DB::Object::Metadata::Column::BigInt
452
453             serial    => Rose::DB::Object::Metadata::Column::Serial
454             bigserial => Rose::DB::Object::Metadata::Column::BigSerial
455
456             enum      => Rose::DB::Object::Metadata::Column::Enum
457
458             num       => Rose::DB::Object::Metadata::Column::Numeric
459             numeric   => Rose::DB::Object::Metadata::Column::Numeric
460             decimal   => Rose::DB::Object::Metadata::Column::Numeric
461             float     => Rose::DB::Object::Metadata::Column::Float
462             float8    => Rose::DB::Object::Metadata::Column::DoublePrecision
463
464             'double precision' =>
465               Rose::DB::Object::Metadata::Column::DoublePrecision
466
467             time      => Rose::DB::Object::Metadata::Column::Time
468             interval  => Rose::DB::Object::Metadata::Column::Interval
469
470             date      => Rose::DB::Object::Metadata::Column::Date
471             datetime  => Rose::DB::Object::Metadata::Column::Datetime
472             timestamp => Rose::DB::Object::Metadata::Column::Timestamp
473
474             timestamptz =>
475               Rose::DB::Object::Metadata::Column::TimestampWithTimeZone
476
477             'timestamp with time zone' =>
478               Rose::DB::Object::Metadata::Column::TimestampWithTimeZone
479
480             'datetime year to fraction' =>
481               Rose::DB::Object::Metadata::Column::DatetimeYearToFraction
482
483             'datetime year to fraction(1)' =>
484               Rose::DB::Object::Metadata::Column::DatetimeYearToFraction1
485
486             'datetime year to fraction(2)' =>
487               Rose::DB::Object::Metadata::Column::DatetimeYearToFraction2
488
489             'datetime year to fraction(3)' =>
490               Rose::DB::Object::Metadata::Column::DatetimeYearToFraction3
491
492             'datetime year to fraction(4)' =>
493               Rose::DB::Object::Metadata::Column::DatetimeYearToFraction4
494
495             'datetime year to fraction(5)' =>
496               Rose::DB::Object::Metadata::Column::DatetimeYearToFraction5
497
498             'timestamp with time zone' =>
499               Rose::DB::Object::Metadata::Column::Timestamp
500
501             'timestamp without time zone' =>
502               Rose::DB::Object::Metadata::Column::Timestamp
503
504             'datetime year to second' =>
505               Rose::DB::Object::Metadata::Column::DatetimeYearToSecond
506
507             'datetime year to minute' =>
508               Rose::DB::Object::Metadata::Column::DatetimeYearToMinute
509
510             'datetime year to month' =>
511               Rose::DB::Object::Metadata::Column::DatetimeYearToMonth
512
513             'epoch'       => Rose::DB::Object::Metadata::Column::Epoch
514             'epoch hires' => Rose::DB::Object::Metadata::Column::Epoch::HiRes
515
516             array     => Rose::DB::Object::Metadata::Column::Array
517             set       => Rose::DB::Object::Metadata::Column::Set
518
519             chkpass   => Rose::DB::Object::Metadata::Column::Pg::Chkpass
520
521       column_type_names
522           Returns the list (in list context) or reference to an array (in
523           scalar context) of registered column type names.
524
525       convention_manager_class NAME [, CLASS]
526           Given the string NAME, return the name of the
527           Rose::DB::Object::ConventionManager-derived class mapped to that
528           name.
529
530           If a CLASS is passed, then NAME is mapped to CLASS.
531
532       convention_manager_classes [MAP]
533           Get or set the hash that maps names to
534           Rose::DB::Object::ConventionManager-derived class names.
535
536           This hash is class data.  If you want to modify it, I suggest
537           making your own subclass of Rose::DB::Object::Metadata and then
538           setting that as the meta_class of your Rose::DB::Object subclass.
539
540           If passed MAP (a list of name/class pairs or a reference to a hash
541           of the same) then MAP replaces the current mapping.  Returns a list
542           of name/class pairs (in list context) or a reference to the hash of
543           name/class mappings (in scalar context).
544
545           The default mapping of names to classes is:
546
547             default => Rose::DB::Object::ConventionManager
548             null    => Rose::DB::Object::ConventionManager::Null
549
550       dbi_prepare_cached [BOOL]
551           Get or set a boolean value that indicates whether or not the
552           Rose::DB::Object-derived class will use DBI's prepare_cached method
553           by default (instead of the prepare method) when loading, saving,
554           and deleting objects.  The default value is true.
555
556       default_column_undef_overrides_default [BOOL]
557           Get or set the default value of the column_undef_overrides_default
558           attribute.  Defaults to undef.
559
560       default_manager_base_class [CLASS]
561           Get or set the default name of the base class used by this metadata
562           class when generating a manager classes.  The default value is
563           "Rose::DB::Object::Manager".  See the
564           "default_manager_base_class()" object method to override this value
565           for a specific metadata object.
566
567       for_class CLASS
568           Returns (or creates, if needed) the single
569           Rose::DB::Object::Metadata object associated with CLASS, where
570           CLASS is the name of a Rose::DB::Object-derived class.
571
572       init_column_name_to_method_name_mapper
573           This class method should return a reference to a subroutine that
574           maps column names to method names, or false if it does not want to
575           do any custom mapping.  The default implementation returns zero
576           (0).
577
578           If defined, the subroutine should take four arguments: the metadata
579           object, the column name, the column method type, and the method
580           name that would be used if the mapper subroutine did not exist.  It
581           should return a method name.
582
583       prime_all_caches [PARAMS]
584           Call prime_caches on all registered_classes, passing PARAMS to each
585           call.  PARAMS are name/value pairs.  Valid parameters are:
586
587           db DB
588               A Rose::DB-derived object used to determine which data source
589               the cached metadata will be generated on behalf of.  (Each data
590               source has its own set of cached metadata.)  This parameter is
591               optional.  If it is not passed, then the Rose::DB-derived
592               object returned by the init_db method for each class will be
593               used instead.
594
595       relationship_type_class TYPE
596           Given the relationship type string TYPE, return the name of the
597           Rose::DB::Object::Metadata::Relationship-derived class used to
598           store metadata and create the accessor method(s) for relationships
599           of that type.
600
601       relationship_type_classes [MAP]
602           Get or set the hash that maps relationship type strings to the
603           names of the Rose::DB::Object::Metadata::Relationship-derived
604           classes used to store metadata and create object methods fetch
605           and/or manipulate objects from foreign tables.
606
607           This hash is class data.  If you want to modify it, I suggest
608           making your own subclass of Rose::DB::Object::Metadata and then
609           setting that as the meta_class of your Rose::DB::Object subclass.
610
611           If passed MAP (a list of type/class pairs or a reference to a hash
612           of the same) then MAP replaces the current relationship type
613           mapping.  Returns a list of type/class pairs (in list context) or a
614           reference to the hash of type/class mappings (in scalar context).
615
616           The default mapping of type names to class names is:
617
618             'one to one'   => Rose::DB::Object::Metadata::Relationship::OneToOne
619             'one to many'  => Rose::DB::Object::Metadata::Relationship::OneToMany
620             'many to one'  => Rose::DB::Object::Metadata::Relationship::ManyToOne
621             'many to many' => Rose::DB::Object::Metadata::Relationship::ManyToMany
622
623       registered_classes
624           Return a list (in list context) or reference to an array (in scalar
625           context) of the names of all Rose::DB::Object-derived classes
626           registered under this metadata class's registry_key.
627
628       registry_key
629           Returns the string used to group Rose::DB::Object-derived class
630           names in the class registry.  The default is
631           "Rose::DB::Object::Metadata".
632

CONSTRUCTOR

634       new PARAMS
635           Returns (or creates, if needed) the single
636           Rose::DB::Object::Metadata associated with a particular
637           Rose::DB::Object-derived class, modifying or initializing it
638           according to PARAMS, where PARAMS are name/value pairs.
639
640           Any object method is a valid parameter name, but PARAMS must
641           include a value for the "class" parameter, since that's how
642           Rose::DB::Object::Metadata objects are mapped to their
643           corresponding Rose::DB::Object-derived class.
644

OBJECT METHODS

646       add_column ARGS
647           This is an alias for the add_columns method.
648
649       add_columns ARGS
650           Add the columns specified by ARGS to the list of columns for the
651           table.  Returns the list of columns added in list context, or a
652           reference to an array of columns added in scalar context.  Columns
653           can be specified in ARGS in several ways.
654
655           If an argument is a subclass of Rose::DB::Object::Metadata::Column,
656           it is added as-is.
657
658           If an argument is a plain scalar, it is taken as the name of a
659           scalar column.  A column object of the class returned by the method
660           call "$obj->column_type_class('scalar')" is constructed and then
661           added.
662
663           Otherwise, only name/value pairs are considered, where the name is
664           taken as the column name and the value must be a reference to a
665           hash.
666
667           If the hash contains the key "primary_key" with a true value, then
668           the column is marked as a primary_key_member and the column name is
669           added to the list of primary key columns by calling the
670           add_primary_key_column method with the column name as its argument.
671
672           If the hash contains the key "alias", then the value of that key is
673           used as the alias for the column.  This is a shorthand equivalent
674           to explicitly calling the alias_column column method.
675
676           If the hash contains the key "temp" and its value is true, then the
677           column is actually added to the list of non-persistent columns.
678
679           If the hash contains a key with the same name as a column trigger
680           event type (e.g., "on_set", "on_load", "inflate") then the value of
681           that key must be a code reference or a reference to an array of
682           code references, which will be added to the list of the column's
683           triggers for the specified event type.
684
685           If the hash contains the key "methods", then its value must be a
686           reference to an array or a reference to a hash.  The
687           auto_method_types of the column are then set to the values of the
688           referenced array, or the keys of the referenced hash.  The values
689           of the referenced hash are used to set the method_name for their
690           corresponding method types.
691
692           If the hash contains the key "add_methods", then its value must be
693           a reference to an array or a reference to a hash.  The values of
694           the referenced array or the keys of the referenced hash are added
695           to the column's auto_method_types.  The values of the referenced
696           hash are used to set the method_name for their corresponding method
697           types.
698
699           If the "methods" and "add_methods" keys are both set, a fatal error
700           will occur.
701
702           Then the column_type_class method is called with the value of the
703           "type" hash key as its argument (or "scalar" if that key is
704           missing), returning the name of a column class.  Finally, a new
705           column object of that class is constructed and is passed all the
706           remaining pairs in the hash reference, along with the name and type
707           of the column.  That column object is then added to the list of
708           columns.
709
710           This is done until there are no more arguments to be processed, or
711           until an argument does not conform to one of the required formats,
712           in which case a fatal error occurs.
713
714           Example:
715
716               $meta->add_columns
717               (
718                 # Add a scalar column
719                 'name',
720
721                 # which is roughly equivalent to:
722                 #
723                 # $class = $meta->column_type_class('scalar');
724                 # $col = $class->new(name => 'name');
725                 # (then add $col to the list of columns)
726
727                 # Add by name/hashref pair with explicit method types
728                 age => { type => 'int', default => 5, methods => [ 'get', 'set' ] },
729
730                 # which is roughly equivalent to:
731                 #
732                 # $class = $meta->column_type_class('int');
733                 # $col = $class->new(name    => 'age',
734                 #                    type    => 'int',
735                 #                    default => 5);
736                 # $col->auto_method_types('get', 'set');
737                 # (then add $col to the list of columns)
738
739                 # Add by name/hashref pair with additional method type and name
740                 size => { type => 'int', add_methods => { 'set' => 'set_my_size' } },
741
742                 # which is roughly equivalent to:
743                 #
744                 # $class = $meta->column_type_class('int');
745                 # $col = $class->new(name    => 'size',
746                 #                    type    => 'int',);
747                 # $col->add_auto_method_types('set');
748                 # $col->method_name(set => 'set_my_size');
749                 # (then add $col to the list of columns)
750
751                 # Add a column object directly
752                 Rose::DB::Object::Metadata::Column::Date->new(
753                   name => 'start_date'),
754               );
755
756       add_nonpersistent_column ARGS
757           This is an alias for the add_nonpersistent_columns method.
758
759       add_nonpersistent_columns ARGS
760           This method behaves like the add_columns method, except that it
761           adds to the list of non-persistent columns.  See the documentation
762           for the nonpersistent_columns method for more information.
763
764       add_foreign_keys ARGS
765           Add foreign keys as specified by ARGS.  Each foreign key must have
766           a name that is unique among all other foreign keys in this class.
767
768           Foreign keys can be specified in ARGS in several ways.
769
770           If an argument is a Rose::DB::Object::Metadata::ForeignKey object
771           (or subclass thereof), it is added as-is.
772
773           Otherwise, only name/value pairs are considered, where the name is
774           taken as the foreign key name and the value must be a reference to
775           a hash.
776
777           If the hash contains the key "methods", then its value must be a
778           reference to an array or a reference to a hash.  The
779           auto_method_types of the foreign key are then set to the values of
780           the referenced array, or the keys of the referenced hash.  The
781           values of the referenced hash are used to set the method_name for
782           their corresponding method types.
783
784           If the hash contains the key "add_methods", then its value must be
785           a reference to an array or a reference to a hash.  The values of
786           the referenced array or the keys of the referenced hash are added
787           to the foreign key's auto_method_types.  The values of the
788           referenced hash are used to set the method_name for their
789           corresponding method types.
790
791           If the "methods" and "add_methods" keys are both set, a fatal error
792           will occur.
793
794           A new Rose::DB::Object::Metadata::ForeignKey object is constructed
795           and is passed all the remaining pairs in the hash reference, along
796           with the name of the foreign key as the value of the "name"
797           parameter.  That foreign key object is then added to the list of
798           foreign keys.
799
800           This is done until there are no more arguments to be processed, or
801           until an argument does not conform to one of the required formats,
802           in which case a fatal error occurs.
803
804           Example:
805
806               $meta->add_foreign_keys
807               (
808                 # Add by name/hashref pair with explicit method type
809                 category =>
810                 {
811                   class       => 'Category',
812                   key_columns => { category_id => 'id' },
813                   methods => [ 'get' ],
814                 },
815
816                 # which is roughly equivalent to:
817                 #
818                 # $fk = Rose::DB::Object::Metadata::ForeignKey->new(
819                 #         class       => 'Category',
820                 #         key_columns => { category_id => 'id' },
821                 #         name        => 'category');
822                 # $fk->auto_method_types('get');
823                 # (then add $fk to the list of foreign keys)
824
825                 # Add by name/hashref pair with additional method type and name
826                 color =>
827                 {
828                   class       => 'Color',
829                   key_columns => { color_id => 'id' },
830                   add_methods => { set => 'set_my_color' },
831                 },
832
833                 # which is roughly equivalent to:
834                 #
835                 # $fk = Rose::DB::Object::Metadata::ForeignKey->new(
836                 #         class       => 'Color',
837                 #         key_columns => { color_id => 'id' },
838                 #         name        => 'color');
839                 # $fk->add_auto_method_types('set');
840                 # $fk->method_name(set => 'set_my_color');
841                 # (then add $fk to the list of foreign keys)
842
843                 # Add a foreign key object directly
844                 Rose::DB::Object::Metadata::ForeignKey->new(...),
845               );
846
847           For each foreign key added, a corresponding relationship with the
848           same name is added if it does not already exist.  The relationship
849           type is determined by the value of the foreign key object's
850           relationship attribute.  The default is "many to one".  The class
851           of the relationship is chosen by calling relationship_type_class
852           with the relationship type as an argument.
853
854       add_primary_key_column COLUMN
855           This method is an alias for add_primary_key_columns.
856
857       add_primary_key_columns COLUMNS
858           Add COLUMNS to the list of columns that make up the primary key.
859           COLUMNS can be a list or reference to an array of column names.
860
861       add_relationship ARGS
862           This is an alias for the add_relationships method.
863
864       add_relationships ARGS
865           Add relationships as specified by ARGS.  Each relationship must
866           have a name that is unique among all other relationships in this
867           class.
868
869           Relationships can be specified in ARGS in several ways.
870
871           If an argument is a subclass of
872           Rose::DB::Object::Metadata::Relationship, it is added as-is.
873
874           Otherwise, only name/value pairs are considered, where the name is
875           taken as the relationship name and the value must be a reference to
876           a hash.
877
878           If the hash contains the key "methods", then its value must be a
879           reference to an array or a reference to a hash.  The
880           auto_method_types of the relationship are then set to the values of
881           the referenced array, or the keys of the referenced hash.  The
882           values of the referenced hash are used to set the method_name for
883           their corresponding method types.
884
885           If the hash contains the key "add_methods", then its value must be
886           a reference to an array or a reference to a hash.  The values of
887           the referenced array or the keys of the referenced hash are added
888           to the relationship's auto_method_types.  The values of the
889           referenced hash are used to set the method_name for their
890           corresponding method types.
891
892           If the "methods" and "add_methods" keys are both set, a fatal error
893           will occur.
894
895           Then the relationship_type_class method is called with the value of
896           the "type" hash key as its argument, returning the name of a
897           relationship class.
898
899           Finally, a new relationship object of that class is constructed and
900           is passed all the remaining pairs in the hash reference, along with
901           the name and type of the relationship.  That relationship object is
902           then added to the list of relationships.
903
904           This is done until there are no more arguments to be processed, or
905           until an argument does not conform to one of the required formats,
906           in which case a fatal error occurs.
907
908           Example:
909
910               $meta->add_relationships
911               (
912                 # Add by name/hashref pair with explicit method type
913                 category =>
914                 {
915                   type       => 'many to one',
916                   class      => 'Category',
917                   column_map => { category_id => 'id' },
918                   methods    => [ 'get' ],
919                 },
920
921                 # which is roughly equivalent to:
922                 #
923                 # $class = $meta->relationship_type_class('many to one');
924                 # $rel = $class->new(class      => 'Category',
925                 #                    column_map => { category_id => 'id' },
926                 #                    name       => 'category');
927                 # $rel->auto_method_types('get');
928                 # (then add $rel to the list of relationships)
929
930                 # Add by name/hashref pair with additional method type and name
931                 color =>
932                 {
933                   type        => 'many to one',
934                   class       => 'Color',
935                   column_map  => { color_id => 'id' },
936                   add_methods => { set => 'set_my_color' },
937                 },
938
939                 # which is roughly equivalent to:
940                 #
941                 # $class = $meta->relationship_type_class('many to one');
942                 # $rel = $class->new(class      => 'Color',
943                 #                    column_map => { color_id => 'id' },
944                 #                    name       => 'color');
945                 # $rel->add_auto_method_types('set');
946                 # $fk->method_name(set => 'set_my_color');
947                 # (rel add $fk to the list of foreign keys)
948
949                 # Add a relationship object directly
950                 Rose::DB::Object::Metadata::Relationship::OneToOne->new(...),
951               );
952
953       add_unique_key KEY
954           This method is an alias for add_unique_keys.
955
956       add_unique_keys KEYS
957           Add new unique keys specified by KEYS.  Unique keys can be
958           specified in KEYS in two ways.
959
960           If an argument is a Rose::DB::Object::Metadata::UniqueKey object
961           (or subclass thereof), then its parent is set to the metadata
962           object itself, and it is added.
963
964           Otherwise, an argument must be a single column name or a reference
965           to an array of column names that make up a unique key.  A new
966           Rose::DB::Object::Metadata::UniqueKey is created, with its parent
967           set to the metadata object itself, and then the unique key object
968           is added to this list of unique keys for this class.
969
970       alias_column NAME, ALIAS
971           Set the alias for the column named NAME to ALIAS.  It is sometimes
972           necessary to use an alias for a column because the column name
973           conflicts with an existing Rose::DB::Object method name.
974
975           For example, imagine a column named "save".  The Rose::DB::Object
976           API already defines a method named save, so obviously that name
977           can't be used for the accessor method for the "save" column.  To
978           solve this, make an alias:
979
980               $meta->alias_column(save => 'save_flag');
981
982           See the Rose::DB::Object documentation or call the
983           method_name_is_reserved method to determine if a method name is
984           reserved.
985
986       allow_inline_column_values [BOOL]
987           Get or set the boolean flag that indicates whether or not the
988           associated Rose::DB::Object-derived class should try to inline
989           column values that DBI does not handle correctly when they are
990           bound to placeholders using bind_columns.  The default value is
991           false.
992
993           Enabling this flag reduces the performance of the update and insert
994           operations on the Rose::DB::Object-derived object.  But it is
995           sometimes necessary to enable the flag because some DBI drivers do
996           not (or cannot) always do the right thing when binding values to
997           placeholders in SQL statements.  For example, consider the
998           following SQL for the Informix database:
999
1000               CREATE TABLE test (d DATETIME YEAR TO SECOND);
1001               INSERT INTO test (d) VALUES (CURRENT);
1002
1003           This is valid Informix SQL and will insert a row with the current
1004           date and time into the "test" table.
1005
1006           Now consider the following attempt to do the same thing using DBI
1007           placeholders (assume the table was already created as per the
1008           CREATE TABLE statement above):
1009
1010               $sth = $dbh->prepare('INSERT INTO test (d) VALUES (?)');
1011               $sth->execute('CURRENT'); # Error!
1012
1013           What you'll end up with is an error like this:
1014
1015               DBD::Informix::st execute failed: SQL: -1262: Non-numeric
1016               character in datetime or interval.
1017
1018           In other words, DBD::Informix has tried to quote the string
1019           "CURRENT", which has special meaning to Informix only when it is
1020           not quoted.
1021
1022           In order to make this work, the value "CURRENT" must be "inlined"
1023           rather than bound to a placeholder when it is the value of a
1024           "DATETIME YEAR TO SECOND" column in an Informix database.
1025
1026       auto_load_related_classes [BOOL]
1027           Get or set a flag that indicates whether or not classes related to
1028           this class through a foreign key or other relationship will be
1029           automatically loaded when this class is initialized.  The default
1030           value is true.
1031
1032       cached_objects_expire_in [DURATION]
1033           This method is only applicable if this metadata object is
1034           associated with a Rose::DB::Object::Cached-derived class.  It
1035           simply calls the class method of the same name that belongs to the
1036           Rose::DB::Object::Cached-derived class associated with this
1037           metadata object.
1038
1039       catalog [CATALOG]
1040           Get or set the database catalog for this class.  This setting will
1041           override any setting in the db object.  Use this method only if you
1042           know that the class will always point to a specific catalog,
1043           regardless of what the Rose::DB-derived database handle object
1044           specifies.
1045
1046       class [CLASS]
1047           Get or set the Rose::DB::Object-derived class associated with this
1048           metadata object.  This is the class where the accessor methods for
1049           each column will be created (by make_methods).
1050
1051       class_for PARAMS
1052           Returns the name of the Rose::DB::Object-derived class associated
1053           with the "catalog", "schema", and "table" specified by the
1054           name/value paris in PARAMS.  Catalog and/or schema maybe omitted if
1055           unknown or inapplicable, and the "best" match will be returned.
1056           Returns undef if there is no class name registered under the
1057           specified PARAMS.
1058
1059           Note: This method may also be called as a class method, but may
1060           require explicit "catalog" and/or "schema" arguments when dealing
1061           with databases that support these concepts and have default
1062           implicit values for them.
1063
1064       clear_object_cache
1065           This method is only applicable if this metadata object is
1066           associated with a Rose::DB::Object::Cached-derived class.  It
1067           simply calls the class method of the same name that belongs to the
1068           Rose::DB::Object::Cached-derived class associated with this
1069           metadata object.
1070
1071       column NAME [, COLUMN | HASHREF]
1072           Get or set the column named NAME.  If just NAME is passed, the
1073           Rose::DB::Object::Metadata::Column-derived column object for the
1074           column of that name is returned.  If no such column exists, undef
1075           is returned.
1076
1077           If both NAME and COLUMN are passed, then COLUMN must be a
1078           Rose::DB::Object::Metadata::Column-derived object.  COLUMN has its
1079           name set to NAME, and is then stored as the column metadata object
1080           for NAME, replacing any existing column.
1081
1082           If both NAME and HASHREF are passed, then the combination of NAME
1083           and HASHREF must form a name/value pair suitable for passing to the
1084           add_columns method.  The new column specified by NAME and HASHREF
1085           replaces any existing column.
1086
1087       columns [ARGS]
1088           Get or set the full list of columns.  If ARGS are passed, the
1089           column list is cleared and then ARGS are passed to the add_columns
1090           method.
1091
1092           Returns a list of column objects in list context, or a reference to
1093           an array of column objects in scalar context.
1094
1095       column_accessor_method_name NAME
1096           Returns the name of the "get" method for the column named NAME.
1097           This is just a shortcut for
1098           "$meta->column(NAME)->accessor_method_name".
1099
1100       column_accessor_method_names
1101           Returns a list (in list context) or a reference to the array (in
1102           scalar context) of the names of the "set" methods for all the
1103           columns, in the order that the columns are returned by
1104           column_names.
1105
1106       column_aliases [MAP]
1107           Get or set the hash that maps column names to their aliases.  If
1108           passed MAP (a list of name/value pairs or a reference to a hash)
1109           then MAP replaces the current alias mapping.  Returns a reference
1110           to the hash that maps column names to their aliases.
1111
1112           Note that modifying this map has no effect if initialize,
1113           make_methods, or make_column_methods has already been called for
1114           the current class.
1115
1116       column_mutator_method_name NAME
1117           Returns the name of the "set" method for the column named NAME.
1118           This is just a shortcut for
1119           "$meta->column(NAME)->mutator_method_name".
1120
1121       column_mutator_method_names
1122           Returns a list (in list context) or a reference to the array (in
1123           scalar context) of the names of the "set" methods for all the
1124           columns, in the order that the columns are returned by
1125           column_names.
1126
1127       column_names
1128           Returns a list (in list context) or a reference to an array (in
1129           scalar context) of column names.
1130
1131       column_name_to_method_name_mapper [CODEREF]
1132           Get or set the code reference to the subroutine used to map column
1133           names to  method names.  If undefined, then the
1134           init_column_name_to_method_name_mapper class method is called in
1135           order to initialize it.  If still undefined or false, then the
1136           "default" method name is used.
1137
1138           If defined, the subroutine should take four arguments: the metadata
1139           object, the column name, the column method type, and the method
1140           name that would be used if the mapper subroutine did not exist.  It
1141           should return a method name.
1142
1143       column_rw_method_name NAME
1144           Returns the name of the "get_set" method for the column named NAME.
1145           This is just a shortcut for "$meta->column(NAME)->rw_method_name".
1146
1147       column_rw_method_names
1148           Returns a list (in list context) or a reference to the array (in
1149           scalar context) of the names of the "get_set" methods for all the
1150           columns, in the order that the columns are returned by
1151           column_names.
1152
1153       column_undef_overrides_default [BOOL]
1154           Get or set a boolean value that influences the default value of the
1155           undef_overrides_default attribute for each column in this class.
1156           See the documentation for Rose::DB::Object::Metadata::Column's
1157           undef_overrides_default attribute for more information.
1158
1159           Defaults to the value returned by the
1160           default_column_undef_overrides_default class method.
1161
1162       convention_manager [ OBJECT | CLASS | NAME ]
1163           Get or set the convention manager for this class.  Defaults to the
1164           return value of the init_convention_manager method.
1165
1166           If undef is passed, then a
1167           Rose::DB::Object::ConventionManager::Null object is stored instead.
1168
1169           If a Rose::DB::Object::ConventionManager-derived object is passed,
1170           its meta attribute set to this metadata object and then it is used
1171           as the convention manager for this class.
1172
1173           If a Rose::DB::Object::ConventionManager-derived class name is
1174           passed, a new object of that class is created with its meta
1175           attribute set to this metadata object.  Then it is used as the
1176           convention manager for this class.
1177
1178           If a convention manager name is passed, then the corresponding
1179           class is looked up in the convention manager class map, a new
1180           object of that class is constructed, its meta attribute set to this
1181           metadata object, and it is used as the convention manager for this
1182           class.  If there is no class mapped to NAME, a fatal error will
1183           occur.
1184
1185           See the Rose::DB::Object::ConventionManager documentation for more
1186           information on convention managers.
1187
1188       db  Returns the Rose::DB-derived object associated with this metadata
1189           object's class.  A fatal error will occur if class is undefined or
1190           if the Rose::DB object could not be created.
1191
1192       default_cascade_save [BOOL]
1193           Get or set a boolean value that indicates whether or not the class
1194           associated with this metadata object will save related objects when
1195           the parent object is saved.  See the documentation for
1196           Rose::DB::Object's save() method for details.  The default value is
1197           false.
1198
1199       default_load_speculative [BOOL]
1200           Get or set a boolean value that indicates whether or not the class
1201           associated with this metadata object will load speculatively by
1202           default.  See the documentation for Rose::DB::Object's load()
1203           method for details.  The default value is false.
1204
1205       default_update_changes_only [BOOL]
1206           Get or set a boolean value that indicates whether or not the class
1207           associated with this metadata object will update only an object's
1208           modified columns by default (instead of updating all columns).  See
1209           the documentation for Rose::DB::Object's update() method for
1210           details.  The default value is false.
1211
1212       delete_column NAME
1213           Delete the column named NAME.
1214
1215       delete_columns
1216           Delete all of the columns.
1217
1218       delete_column_type_class TYPE
1219           Delete the type/class mapping entry for the column type TYPE.
1220
1221       delete_convention_manager_class NAME
1222           Delete the name/class mapping entry for the convention manager
1223           class mapped to NAME.
1224
1225       delete_nonpersistent_column NAME
1226           Delete the non-persistent column named NAME.
1227
1228       delete_nonpersistent_columns
1229           Delete all of the nonpersistent_columns.
1230
1231       delete_relationship NAME
1232           Delete the relationship named NAME.
1233
1234       delete_relationships
1235           Delete all of the relationships.
1236
1237       delete_relationship_type_class TYPE
1238           Delete the type/class mapping entry for the relationship type TYPE.
1239
1240       delete_unique_keys
1241           Delete all of the unique key definitions.
1242
1243       error_mode [MODE]
1244           Get or set the error mode of the Rose::DB::Object that fronts the
1245           table described by this Rose::DB::Object::Metadata object.  If the
1246           error mode is false, then it defaults to the return value of the
1247           "init_error_mode" method, which is "fatal" by default.
1248
1249           The error mode determines what happens when a Rose::DB::Object
1250           method encounters an error.  The "return" error mode causes the
1251           methods to behave as described in the Rose::DB::Object
1252           documentation.  All other error modes cause an action to be
1253           performed before (possibly) returning as per the documentation
1254           (depending on whether or not the "action" is some variation on
1255           "throw an exception.")
1256
1257           Valid values of MODE are:
1258
1259           carp
1260               Call Carp::carp with the value of the object error as an
1261               argument.
1262
1263           cluck
1264               Call Carp::cluck with the value of the object error as an
1265               argument.
1266
1267           confess
1268               Call Carp::confess with the value of the object error as an
1269               argument.
1270
1271           croak
1272               Call Carp::croak with the value of the object error as an
1273               argument.
1274
1275           fatal
1276               An alias for the "croak" mode.
1277
1278           return
1279               Return a value that indicates that an error has occurred, as
1280               described in the documentation for each method.
1281
1282           In all cases, the object's error attribute will also contain the
1283           error message.
1284
1285       first_column
1286           Returns the first column, determined by the order that columns were
1287           added, or undef if there are no columns.
1288
1289       foreign_key NAME [, FOREIGNKEY | HASHREF ]
1290           Get or set the foreign key named NAME.  NAME should be the name of
1291           the thing being referenced by the foreign key, not the name of any
1292           of the columns that make up the foreign key.  If called with just a
1293           NAME argument, the foreign key stored under that name is returned.
1294           Undef is returned if there is no such foreign key.
1295
1296           If both NAME and FOREIGNKEY are passed, then FOREIGNKEY must be a
1297           Rose::DB::Object::Metadata::ForeignKey-derived object.  FOREIGNKEY
1298           has its name set to NAME, and is then stored, replacing any
1299           existing foreign key with the same name.
1300
1301           If both NAME and HASHREF are passed, then the combination of NAME
1302           and HASHREF must form a name/value pair suitable for passing to the
1303           add_foreign_keys method.  The new foreign key specified by NAME and
1304           HASHREF replaces any existing foreign key with the same name.
1305
1306       foreign_keys [ARGS]
1307           Get or set the full list of foreign keys.  If ARGS are passed, the
1308           foreign key list is cleared and then ARGS are passed to the
1309           add_foreign_keys method.
1310
1311           Returns a list of foreign key objects in list context, or a
1312           reference to an array of foreign key objects in scalar context.
1313
1314       generate_primary_key_value DB
1315           This method is the same as generate_primary_key_values except that
1316           it only returns the generated value for the first primary key
1317           column, rather than the entire list of values.  Use this method
1318           only when there is a single primary key column (or not at all).
1319
1320       generate_primary_key_values DB
1321           Given the Rose::DB-derived object DB, generate and return a list of
1322           new primary key column values for the table described by this
1323           metadata object.
1324
1325           If a primary_key_generator is defined, it will be called (passed
1326           this metadata object and the DB) and its value returned.
1327
1328           If no primary_key_generator is defined, new primary key values will
1329           be generated, if possible, using the native facilities of the
1330           current database.  Note that this may not be possible for databases
1331           that auto-generate such values only after an insertion.  In that
1332           case, undef will be returned.
1333
1334       include_predicated_unique_indexes [BOOL]
1335           Get or set a boolean value that indicates whether or not the
1336           auto_init_unique_keys method will create unique keys for unique
1337           indexes that have predicates.  The default value is false.  This
1338           feature is currently only supported for PostgreSQL.
1339
1340           Here's an example of a unique index that has a predicate:
1341
1342               CREATE UNIQUE INDEX my_idx ON mytable (mycolumn) WHERE mycolumn > 123;
1343
1344           The predicate in this case is "WHERE mycolumn > 123".
1345
1346           Predicated unique indexes differ semantically from unpredicated
1347           unique indexes in that predicates generally cause the index to only
1348           apply to part of a table.  Rose::DB::Object expects unique indexes
1349           to uniquely identify a row within a table.  Predicated indexes that
1350           fail to do so due to their predicates should therefore not have
1351           Rose::DB::Object::Metadata::UniqueKey objects created for them,
1352           thus the false default for this attribute.
1353
1354       init_convention_manager
1355           Returns the default Rose::DB::Object::ConventionManager-derived
1356           object used as the convention manager for this class.  This object
1357           will be of the class returned by
1358           convention_manager_class('default').
1359
1360           Override this method in your Rose::DB::Object::Metadata subclass,
1361           or re-map the "default" convention manager class, in order to use a
1362           different convention manager class.  See the tips and tricks
1363           section of the Rose::DB::Object::ConventionManager documentation
1364           for an example of the subclassing approach.
1365
1366       initialize [ARGS]
1367           Initialize the Rose::DB::Object-derived class associated with this
1368           metadata object by creating accessor methods for each column and
1369           foreign key.  The table name and the primary_key_columns must be
1370           defined or a fatal error will occur.
1371
1372           If any column name in the primary key or any of the unique keys
1373           does not exist in the list of columns, then that primary or unique
1374           key is deleted.  (As per the above, this will trigger a fatal error
1375           if any column in the primary key is not in the column list.)
1376
1377           ARGS, if any, are passed to the call to make_methods that actually
1378           creates the methods.
1379
1380           If auto_prime_caches is true, then the prime_caches method will be
1381           called at the end of the initialization process.
1382
1383       is_initialized [BOOL]
1384           Get or set a boolean value that indicates whether or not this class
1385           was initialized.  A successful call to the initialize method will
1386           automatically set this flag to true.
1387
1388       make_manager_class [PARAMS | CLASS]
1389           This method creates a Rose::DB::Object::Manager-derived class to
1390           manage objects of this class.  To do so, it simply calls
1391           perl_manager_class, passing all arguments, and then evaluates the
1392           result.  See the perl_manager_class documentation for more
1393           information.
1394
1395       make_methods [ARGS]
1396           Create object methods in class for each column, foreign key, and
1397           relationship.  This is done by calling make_column_methods,
1398           make_nonpersistent_column_methods, make_foreign_key_methods, and
1399           make_relationship_methods, in that order.
1400
1401           ARGS are name/value pairs which are passed on to the other
1402           "make_*_methods" calls.  They are all optional.  Valid ARGS are:
1403
1404           •   "preserve_existing"
1405
1406               If set to a true value, a method will not be created if there
1407               is already an existing method with the same named.
1408
1409           •   "replace_existing"
1410
1411               If set to a true value, override any existing method with the
1412               same name.
1413
1414           In the absence of one of these parameters, any method name that
1415           conflicts with an existing method name will cause a fatal error.
1416
1417       make_column_methods [ARGS]
1418           Create accessor/mutator methods in class for each column.  ARGS are
1419           name/value pairs, and are all optional.  Valid ARGS are:
1420
1421           •   "preserve_existing"
1422
1423               If set to a true value, a method will not be created if there
1424               is already an existing method with the same named.
1425
1426           •   "replace_existing"
1427
1428               If set to a true value, override any existing method with the
1429               same name.
1430
1431           For each auto_method_type in each column, the method name is
1432           determined by passing the column name and the method type to
1433           method_name_from_column_name.  If the resulting method name is
1434           reserved (according to method_name_is_reserved, a fatal error will
1435           occur.  The object methods for each column are created by calling
1436           the column object's make_methods method.
1437
1438       make_foreign_key_methods [ARGS]
1439           Create object methods in class for each foreign key.  ARGS are
1440           name/value pairs, and are all optional.  Valid ARGS are:
1441
1442           •   "preserve_existing"
1443
1444               If set to a true value, a method will not be created if there
1445               is already an existing method with the same named.
1446
1447           •   "replace_existing"
1448
1449               If set to a true value, override any existing method with the
1450               same name.
1451
1452           For each auto_method_type in each foreign key, the method name is
1453           determined by passing the method type to the method_name method of
1454           the foreign key object, or the build_method_name_for_type method if
1455           the method_name call returns a false value.  If the method name is
1456           reserved (according to method_name_is_reserved), a fatal error will
1457           occur.  The object methods for each foreign key are created by
1458           calling the foreign key  object's make_methods method.
1459
1460           Foreign keys and relationships with the type "one to one" or "many
1461           to one" both encapsulate essentially the same information.  They
1462           are kept in sync when this method is called by setting the
1463           foreign_key attribute of each "one to one" or "many to one"
1464           relationship object to be the corresponding foreign key object.
1465
1466       make_nonpersistent_column_methods [ARGS]
1467           This method behaves like the make_column_methods method, except
1468           that it works with non-persistent columns.  See the documentation
1469           for the nonpersistent_columns method for more information on non-
1470           persistent columns.
1471
1472       make_relationship_methods [ARGS]
1473           Create object methods in class for each relationship.  ARGS are
1474           name/value pairs, and are all optional.  Valid ARGS are:
1475
1476           •   "preserve_existing"
1477
1478               If set to a true value, a method will not be created if there
1479               is already an existing method with the same named.
1480
1481           •   "replace_existing"
1482
1483               If set to a true value, override any existing method with the
1484               same name.
1485
1486           For each auto_method_type in each relationship, the method name is
1487           determined by passing the method type to the method_name method of
1488           the relationship object, or the build_method_name_for_type method
1489           if the method_name call returns a false value.  If the method name
1490           is reserved (according to method_name_is_reserved), a fatal error
1491           will occur.  The object methods for each relationship are created
1492           by calling the relationship  object's make_methods method.
1493
1494           Foreign keys and relationships with the type "one to one" or "many
1495           to one" both encapsulate essentially the same information.  They
1496           are kept in sync when this method is called by setting the
1497           foreign_key attribute of each "one to one" or "many to one"
1498           relationship object to be the corresponding foreign key object.
1499
1500           If a relationship corresponds exactly to a foreign key, and that
1501           foreign key already made an object method, then the relationship is
1502           not asked to make its own method.
1503
1504       default_manager_base_class [CLASS]
1505           Get or set the default name of the base class used by this specific
1506           metadata object when generating a manager class, using either the
1507           perl_manager_class or make_manager_class methods.  The default
1508           value is determined by the
1509           "default_manager_base_class|/default_manager_base_class()" class
1510           method.
1511
1512       method_column METHOD
1513           Returns the name of the column manipulated by the method named
1514           METHOD.
1515
1516       method_name_from_column_name NAME, TYPE
1517           Looks up the column named NAME and calls method_name_from_column
1518           with the column and TYPE as argument.  If no such column exists, a
1519           fatal error will occur.
1520
1521       method_name_from_column COLUMN, TYPE
1522           Given a Rose::DB::Object::Metadata::Column-derived column object
1523           and a column type name, return the corresponding method name that
1524           should be used for it.  Several entities are given an opportunity
1525           to determine the name.  They are consulted in the following order.
1526
1527           1. If a custom-defined column_name_to_method_name_mapper exists,
1528           then it is used to generate the method name and this name is
1529           returned.
1530           2. If a method name has been explicitly set, for this type in the
1531           column object itself, then this name is returned.
1532           3. If the convention manager's auto_column_method_name method
1533           returns a defined value, then this name is returned.
1534           4. Otherwise, the default naming rules as defined in the column
1535           class itself are used.
1536       method_name_is_reserved NAME, CLASS
1537           Given the method name NAME and the class name CLASS, returns true
1538           if the method name is reserved (i.e., is used by the CLASS API),
1539           false otherwise.
1540
1541       nonpersistent_column NAME [, COLUMN | HASHREF]
1542           This method behaves like the column method, except that it works
1543           with non-persistent columns.  See the documentation for the
1544           nonpersistent_columns method for more information on non-persistent
1545           columns.
1546
1547       nonpersistent_columns [ARGS]
1548           Get or set the full list of non-persistent columns.  If ARGS are
1549           passed, the non-persistent column list is cleared and then ARGS are
1550           passed to the add_nonpersistent_columns method.
1551
1552           Returns a list of non-persistent column objects in list context, or
1553           a reference to an array of non-persistent column objects in scalar
1554           context.
1555
1556           Non-persistent columns allow the creation of object attributes and
1557           associated accessor/mutator methods exactly like those associated
1558           with columns, but without ever sending any of these attributes to
1559           (or pulling any these attributes from) the database.
1560
1561           Non-persistent columns are tracked entirely separately from
1562           columns.  Adding, deleting, and listing non-persistent columns has
1563           no affect on the list of normal (i.e., "persistent") columns.
1564
1565           You cannot query the database (e.g., using
1566           Rose::DB::Object::Manager) and filter on a non-persistent column;
1567           non-persistent columns do not exist in the database.  This feature
1568           exists solely to leverage the method creation abilities of the
1569           various column classes.
1570
1571       nonpersistent_column_accessor_method_name NAME
1572           Returns the name of the "get" method for the non-persistent column
1573           named NAME.  This is just a shortcut for
1574           "$meta->nonpersistent_column(NAME)->accessor_method_name".
1575
1576       nonpersistent_column_accessor_method_names
1577           Returns a list (in list context) or a reference to the array (in
1578           scalar context) of the names of the "set" methods for all the non-
1579           persistent columns, in the order that the columns are returned by
1580           nonpersistent_column_names.
1581
1582       nonpersistent_column_mutator_method_name NAME
1583           Returns the name of the "set" method for the non-persistent column
1584           named NAME.  This is just a shortcut for
1585           "$meta->nonpersistent_column(NAME)->mutator_method_name".
1586
1587       nonpersistent_column_mutator_method_names
1588           Returns a list (in list context) or a reference to the array (in
1589           scalar context) of the names of the "set" methods for all the non-
1590           persistent columns, in the order that the columns are returned by
1591           nonpersistent_column_names.
1592
1593       nonpersistent_column_names
1594           Returns a list (in list context) or a reference to an array (in
1595           scalar context) of non-persistent column names.
1596
1597       pk_columns [COLUMNS]
1598           This is an alias for the primary_key_columns method.
1599
1600       post_init_hook [ CODEREF | ARRAYREF ]
1601           Get or set a reference to a subroutine or a reference to an array
1602           of code references that will be called just after the initialize
1603           method runs.  Each referenced subroutine will be passed the
1604           metadata object itself and any arguments passed to the call to
1605           initialize.
1606
1607       pre_init_hook [ CODEREF | ARRAYREF ]
1608           Get or set a reference to a subroutine or a reference to an array
1609           of code references that will be called just before the initialize
1610           method runs.  Each referenced subroutine will be passed the
1611           metadata object itself and any arguments passed to the call to
1612           initialize.
1613
1614       primary_key [PK]
1615           Get or set the Rose::DB::Object::Metadata::PrimaryKey object that
1616           stores the list of column names that make up the primary key for
1617           this table.
1618
1619       primary_key_columns [COLUMNS]
1620           Get or set the list of columns that make up the primary key.
1621           COLUMNS should be a list of column names or
1622           Rose::DB::Object::Metadata::Column-derived objects.
1623
1624           Returns all of the columns that make up the primary key.  Each
1625           column is a Rose::DB::Object::Metadata::Column-derived column
1626           object if a column object with the same name exists, or just the
1627           column name otherwise.  In scalar context, a reference to an array
1628           of columns is returned.  In list context, a list is returned.
1629
1630           This method is just a shortcut for the code:
1631
1632               $meta->primary_key->columns(...);
1633
1634           See the primary_key method and the
1635           Rose::DB::Object::Metadata::PrimaryKey class for more information.
1636
1637       primary_key_column_names [NAMES]
1638           Get or set the names of the columns that make up the table's
1639           primary key.  NAMES should be a list or reference to an array of
1640           column names.
1641
1642           Returns the list of column names (in list context) or a reference
1643           to the array of column names (in scalar context).
1644
1645           This method is just a shortcut for the code:
1646
1647               $meta->primary_key->column_names(...);
1648
1649           See the primary_key method and the
1650           Rose::DB::Object::Metadata::PrimaryKey class for more information.
1651
1652       primary_key_generator [CODEREF]
1653           Get or set the subroutine used to generate new primary key values
1654           for the primary key columns of this table.  The subroutine will be
1655           passed two arguments: the current metadata object and the
1656           Rose::DB-derived object that points to the current database.
1657
1658           The subroutine is expected to return a list of values, one for each
1659           primary key column.  The values must be in the same order as the
1660           corresponding columns returned by primary_key_columns. (i.e., the
1661           first value belongs to the first column returned by
1662           primary_key_columns, the second value belongs to the second column,
1663           and so on.)
1664
1665       primary_key_sequence_names [NAMES]
1666           Get or set the list of database sequence names used to populate the
1667           primary key columns.  The sequence names must be in the same order
1668           as the primary_key_columns.  NAMES may be a list or reference to an
1669           array of sequence names.  Returns a list (in list context) or
1670           reference to the array (in scalar context) of sequence names.
1671
1672           If you do not set this value, it will be derived for you based on
1673           the name of the primary key columns.  In the common case, you do
1674           not need to be concerned about this method.  If you are using the
1675           built-in SERIAL or AUTO_INCREMENT types in your database for your
1676           primary key columns, everything should just work.
1677
1678       prime_caches [PARAMS]
1679           By default, secondary metadata derived from the attributes of this
1680           object is created and cached on demand.  Call this method to pre-
1681           cache this metadata all at once.  This method is useful when
1682           running in an environment like mod_perl where it's advantageous to
1683           load as much data as possible on start-up.
1684
1685           PARAMS are name/value pairs.  Valid parameters are:
1686
1687           db DB
1688               A Rose::DB-derived object used to determine which data source
1689               the cached metadata will be generated on behalf of.  (Each data
1690               source has its own set of cached metadata.)  This parameter is
1691               optional.  If it is not passed, then the Rose::DB-derived
1692               object returned by the init_db method for this class will be
1693               used instead.
1694
1695       relationship NAME [, RELATIONSHIP | HASHREF]
1696           Get or set the relationship named NAME.  If just NAME is passed,
1697           the Rose::DB::Object::Metadata::Relationship-derived relationship
1698           object for that NAME is returned.  If no such relationship exists,
1699           undef is returned.
1700
1701           If both NAME and RELATIONSHIP are passed, then RELATIONSHIP must be
1702           a Rose::DB::Object::Metadata::Relationship-derived object.
1703           RELATIONSHIP has its name set to NAME, and is then stored as the
1704           relationship metadata object for NAME, replacing any existing
1705           relationship.
1706
1707           If both NAME and HASHREF are passed, then the combination of NAME
1708           and HASHREF must form a name/value pair suitable for passing to the
1709           add_relationships method.  The new relationship specified by NAME
1710           and HASHREF replaces any existing relationship.
1711
1712       relationships [ARGS]
1713           Get or set the full list of relationships.  If ARGS are passed, the
1714           relationship list is cleared and then ARGS are passed to the
1715           add_relationships method.
1716
1717           Returns a list of relationship objects in list context, or a
1718           reference to an array of relationship objects in scalar context.
1719
1720       replace_column NAME, [COLUMN | HASHREF]
1721           Replace the column named NAME with a newly constructed column.
1722           This method is equivalent to deleting any existing column named
1723           NAME and then adding a new one.  In other words, this:
1724
1725               $meta->replace_column($name => $value);
1726
1727           is equivalent to this:
1728
1729               $meta->delete_column($name);
1730               $meta->add_column($name => $value);
1731
1732           The value of the new column may be a
1733           Rose::DB::Object::Metadata::Column-derived object or a reference to
1734           a hash suitable for passing to the add_columns method.
1735
1736       schema [SCHEMA]
1737           Get or set the database schema for this class.  This setting will
1738           override any setting in the db object.  Use this method only if you
1739           know that the class will always point to a specific schema,
1740           regardless of what the Rose::DB-derived database handle object
1741           specifies.
1742
1743       setup PARAMS
1744           Set up all the metadata for this class in a single method call.
1745           This method is a convenient shortcut.  It does its work by
1746           delegating to other methods.
1747
1748           The setup() method does nothing if the metadata object is already
1749           initialized (according to the is_initialized method).
1750
1751           PARAMS are method/arguments pairs.  In general, the following
1752           transformations apply.
1753
1754           Given a method/arrayref pair:
1755
1756               METHOD => [ ARG1, ARG2 ]
1757
1758           The arguments will be removed from their array reference and passed
1759           to METHOD like this:
1760
1761               $meta->METHOD(ARG1, ARG2);
1762
1763           Given a method/value pair:
1764
1765               METHOD => ARG
1766
1767           The argument will be passed to METHOD as-is:
1768
1769               $meta->METHOD(ARG);
1770
1771           There are two exceptions to these transformation rules.
1772
1773           If METHOD is "unique_key" or "add_unique_key" and the argument is a
1774           reference to an array containing only non-reference values, then
1775           the array reference itself is passed to the method.  For example,
1776           this pair:
1777
1778               unique_key => [ 'name', 'status' ]
1779
1780           will result in this method call:
1781
1782               $meta->unique_key([ 'name', 'status' ]);
1783
1784           (Note that these method names are singular.  This exception does
1785           not apply to the plural variants, "unique_keys" and
1786           "add_unique_keys".)
1787
1788           If METHOD is "helpers", then the argument is dereferenced (if it's
1789           an array reference) and passed on to Rose::DB::Object::Helpers.
1790           That is, this:
1791
1792               helpers => [ 'load_or_save', { load_or_insert => 'find_or_create' } ],
1793
1794           Is equivalent to having this in your class:
1795
1796               use Rose::DB::Object::Helpers
1797                 'load_or_save', { load_or_insert => 'find_or_create' };
1798
1799           Method names may appear more than once in PARAMS.  The methods are
1800           called in the order that they appear in PARAMS, with the exception
1801           of the initialize (or auto_initialize) method, which is always
1802           called last.
1803
1804           If "initialize" is not one of the method names, then it will be
1805           called automatically (with no arguments) at the end.  If you do not
1806           want to pass any arguments to the initialize method, standard
1807           practice is to omit it.
1808
1809           If "auto_initialize" is one of the method names, then the
1810           auto_initialize method will be called instead of the initialize
1811           method.  This is useful if you want to manually set up a few pieces
1812           of metadata, but want the auto-initialization system to set up the
1813           rest.
1814
1815           The name "auto" is considered equivalent to "auto_initialize", but
1816           any arguments are ignored unless they are encapsulated in a
1817           reference to an array.  For example, these are equivalent:
1818
1819               $meta->setup(
1820                 table => 'mytable',
1821                 # Call auto_initialize() with no arguments
1822                 auto_initialize => [],
1823               );
1824
1825               # This is another way of writing the same thing as the above
1826               $meta->setup(
1827                 table => 'mytable',
1828                 # The value "1" is ignored because it's not an arrayref,
1829                 # so auto_initialize() will be called with no arguments.
1830                 auto => 1,
1831               );
1832
1833           Finally, here's a full example of a setup() method call followed by
1834           the equivalent "long-hand" implementation.
1835
1836               $meta->setup
1837               (
1838                 table => 'colors',
1839
1840                 columns =>
1841                 [
1842                   code => { type => 'character', length => 3, not_null => 1 },
1843                   name => { type => 'varchar', length => 255 },
1844                 ],
1845
1846                 primary_key_columns => [ 'code' ],
1847
1848                 unique_key => [ 'name' ],
1849               );
1850
1851           The setup() method call above is equivalent to the following code:
1852
1853               unless($meta->is_initialized)
1854               {
1855                 $meta->table('colors');
1856
1857                 $meta->columns(
1858                 [
1859                   code => { type => 'character', length => 3, not_null => 1 },
1860                   name => { type => 'varchar', length => 255 },
1861                 ]);
1862
1863                 $meta->primary_key_columns('code');
1864
1865                 $meta->unique_key([ 'name' ]),
1866
1867                 $meta->initialize;
1868               }
1869
1870       sql_qualify_column_names_on_load [BOOL]
1871           Get or set a boolean value that indicates whether or not to prefix
1872           the columns with the table name in the SQL used to load() an
1873           object.  The default value is false.
1874
1875           For example, here is some SQL that might be used to load an object,
1876           as generated with sql_qualify_column_names_on_load set to false:
1877
1878               SELECT id, name FROM dogs WHERE id = 5;
1879
1880           Now here's how it would look with sql_qualify_column_names_on_load
1881           set to true:
1882
1883               SELECT dogs.id, dogs.name FROM dogs WHERE dogs.id = 5;
1884
1885       table [TABLE]
1886           Get or set the name of the database table.  The table name should
1887           not include any sort of prefix to indicate the schema or catalog.
1888
1889       unique_key KEY
1890           This method is an alias for add_unique_keys.
1891
1892       unique_keys KEYS
1893           Get or set the list of unique keys for this table.  If KEYS is
1894           passed, any existing keys will be deleted and KEYS will be passed
1895           to the add_unique_keys method.
1896
1897           Returns the list (in list context) or reference to an array (in
1898           scalar context) of Rose::DB::Object::Metadata::UniqueKey objects.
1899
1900       unique_key_by_name NAME
1901           Return the unique key named NAME, or undef if no such key exists.
1902
1903       unique_keys_column_names
1904           Returns a list (in list context) or a reference to an array (in
1905           scalar context) or references to arrays of the column names that
1906           make up each unique key.  That is:
1907
1908               # Example of a scalar context return value
1909               [ [ 'id', 'name' ], [ 'code' ] ]
1910
1911               # Example of a list context return value
1912               ([ 'id', 'name' ], [ 'code' ])
1913

AUTO-INITIALIZATION METHODS

1915       These methods are associated with the auto-initialization process.
1916       Calling any of them will cause the auto-initialization code to be
1917       loaded, which costs memory.  This should be considered an
1918       implementation detail for now.
1919
1920       Regardless of the implementation details, you should still avoid
1921       calling any of these methods unless you plan to do some auto-
1922       initialization.  No matter how generic they may seem (e.g.,
1923       default_perl_indent), rest assured that none of these methods are
1924       remotely useful unless you are doing auto-initialization.
1925
1926   CLASS METHODS
1927       default_perl_braces [STYLE]
1928           Get or set the default brace style used in the Perl code generated
1929           by the perl_* object methods.  STYLE must be either "k&r" or "bsd".
1930           The default value is "k&r".
1931
1932       default_perl_indent [INT]
1933           Get or set the default integer number of spaces used for each level
1934           of indenting in the Perl code generated by the perl_* object
1935           methods.  The default value is 4.
1936
1937       default_perl_unique_key_style [STYLE]
1938           Get or set the default style of the unique key initialization used
1939           in the Perl code generated by the perl_unique_keys_definition
1940           method.  STYLE must be "array" or "object".  The default value is
1941           "array".  See the perl_unique_keys_definition method for examples
1942           of the two styles.
1943
1944   OBJECT METHODS
1945       auto_generate_columns
1946           Auto-generate Rose::DB::Object::Metadata::Column-derived objects
1947           for each column in the table.  Note that this method does not
1948           modify the metadata object's list of columns.  It simply returns a
1949           list of column objects.    Calling this method in void context will
1950           cause a fatal error.
1951
1952           Returns a list of column objects (in list context) or a reference
1953           to a hash of column objects, keyed by column name (in scalar
1954           context).  The hash reference return value is intended to allow
1955           easy modification of the auto-generated column objects.  Example:
1956
1957               $columns = $meta->auto_generate_columns; # hash ref return value
1958
1959               # Make some changes
1960               $columns->{'name'}->length(10); # set different length
1961               $columns->{'age'}->default(5);  # set different default
1962               ...
1963
1964               # Finally, set the column list
1965               $meta->columns(values %$columns);
1966
1967           If you do not want to modify the auto-generated columns, you should
1968           use the auto_init_columns method instead.
1969
1970           A fatal error will occur unless at least one column was auto-
1971           generated.
1972
1973       auto_generate_foreign_keys [PARAMS]
1974           Auto-generate Rose::DB::Object::Metadata::ForeignKey objects for
1975           each foreign key in the table.  Note that this method does not
1976           modify the metadata object's list of foreign_keys.  It simply
1977           returns a list of foreign key objects.  Calling this method in void
1978           context will cause a fatal error.  A warning will be issued if a
1979           foreign key could not be generated because no
1980           Rose::DB::Object-derived class was found for the foreign table.
1981
1982           PARAMS are optional name/value pairs.  If a "no_warnings" parameter
1983           is passed with a true value, then the warning described above will
1984           not be issued.
1985
1986           Returns a list of foreign key objects (in list context) or a
1987           reference to an array of foreign key objects (in scalar context).
1988
1989           If you do not want to inspect or modify the auto-generated foreign
1990           keys, but just want them to populate the metadata object's
1991           foreign_keys list, you should use the auto_init_foreign_keys method
1992           instead.
1993
1994           Note: This method works with MySQL only when using the InnoDB
1995           storage type.
1996
1997       auto_generate_unique_keys
1998           Auto-generate Rose::DB::Object::Metadata::UniqueKey objects for
1999           each unique key in the table.  Note that this method does not
2000           modify the metadata object's list of unique_keys.  It simply
2001           returns a list of unique key objects.  Calling this method in void
2002           context will cause a fatal error.
2003
2004           Returns a list of unique key objects (in list context) or a
2005           reference to an array of unique key objects (in scalar context).
2006
2007           If you do not want to inspect or modify the auto-generated unique
2008           keys, but just want them to populate the metadata object's
2009           unique_keys list, you should use the auto_init_unique_keys method
2010           instead.
2011
2012       auto_retrieve_primary_key_column_names
2013           Returns a list (in list context) or a reference to an array (in
2014           scalar context) of the names of the columns that make up the
2015           primary key for this table.  Note that this method does not modify
2016           the metadata object's primary_key.  It simply returns a list of
2017           column names.  Calling this method in void context will cause a
2018           fatal error.
2019
2020           This method is rarely called explicitly.  Usually, you will use the
2021           auto_init_primary_key_columns method instead.
2022
2023           A fatal error will occur unless at least one column name can be
2024           retrieved.
2025
2026           (This method uses the word "retrieve" instead of "generate" like
2027           its sibling methods above because it does not generate objects; it
2028           simply returns column names.)
2029
2030       auto_initialize [PARAMS]
2031           Auto-initialize the entire metadata object.  This is a wrapper for
2032           the individual "auto_init_*" methods, and is roughly equivalent to
2033           this:
2034
2035             $meta->auto_init_columns(...);
2036             $meta->auto_init_primary_key_columns;
2037             $meta->auto_init_unique_keys(...);
2038             $meta->auto_init_foreign_keys(...);
2039             $meta->auto_init_relationships(...);
2040             $meta->initialize;
2041
2042           PARAMS are optional name/value pairs.  When applicable, these
2043           parameters are passed on to each of the "auto_init_*" methods.
2044           Valid parameters are:
2045
2046           include_map_class_relationships BOOL
2047               By default, if a class is a map class (according to the
2048               is_map_class method of the convention manager), then
2049               relationships directly between that class and the current class
2050               will not be created.  Set this parameter to true to allow such
2051               relationships to be created.
2052
2053               Note: If some classes that are not actually map classes are
2054               being skipped, you should not use this parameter to force them
2055               to be included.  It's more appropriate to make your own custom
2056               convention manager subclass and then override the is_map_class
2057               method to make the correct determination.
2058
2059           replace_existing BOOL
2060               If true, then the auto-generated columns, unique keys, foreign
2061               keys, and relationships entirely replace any existing columns,
2062               unique keys, foreign keys, and relationships, respectively.
2063
2064           stay_connected BOOL
2065               If true, then any database connections retained by the metadata
2066               objects belonging to the various Rose::DB::Object-derived
2067               classes participating in the auto-initialization process will
2068               remain connected until an explicit call to the clear_all_dbs
2069               class method.
2070
2071           with_foreign_keys BOOL
2072               A boolean value indicating whether or not foreign key metadata
2073               will be auto-initialized.  Defaults to true.
2074
2075           with_relationships [ BOOL | ARRAYREF ]
2076               A boolean value or a reference to an array of relationship type
2077               names.  If set to a simple boolean value, then the all types of
2078               relationships will be considered for auto-initialization.  If
2079               set to a list of relationship type names, then only
2080               relationships of those types will be considered.  Defaults to
2081               true.
2082
2083           with_unique_keys BOOL
2084               A boolean value indicating whether or not unique key metadata
2085               will be auto-initialized.  Defaults to true.
2086
2087           During initialization, if one of the columns has a method name that
2088           clashes with a reserved method name, then the
2089           column_alias_generator will be called to remedy the situation by
2090           aliasing the column.  If the name still conflicts, then a fatal
2091           error will occur.
2092
2093           A fatal error will occur if auto-initialization fails.
2094
2095       auto_init_columns [PARAMS]
2096           Auto-generate Rose::DB::Object::Metadata::Column objects for this
2097           table, then populate the list of columns.  PARAMS are optional
2098           name/value pairs.  If a "replace_existing" parameter is passed with
2099           a true value, then the auto-generated columns replace any existing
2100           columns.  Otherwise, any existing columns are left as-is.
2101
2102       auto_init_foreign_keys [PARAMS]
2103           Auto-generate Rose::DB::Object::Metadata::ForeignKey objects for
2104           this table, then populate the list of foreign_keys.  PARAMS are
2105           optional name/value pairs.  If a "replace_existing" parameter is
2106           passed with a true value, then the auto-generated foreign keys
2107           replace any existing foreign keys.  Otherwise, any existing foreign
2108           keys are left as-is.
2109
2110           Note: This method works with MySQL only when using the InnoDB
2111           storage type.
2112
2113       auto_init_primary_key_columns
2114           Auto-retrieve the names of the columns that make up the primary key
2115           for this table, then populate the list of primary_key_column_names.
2116           A fatal error will occur unless at least one primary key column
2117           name could be retrieved.
2118
2119       auto_init_relationships [PARAMS]
2120           Auto-populate the list of relationships for this class.  PARAMS are
2121           optional name/value pairs.
2122
2123           include_map_class_relationships BOOL
2124               By default, if a class is a map class (according to the
2125               is_map_class method of the convention manager), then
2126               relationships directly between that class and the current class
2127               will not be created.  Set this parameter to true to allow such
2128               relationships to be created.
2129
2130               Note: If some classes that are not actually map classes are
2131               being skipped, you should not use this parameter to force them
2132               to be included.  It's more appropriate to make your own custom
2133               convention manager subclass and then override the is_map_class
2134               method to make the correct determination.
2135
2136           replace_existing BOOL
2137               If true, then the auto-generated relationships replace any
2138               existing relationships.  Otherwise, any existing relationships
2139               are left as-is.
2140
2141           relationship_types ARRAYREF
2142               A reference to an array of relationship type names.  Only
2143               relationships of these types will be created.  If omitted,
2144               relationships of all types will be created.  If passed a
2145               reference to an empty array, no relationships will be created.
2146
2147           types ARRAYREF
2148               This is an alias for the "relationship_types" parameter.
2149
2150           with_relationships [ BOOL | ARRAYREF ]
2151               This is the same as the "relationship_types" parameter except
2152               that it also accepts a boolean value.  If true, then
2153               relationships of all types will be created.  If false, then
2154               none will be created.
2155
2156           Assume that this class is called "Local" and any hypothetical
2157           foreign class is called "Remote".  Relationships are auto-generated
2158           according to the following rules.
2159
2160           •   A one-to-many relationship is created between "Local" and
2161               "Remote" if "Remote" has a foreign key that points to "Local".
2162               This is not done, however, if "Local" has a one-to-one
2163               relationship pointing to "Remote" that references the same
2164               columns as the foreign key in "Remote" that points to "Local",
2165               or if "Local" is a map class (according to the convention
2166               manager's is_map_class method).  The relationship name is
2167               generated by the convention manager's
2168               auto_relationship_name_one_to_many method.
2169
2170           •   A many-to-many relationship is created between "Local" and
2171               "Remote" if there exists a map class (according to the
2172               convention manager's is_map_class method) with exactly two
2173               foreign keys, one pointing to Local and on pointing to
2174               "Remote".  The relationship name is generated by creating a
2175               plural version of the name of the foreign key in the map class
2176               that points to "Remote".
2177
2178           In all cases, if there is an existing, semantically identical
2179           relationship, then a new relationship is not auto-generated.
2180           Similarly, any existing methods with the same names are not
2181           overridden by methods associated with auto-generated relationships.
2182
2183       auto_init_unique_keys [PARAMS]
2184           Auto-generate Rose::DB::Object::Metadata::UniqueKey objects for
2185           this table, then populate the list of unique_keys.  PARAMS are
2186           name/value pairs.  If a "replace_existing" parameter is passed with
2187           a true value, then the auto-generated unique keys replace any
2188           existing unique keys.  Otherwise, any existing unique keys are left
2189           as-is.
2190
2191       column_alias_generator [CODEREF]
2192           Get or set the code reference to the subroutine used to alias
2193           columns have, or would generate, one or more method names that
2194           clash with reserved method names.
2195
2196           The subroutine should take two arguments: the metadata object and
2197           the column name.  The $_ variable will also be set to the column
2198           name at the time of the call.  The subroutine should return an
2199           alias for the column.
2200
2201           The default column alias generator simply appends the string "_col"
2202           to the end of the column name and returns that as the alias.
2203
2204       foreign_key_name_generator [CODEREF]
2205           Get or set the code reference to the subroutine used to generate
2206           foreign key names.  Note: This code will only be called if the
2207           convention_manager's auto_foreign_key_name method fails to (or
2208           declines to) produce a defined foreign key name.
2209
2210           The subroutine should take two arguments: a metadata object and a
2211           Rose::DB::Object::Metadata::ForeignKey object.  It should return a
2212           name for the foreign key.
2213
2214           Each foreign key must have a name that is unique within the class.
2215           By default, this name will also be the name of the method generated
2216           to access the object referred to by the foreign key, so it must be
2217           unique among method names in the class as well.
2218
2219           The default foreign key name generator uses the following
2220           algorithm:
2221
2222           If the foreign key has only one column, and if the name of that
2223           column ends with an underscore and the name of the referenced
2224           column, then that part of the column name is removed and the
2225           remaining string is used as the foreign key name.  For example,
2226           given the following tables:
2227
2228               CREATE TABLE categories
2229               (
2230                 id  SERIAL PRIMARY KEY,
2231                 ...
2232               );
2233
2234               CREATE TABLE products
2235               (
2236                 category_id  INT REFERENCES categories (id),
2237                 ...
2238               );
2239
2240           The foreign key name would be "category", which is the name of the
2241           referring column ("category_id") with an underscore and the name of
2242           the referenced column ("_id") removed from the end of it.
2243
2244           If the foreign key has only one column, but it does not meet the
2245           criteria described above, then "_object" is appended to the name of
2246           the referring column and the resulting string is used as the
2247           foreign key name.
2248
2249           If the foreign key has more than one column, then the foreign key
2250           name is generated by replacing double colons and case-transitions
2251           in the referenced class name with underscores, and then converting
2252           to lowercase.  For example, if the referenced table is fronted by
2253           the class My::TableOfStuff, then the generated foreign key name
2254           would be "my_table_of_stuff".
2255
2256           In all of the scenarios above, if the generated foreign key name is
2257           still not unique within the class, then a number is appended to the
2258           end of the name.  That number is incremented until the name is
2259           unique.
2260
2261           In practice, rather than setting a custom foreign key name
2262           generator, it's usually easier to simply set the foreign key
2263           name(s) manually after auto-initializing the foreign keys (but
2264           before calling initialize or auto_initialize, of course).
2265
2266       perl_class_definition [PARAMS]
2267           Auto-initialize the columns, primary key, foreign keys, and unique
2268           keys, then return the Perl source code for a complete
2269           Rose::DB::Object-derived class definition.  PARAMS are optional
2270           name/value pairs that may include the following:
2271
2272           braces STYLE
2273               The brace style to use in the generated Perl code.  STYLE must
2274               be either "k&r" or "bsd".  The default value is determined by
2275               the return value of the default_perl_braces class method.
2276
2277           indent INT
2278               The integer number of spaces to use for each level of indenting
2279               in the generated Perl code.  The default value is determined by
2280               the return value of the default_perl_indent class method.
2281
2282           isa CLASSES
2283               The list of base classes to use in the generated class
2284               definition.  CLASSES should be a single class name, or a
2285               reference to an array of class names.  The default base class
2286               is Rose::DB::Object.
2287
2288           use_setup BOOL
2289               If true, then the generated class definition will include a
2290               call to the setup method.  Otherwise, the generated code will
2291               contain individual methods calls.  The default value for this
2292               parameter is true; the setup method is the recommended way to
2293               initialize a class.
2294
2295           This method is simply a wrapper (with some glue) for the following
2296           methods: perl_columns_definition,
2297           perl_primary_key_columns_definition, perl_unique_keys_definition,
2298           perl_foreign_keys_definition, and perl_relationships_definition.
2299           The "braces" and "indent" parameters are passed on to these other
2300           methods.
2301
2302           Here's a complete example, which also serves as an example of the
2303           individual "perl_*" methods that this method wraps.  First, the
2304           table definitions.
2305
2306               CREATE TABLE topics
2307               (
2308                 id    SERIAL PRIMARY KEY,
2309                 name  VARCHAR(32)
2310               );
2311
2312               CREATE TABLE codes
2313               (
2314                 k1    INT NOT NULL,
2315                 k2    INT NOT NULL,
2316                 k3    INT NOT NULL,
2317                 name  VARCHAR(32),
2318
2319                 PRIMARY KEY(k1, k2, k3)
2320               );
2321
2322               CREATE TABLE products
2323               (
2324                 id             SERIAL PRIMARY KEY,
2325                 name           VARCHAR(32) NOT NULL,
2326                 flag           BOOLEAN NOT NULL DEFAULT 't',
2327                 status         VARCHAR(32) DEFAULT 'active',
2328                 topic_id       INT REFERENCES topics (id),
2329                 fk1            INT,
2330                 fk2            INT,
2331                 fk3            INT,
2332                 last_modified  TIMESTAMP,
2333                 date_created   TIMESTAMP,
2334
2335                 FOREIGN KEY (fk1, fk2, fk3) REFERENCES codes (k1, k2, k3)
2336               );
2337
2338               CREATE TABLE prices
2339               (
2340                 id          SERIAL PRIMARY KEY,
2341                 product_id  INT REFERENCES products (id),
2342                 price       DECIMAL(10,2) NOT NULL DEFAULT 0.00,
2343                 region      CHAR(2) NOT NULL DEFAULT 'US'
2344               );
2345
2346           First we'll auto-initialize the classes.
2347
2348               package Code;
2349               use base qw(Rose::DB::Object);
2350               __PACKAGE__->meta->auto_initialize;
2351
2352               package Category;
2353               use base qw(Rose::DB::Object);
2354               # Explicit table name required because the class name
2355               # does not match up with the table name in this case.
2356               __PACKAGE__->meta->table('topics');
2357               __PACKAGE__->meta->auto_initialize;
2358
2359               package Product;
2360               use base qw(Rose::DB::Object);
2361               __PACKAGE__->meta->auto_initialize;
2362
2363               package Price;
2364               use base qw(Rose::DB::Object);
2365               __PACKAGE__->meta->auto_initialize;
2366
2367           Now we'll print the "Product" class definition;
2368
2369               print Product->meta->perl_class_definition(braces => 'bsd',
2370                                                          indent => 2);
2371
2372           The output looks like this:
2373
2374             package Product;
2375
2376             use strict;
2377
2378             use base qw(Rose::DB::Object);
2379
2380             __PACKAGE__->meta->setup
2381             (
2382               table => 'products',
2383
2384               columns =>
2385               [
2386                 id            => { type => 'integer', not_null => 1 },
2387                 name          => { type => 'varchar', length => 32, not_null => 1 },
2388                 flag          => { type => 'boolean', default => 'true', not_null => 1 },
2389                 status        => { type => 'varchar', default => 'active', length => 32 },
2390                 topic_id      => { type => 'integer' },
2391                 fk1           => { type => 'integer' },
2392                 fk2           => { type => 'integer' },
2393                 fk3           => { type => 'integer' },
2394                 last_modified => { type => 'timestamp' },
2395                 date_created  => { type => 'timestamp' },
2396               ],
2397
2398               primary_key_columns => [ 'id' ],
2399
2400               foreign_keys =>
2401               [
2402                 code =>
2403                 {
2404                   class => 'Code',
2405                   key_columns =>
2406                   {
2407                     fk1 => 'k1',
2408                     fk2 => 'k2',
2409                     fk3 => 'k3',
2410                   },
2411                 },
2412
2413                 topic =>
2414                 {
2415                   class => 'Category',
2416                   key_columns =>
2417                   {
2418                     topic_id => 'id',
2419                   },
2420                 },
2421               ],
2422
2423               relationships =>
2424               [
2425                 prices =>
2426                 {
2427                   class       => 'Price',
2428                   key_columns => { id => 'product_id' },
2429                   type        => 'one to many',
2430                 },
2431               ],
2432             );
2433
2434             1;
2435
2436           Here's the output when the "use_setup" parameter is explicitly set
2437           to false.
2438
2439               print Product->meta->perl_class_definition(braces    => 'bsd',
2440                                                          indent    => 2,
2441                                                          use_setup => 0);
2442
2443           Note that this approach is not recommended, but exists for
2444           historical reasons.
2445
2446             package Product;
2447
2448             use strict;
2449
2450             use base qw(Rose::DB::Object);
2451
2452             __PACKAGE__->meta->table('products');
2453
2454             __PACKAGE__->meta->columns
2455             (
2456               id            => { type => 'integer', not_null => 1 },
2457               name          => { type => 'varchar', length => 32, not_null => 1 },
2458               flag          => { type => 'boolean', default => 'true', not_null => 1 },
2459               status        => { type => 'varchar', default => 'active', length => 32 },
2460               topic_id      => { type => 'integer' },
2461               fk1           => { type => 'integer' },
2462               fk2           => { type => 'integer' },
2463               fk3           => { type => 'integer' },
2464               last_modified => { type => 'timestamp' },
2465               date_created  => { type => 'timestamp' },
2466             );
2467
2468             __PACKAGE__->meta->primary_key_columns([ 'id' ]);
2469
2470             __PACKAGE__->meta->foreign_keys
2471             (
2472               code =>
2473               {
2474                 class => 'Code',
2475                 key_columns =>
2476                 {
2477                   fk1 => 'k1',
2478                   fk2 => 'k2',
2479                   fk3 => 'k3',
2480                 },
2481               },
2482
2483               topic =>
2484               {
2485                 class => 'Category',
2486                 key_columns =>
2487                 {
2488                   topic_id => 'id',
2489                 },
2490               },
2491             );
2492
2493             __PACKAGE__->meta->relationships
2494             (
2495               prices =>
2496               {
2497                 class       => 'Price',
2498                 key_columns => { id => 'product_id' },
2499                 type        => 'one to many',
2500               },
2501             );
2502
2503             __PACKAGE__->meta->initialize;
2504
2505             1;
2506
2507           See the auto-initialization section for more discussion of Perl
2508           code generation.
2509
2510       perl_columns_definition [PARAMS]
2511           Auto-initialize the columns (if necessary), then return the Perl
2512           source code that is equivalent to the auto-initialization.  PARAMS
2513           are optional name/value pairs that may include the following:
2514
2515           braces STYLE
2516               The brace style to use in the generated Perl code.  STYLE must
2517               be either "k&r" or "bsd".  The default value is determined by
2518               the return value of the default_perl_braces class method.
2519
2520           for_setup BOOL
2521               If true, then the generated Perl code will be a
2522               method/arguments pair suitable for use as a parameter to setup
2523               method.  The default is false.
2524
2525           indent INT
2526               The integer number of spaces to use for each level of indenting
2527               in the generated Perl code.  The default value is determined by
2528               the return value of the default_perl_indent class method.
2529
2530           To see examples of the generated code, look in the documentation
2531           for the perl_class_definition method.
2532
2533       perl_foreign_keys_definition [PARAMS]
2534           Auto-initialize the foreign keys (if necessary), then return the
2535           Perl source code that is equivalent to the auto-initialization.
2536           PARAMS are optional name/value pairs that may include the
2537           following:
2538
2539           braces STYLE
2540               The brace style to use in the generated Perl code.  STYLE must
2541               be either "k&r" or "bsd".  The default value is determined by
2542               the return value of the default_perl_braces class method.
2543
2544           for_setup BOOL
2545               If true, then the generated Perl code will be a
2546               method/arguments pair suitable for use as a parameter to setup
2547               method.  The default is false.
2548
2549           indent INT
2550               The integer number of spaces to use for each level of indenting
2551               in the generated Perl code.  The default value is determined by
2552               the return value of the default_perl_indent class method.
2553
2554           To see examples of the generated code, look in the documentation
2555           for the perl_class_definition method.
2556
2557       perl_manager_class [ PARAMS | BASE_NAME ]
2558           Returns a Perl class definition for a
2559           Rose::DB::Object::Manager-derived class to manage objects of this
2560           class.  If a single string is passed, it is taken as the value of
2561           the "base_name" parameter.  PARAMS are optional name/value pairs
2562           that may include the following:
2563
2564           base_name NAME
2565               The value of the base_name parameter that will be passed to the
2566               call to Rose::DB::Object::Manager's make_manager_methods
2567               method.  Defaults to the return value of the convention
2568               manager's auto_manager_base_name method.
2569
2570           class CLASS
2571               The name of the manager class.  Defaults to the return value of
2572               the convention manager's auto_manager_class_name method.
2573
2574           isa [ LIST | ARRAYREF ]
2575               The name of a single class or a reference to an array of class
2576               names to be included in the @ISA array for the manager class.
2577               One of these classes must inherit from
2578               Rose::DB::Object::Manager.  Defaults to the return value of the
2579               "default_manager_base_class()" object method.
2580
2581           For example, given this class:
2582
2583               package Product;
2584
2585               use Rose::DB::Object;
2586               our @ISA = qw(Rose::DB::Object);
2587               ...
2588
2589               print Product->meta->perl_manager_class(
2590                                      class     => 'Prod::Mgr',
2591                                      base_name => 'prod');
2592
2593           The following would be printed:
2594
2595               package Prod::Mgr;
2596
2597               use Rose::DB::Object::Manager;
2598               our @ISA = qw(Rose::DB::Object::Manager);
2599
2600               sub object_class { 'Product' }
2601
2602               __PACKAGE__->make_manager_methods('prod');
2603
2604               1;
2605
2606       perl_primary_key_columns_definition
2607           Auto-initialize the primary key column names (if necessary), then
2608           return the Perl source code that is equivalent to the auto-
2609           initialization.
2610
2611           See the larger example in the documentation for the
2612           perl_class_definition method to see what the generated Perl code
2613           looks like.
2614
2615       perl_relationships_definition [PARAMS]
2616           Auto-initialize the relationships (if necessary), then return the
2617           Perl source code that is equivalent to the auto-initialization.
2618           PARAMS are optional name/value pairs that may include the
2619           following:
2620
2621           braces STYLE
2622               The brace style to use in the generated Perl code.  STYLE must
2623               be either "k&r" or "bsd".  The default value is determined by
2624               the return value of the default_perl_braces class method.
2625
2626           for_setup BOOL
2627               If true, then the generated Perl code will be a
2628               method/arguments pair suitable for use as a parameter to setup
2629               method.  The default is false.
2630
2631           indent INT
2632               The integer number of spaces to use for each level of indenting
2633               in the generated Perl code.  The default value is determined by
2634               the return value of the default_perl_indent class method.
2635
2636           To see examples of the generated code, look in the documentation
2637           for the perl_class_definition method.
2638
2639       perl_table_definition [PARAMS]
2640           Auto-initialize the table name (if necessary), then return the Perl
2641           source code that is equivalent to the auto-initialization.  PARAMS
2642           are optional name/value pairs that may include the following:
2643
2644           braces STYLE
2645               The brace style to use in the generated Perl code.  STYLE must
2646               be either "k&r" or "bsd".  The default value is determined by
2647               the return value of the default_perl_braces class method.
2648
2649           for_setup BOOL
2650               If true, then the generated Perl code will be a
2651               method/arguments pair suitable for use as a parameter to setup
2652               method.  The default is false.
2653
2654           indent INT
2655               The integer number of spaces to use for each level of indenting
2656               in the generated Perl code.  The default value is determined by
2657               the return value of the default_perl_indent class method.
2658
2659           To see examples of the generated code, look in the documentation
2660           for the perl_class_definition method.
2661
2662       perl_unique_keys_definition [PARAMS]
2663           Auto-initialize the unique keys, then return the Perl source code
2664           that is equivalent to the auto-initialization.  PARAMS are optional
2665           name/value pairs that may include the following:
2666
2667           braces STYLE
2668               The brace style to use in the generated Perl code.  STYLE must
2669               be either "k&r" or "bsd".  The default value is determined by
2670               the return value of the default_perl_braces class method.
2671
2672           for_setup BOOL
2673               If true, then the generated Perl code will be a
2674               method/arguments pair suitable for use as a parameter to setup
2675               method.  The default is false.
2676
2677           indent INT
2678               The integer number of spaces to use for each level of indenting
2679               in the generated Perl code.  The default value is determined by
2680               the return value of the default_perl_indent class method.
2681
2682           style STYLE
2683               Determines the style the initialization used in the generated
2684               Perl code.  STYLE must be "array" or "object".  The default is
2685               determined by the return value of the class method
2686               default_perl_unique_key_style.
2687
2688               The "array" style passes references to arrays of column names:
2689
2690                 __PACKAGE__->meta->unique_keys
2691                 (
2692                   [ 'id', 'name' ],
2693                   [ 'flag', 'status' ],
2694                 );
2695
2696               The "object" style sets unique keys using calls to the
2697               Rose::DB::Object::Metadata::UniqueKey constructor:
2698
2699                 __PACKAGE__->meta->unique_keys
2700                 (
2701                   Rose::DB::Object::Metadata::UniqueKey->new(
2702                     name    => 'products_id_key',
2703                     columns => [ 'id', 'name' ]),
2704
2705                   Rose::DB::Object::Metadata::UniqueKey->new(
2706                     name    => 'products_flag_key',
2707                     columns => [ 'flag', 'status' ]),
2708                 );
2709

AUTHOR

2711       John C. Siracusa (siracusa@gmail.com)
2712

LICENSE

2714       Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This
2715       program is free software; you can redistribute it and/or modify it
2716       under the same terms as Perl itself.
2717
2718
2719
2720perl v5.34.0                      2022-01-21     Rose::DB::Object::Metadata(3)
Impressum