1Rose::DB::Object::MetadUastear(3C)ontributed Perl DocumeRnotsaet:i:oDnB::Object::Metadata(3)
2
6 Rose::DB::Object::Metadata - Database object metadata.
7
9 use Rose::DB::Object::Metadata;
10 $meta = Rose::DB::Object::Metadata->new(class => 'Product');
12 # ...or...
13 $meta = Rose::DB::Object::Metadata->for_class('Product');
14 #
16 # Auto-initialization
17 #
18 $meta->table('products'); # optional if class name ends with "::Product"
20 $meta->auto_initialize;
21 #
23 # ...or manual setup
24 #
25 $meta->setup
27 (
28 table => 'products',
29 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 status =>
38 {
39 type => 'varchar',
40 check_in => [ 'active', 'inactive' ],
41 default => 'inactive',
42 },
43 start_date => { type => 'datetime' },
45 end_date => { type => 'datetime' },
46 date_created => { type => 'timestamp', default => 'now' },
48 last_modified => { type => 'timestamp', default => 'now' },
49 ],
50 unique_key => 'name',
52 foreign_keys =>
54 [
55 category =>
56 {
57 class => 'Category',
58 key_columns =>
59 {
60 category_id => 'id',
61 }
62 },
63 ],
64 relationships =>
66 [
67 prices =>
68 {
69 type => 'one to many',
70 class => 'Price',
71 column_map => { id => 'id_product' },
72 },
73 ],
74 );
75 #
77 # ...or even more verbose manual setup (old-style, not recommended)
78 #
79 $meta->table('products');
81 $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 status =>
90 {
91 type => 'varchar',
92 check_in => [ 'active', 'inactive' ],
93 default => 'inactive',
94 },
95 start_date => { type => 'datetime' },
97 end_date => { type => 'datetime' },
98 date_created => { type => 'timestamp', default => 'now' },
100 last_modified => { type => 'timestamp', default => 'now' },
101 );
102 $meta->unique_key('name');
104 $meta->foreign_keys
106 (
107 category =>
108 {
109 class => 'Category',
110 key_columns =>
111 {
112 category_id => 'id',
113 }
114 },
115 );
116 $meta->relationships
118 (
119 prices =>
120 {
121 type => 'one to many',
122 class => 'Price',
123 column_map => { id => 'id_product' },
124 },
125 );
126 ...
128
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 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 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 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 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 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 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 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
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 The example of auto-initialization in the synopsis above is the most
192 succinct variant:
193 $meta->auto_initialize;
195 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 Caveats
203 Start-Up Cost
204 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 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 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 Detail
227 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 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 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 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 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 Now look at the metadata that MySQL 4 stores internally for this table:
261 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 Note the following divergences from the "CREATE TABLE" statement.
274 • The "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 • The "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 • The "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 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 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 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 # Make a first pass at column setup
317 $meta->auto_init_columns;
318 # Account for inaccuracies in DBD::mysql's column info by
320 # replacing incorrect column definitions with new ones.
321 # Fix CHAR(6) column that shows up as VARCHAR(6)
323 $meta->column(code => { type => 'char', length => 6 });
324 # Fix BIT(5) column that shows up as TINYINT(1)
326 $meta->column(bits => { type => 'bits', bits => 5, default => 101 });
327 # Fix BOOLEAN column that shows up as TINYINT(1)
329 $meta->column(flag => { type => 'boolean', default => 1 });
330 # Do everything else
332 $meta->auto_initialize;
333 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 Maintenance
339 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 "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 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 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 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 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 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
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 clear_all_dbs
396 Clears the db attribute of the metadata object for each registered
397 class.
398 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 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 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 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 The default mapping of type names to class names is:
423 scalar => Rose::DB::Object::Metadata::Column::Scalar
425 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 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 bits => Rose::DB::Object::Metadata::Column::Bitfield
439 bitfield => Rose::DB::Object::Metadata::Column::Bitfield
440 bool => Rose::DB::Object::Metadata::Column::Boolean
442 boolean => Rose::DB::Object::Metadata::Column::Boolean
443 int => Rose::DB::Object::Metadata::Column::Integer
445 integer => Rose::DB::Object::Metadata::Column::Integer
446 tinyint => Rose::DB::Object::Metadata::Column::Integer
448 smallint => Rose::DB::Object::Metadata::Column::Integer
449 mediumint => Rose::DB::Object::Metadata::Column::Integer
450 bigint => Rose::DB::Object::Metadata::Column::BigInt
452 serial => Rose::DB::Object::Metadata::Column::Serial
454 bigserial => Rose::DB::Object::Metadata::Column::BigSerial
455 enum => Rose::DB::Object::Metadata::Column::Enum
457 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 'double precision' =>
465 Rose::DB::Object::Metadata::Column::DoublePrecision
466 time => Rose::DB::Object::Metadata::Column::Time
468 interval => Rose::DB::Object::Metadata::Column::Interval
469 date => Rose::DB::Object::Metadata::Column::Date
471 datetime => Rose::DB::Object::Metadata::Column::Datetime
472 timestamp => Rose::DB::Object::Metadata::Column::Timestamp
473 timestamptz =>
475 Rose::DB::Object::Metadata::Column::TimestampWithTimeZone
476 'timestamp with time zone' =>
478 Rose::DB::Object::Metadata::Column::TimestampWithTimeZone
479 'datetime year to fraction' =>
481 Rose::DB::Object::Metadata::Column::DatetimeYearToFraction
482 'datetime year to fraction(1)' =>
484 Rose::DB::Object::Metadata::Column::DatetimeYearToFraction1
485 'datetime year to fraction(2)' =>
487 Rose::DB::Object::Metadata::Column::DatetimeYearToFraction2
488 'datetime year to fraction(3)' =>
490 Rose::DB::Object::Metadata::Column::DatetimeYearToFraction3
491 'datetime year to fraction(4)' =>
493 Rose::DB::Object::Metadata::Column::DatetimeYearToFraction4
494 'datetime year to fraction(5)' =>
496 Rose::DB::Object::Metadata::Column::DatetimeYearToFraction5
497 'timestamp with time zone' =>
499 Rose::DB::Object::Metadata::Column::Timestamp
500 'timestamp without time zone' =>
502 Rose::DB::Object::Metadata::Column::Timestamp
503 'datetime year to second' =>
505 Rose::DB::Object::Metadata::Column::DatetimeYearToSecond
506 'datetime year to minute' =>
508 Rose::DB::Object::Metadata::Column::DatetimeYearToMinute
509 'datetime year to month' =>
511 Rose::DB::Object::Metadata::Column::DatetimeYearToMonth
512 'epoch' => Rose::DB::Object::Metadata::Column::Epoch
514 'epoch hires' => Rose::DB::Object::Metadata::Column::Epoch::HiRes
515 array => Rose::DB::Object::Metadata::Column::Array
517 set => Rose::DB::Object::Metadata::Column::Set
518 chkpass => Rose::DB::Object::Metadata::Column::Pg::Chkpass
520 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 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 If a CLASS is passed, then NAME is mapped to CLASS.
531 convention_manager_classes [MAP]
533 Get or set the hash that maps names to
534 Rose::DB::Object::ConventionManager-derived class names.
535 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 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 The default mapping of names to classes is:
546 default => Rose::DB::Object::ConventionManager
548 null => Rose::DB::Object::ConventionManager::Null
549 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 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 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 default_manager_base_class()
564 object method to override this value for a specific metadata
565 object.
566 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 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 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 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 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 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 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 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 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 The default mapping of type names to class names is:
617 '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 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 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
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 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
646 add_column ARGS
647 This is an alias for the add_columns method.
648 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 If an argument is a subclass of Rose::DB::Object::Metadata::Column,
656 it is added as-is.
657 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 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 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 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 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 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 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 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 If the "methods" and "add_methods" keys are both set, a fatal error
700 will occur.
701 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 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 Example:
715 $meta->add_columns
717 (
718 # Add a scalar column
719 'name',
720 # 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 # Add by name/hashref pair with explicit method types
728 age => { type => 'int', default => 5, methods => [ 'get', 'set' ] },
729 # 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 # Add by name/hashref pair with additional method type and name
740 size => { type => 'int', add_methods => { 'set' => 'set_my_size' } },
741 # 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 # Add a column object directly
752 Rose::DB::Object::Metadata::Column::Date->new(
753 name => 'start_date'),
754 );
755 add_nonpersistent_column ARGS
757 This is an alias for the add_nonpersistent_columns method.
758 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 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 Foreign keys can be specified in ARGS in several ways.
769 If an argument is a Rose::DB::Object::Metadata::ForeignKey object
771 (or subclass thereof), it is added as-is.
772 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 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 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 If the "methods" and "add_methods" keys are both set, a fatal error
792 will occur.
793 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 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 Example:
805 $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 # 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 # 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 # 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 # Add a foreign key object directly
844 Rose::DB::Object::Metadata::ForeignKey->new(...),
845 );
846 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 add_primary_key_column COLUMN
855 This method is an alias for add_primary_key_columns.
856 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 add_relationship ARGS
862 This is an alias for the add_relationships method.
863 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 Relationships can be specified in ARGS in several ways.
870 If an argument is a subclass of
872 Rose::DB::Object::Metadata::Relationship, it is added as-is.
873 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 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 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 If the "methods" and "add_methods" keys are both set, a fatal error
893 will occur.
894 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 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 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 Example:
909 $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 # 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 # 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 # 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 # Add a relationship object directly
950 Rose::DB::Object::Metadata::Relationship::OneToOne->new(...),
951 );
952 add_unique_key KEY
954 This method is an alias for add_unique_keys.
955 add_unique_keys KEYS
957 Add new unique keys specified by KEYS. Unique keys can be
958 specified in KEYS in two ways.
959 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 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 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 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 $meta->alias_column(save => 'save_flag');
981 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 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 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 CREATE TABLE test (d DATETIME YEAR TO SECOND);
1001 INSERT INTO test (d) VALUES (CURRENT);
1002 This is valid Informix SQL and will insert a row with the current
1004 date and time into the "test" table.
1005 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 $sth = $dbh->prepare('INSERT INTO test (d) VALUES (?)');
1011 $sth->execute('CURRENT'); # Error!
1012 What you'll end up with is an error like this:
1014 DBD::Informix::st execute failed: SQL: -1262: Non-numeric
1016 character in datetime or interval.
1017 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 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 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 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 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 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 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 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 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 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 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 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 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 Returns a list of column objects in list context, or a reference to
1093 an array of column objects in scalar context.
1094 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 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 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 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 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 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 column_names
1128 Returns a list (in list context) or a reference to an array (in
1129 scalar context) of column names.
1130 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 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 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 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 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 Defaults to the value returned by the
1160 default_column_undef_overrides_default class method.
1161 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 If undef is passed, then a
1167 Rose::DB::Object::ConventionManager::Null object is stored instead.
1168 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 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 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 See the Rose::DB::Object::ConventionManager documentation for more
1186 information on convention managers.
1187 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 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 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 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 delete_column NAME
1213 Delete the column named NAME.
1214 delete_columns
1216 Delete all of the columns.
1217 delete_column_type_class TYPE
1219 Delete the type/class mapping entry for the column type TYPE.
1220 delete_convention_manager_class NAME
1222 Delete the name/class mapping entry for the convention manager
1223 class mapped to NAME.
1224 delete_nonpersistent_column NAME
1226 Delete the non-persistent column named NAME.
1227 delete_nonpersistent_columns
1229 Delete all of the nonpersistent_columns.
1230 delete_relationship NAME
1232 Delete the relationship named NAME.
1233 delete_relationships
1235 Delete all of the relationships.
1236 delete_relationship_type_class TYPE
1238 Delete the type/class mapping entry for the relationship type TYPE.
1239 delete_unique_keys
1241 Delete all of the unique key definitions.
1242 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 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 Valid values of MODE are:
1258 carp
1260 Call Carp::carp with the value of the object error as an
1261 argument.
1262 cluck
1264 Call Carp::cluck with the value of the object error as an
1265 argument.
1266 confess
1268 Call Carp::confess with the value of the object error as an
1269 argument.
1270 croak
1272 Call Carp::croak with the value of the object error as an
1273 argument.
1274 fatal
1276 An alias for the "croak" mode.
1277 return
1279 Return a value that indicates that an error has occurred, as
1280 described in the documentation for each method.
1281 In all cases, the object's error attribute will also contain the
1283 error message.
1284 first_column
1286 Returns the first column, determined by the order that columns were
1287 added, or undef if there are no columns.
1288 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 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 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 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 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 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 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 If a primary_key_generator is defined, it will be called (passed
1326 this metadata object and the DB) and its value returned.
1327 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 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 Here's an example of a unique index that has a predicate:
1341 CREATE UNIQUE INDEX my_idx ON mytable (mycolumn) WHERE mycolumn > 123;
1343 The predicate in this case is "WHERE mycolumn > 123".
1345 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 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 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 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 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 ARGS, if any, are passed to the call to make_methods that actually
1378 creates the methods.
1379 If auto_prime_caches is true, then the prime_caches method will be
1381 called at the end of the initialization process.
1382 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 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 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 ARGS are name/value pairs which are passed on to the other
1402 "make_*_methods" calls. They are all optional. Valid ARGS are:
1403 • "preserve_existing"
1405 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 • "replace_existing"
1410 If set to a true value, override any existing method with the
1412 same name.
1413 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 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 • "preserve_existing"
1422 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 • "replace_existing"
1427 If set to a true value, override any existing method with the
1429 same name.
1430 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 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 • "preserve_existing"
1443 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 • "replace_existing"
1448 If set to a true value, override any existing method with the
1450 same name.
1451 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 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 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 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 • "preserve_existing"
1477 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 • "replace_existing"
1482 If set to a true value, override any existing method with the
1484 same name.
1485 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 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 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 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 method_column METHOD
1513 Returns the name of the column manipulated by the method named
1514 METHOD.
1515 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 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 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 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 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 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 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 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 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 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 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 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 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 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 pk_columns [COLUMNS]
1598 This is an alias for the primary_key_columns method.
1599 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 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 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 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 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 This method is just a shortcut for the code:
1631 $meta->primary_key->columns(...);
1633 See the primary_key method and the
1635 Rose::DB::Object::Metadata::PrimaryKey class for more information.
1636 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 Returns the list of column names (in list context) or a reference
1643 to the array of column names (in scalar context).
1644 This method is just a shortcut for the code:
1646 $meta->primary_key->column_names(...);
1648 See the primary_key method and the
1650 Rose::DB::Object::Metadata::PrimaryKey class for more information.
1651 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 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 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 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 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 PARAMS are name/value pairs. Valid parameters are:
1686 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 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 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 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 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 Returns a list of relationship objects in list context, or a
1718 reference to an array of relationship objects in scalar context.
1719 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 $meta->replace_column($name => $value);
1726 is equivalent to this:
1728 $meta->delete_column($name);
1730 $meta->add_column($name => $value);
1731 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 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 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 The setup() method does nothing if the metadata object is already
1749 initialized (according to the is_initialized method).
1750 PARAMS are method/arguments pairs. In general, the following
1752 transformations apply.
1753 Given a method/arrayref pair:
1755 METHOD => [ ARG1, ARG2 ]
1757 The arguments will be removed from their array reference and passed
1759 to METHOD like this:
1760 $meta->METHOD(ARG1, ARG2);
1762 Given a method/value pair:
1764 METHOD => ARG
1766 The argument will be passed to METHOD as-is:
1768 $meta->METHOD(ARG);
1770 There are two exceptions to these transformation rules.
1772 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 unique_key => [ 'name', 'status' ]
1779 will result in this method call:
1781 $meta->unique_key([ 'name', 'status' ]);
1783 (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 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 helpers => [ 'load_or_save', { load_or_insert => 'find_or_create' } ],
1793 Is equivalent to having this in your class:
1795 use Rose::DB::Object::Helpers
1797 'load_or_save', { load_or_insert => 'find_or_create' };
1798 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 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 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 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 $meta->setup(
1820 table => 'mytable',
1821 # Call auto_initialize() with no arguments
1822 auto_initialize => [],
1823 );
1824 # 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 Finally, here's a full example of a setup() method call followed by
1834 the equivalent "long-hand" implementation.
1835 $meta->setup
1837 (
1838 table => 'colors',
1839 columns =>
1841 [
1842 code => { type => 'character', length => 3, not_null => 1 },
1843 name => { type => 'varchar', length => 255 },
1844 ],
1845 primary_key_columns => [ 'code' ],
1847 unique_key => [ 'name' ],
1849 );
1850 The setup() method call above is equivalent to the following code:
1852 unless($meta->is_initialized)
1854 {
1855 $meta->table('colors');
1856 $meta->columns(
1858 [
1859 code => { type => 'character', length => 3, not_null => 1 },
1860 name => { type => 'varchar', length => 255 },
1861 ]);
1862 $meta->primary_key_columns('code');
1864 $meta->unique_key([ 'name' ]),
1866 $meta->initialize;
1868 }
1869 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 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 SELECT id, name FROM dogs WHERE id = 5;
1879 Now here's how it would look with sql_qualify_column_names_on_load
1881 set to true:
1882 SELECT dogs.id, dogs.name FROM dogs WHERE dogs.id = 5;
1884 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 unique_key KEY
1890 This method is an alias for add_unique_keys.
1891 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 Returns the list (in list context) or reference to an array (in
1898 scalar context) of Rose::DB::Object::Metadata::UniqueKey objects.
1899 unique_key_by_name NAME
1901 Return the unique key named NAME, or undef if no such key exists.
1902 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 # Example of a scalar context return value
1909 [ [ 'id', 'name' ], [ 'code' ] ]
1910 # Example of a list context return value
1912 ([ 'id', 'name' ], [ 'code' ])
1913
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 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 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 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 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 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 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 $columns = $meta->auto_generate_columns; # hash ref return value
1958 # Make some changes
1960 $columns->{'name'}->length(10); # set different length
1961 $columns->{'age'}->default(5); # set different default
1962 ...
1963 # Finally, set the column list
1965 $meta->columns(values %$columns);
1966 If you do not want to modify the auto-generated columns, you should
1968 use the auto_init_columns method instead.
1969 A fatal error will occur unless at least one column was auto-
1971 generated.
1972 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 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 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 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 Note: This method works with MySQL only when using the InnoDB
1995 storage type.
1996 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 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 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 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 This method is rarely called explicitly. Usually, you will use the
2021 auto_init_primary_key_columns method instead.
2022 A fatal error will occur unless at least one column name can be
2024 retrieved.
2025 (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 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 $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 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 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 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 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 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 with_foreign_keys BOOL
2072 A boolean value indicating whether or not foreign key metadata
2073 will be auto-initialized. Defaults to true.
2074 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 with_unique_keys BOOL
2084 A boolean value indicating whether or not unique key metadata
2085 will be auto-initialized. Defaults to true.
2086 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 A fatal error will occur if auto-initialization fails.
2094 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 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 Note: This method works with MySQL only when using the InnoDB
2111 storage type.
2112 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 auto_init_relationships [PARAMS]
2120 Auto-populate the list of relationships for this class. PARAMS are
2121 optional name/value pairs.
2122 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 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 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 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 types ARRAYREF
2148 This is an alias for the "relationship_types" parameter.
2149 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 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 • 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 • 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 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 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 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 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 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 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 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 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 The default foreign key name generator uses the following
2220 algorithm:
2221 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 CREATE TABLE categories
2229 (
2230 id SERIAL PRIMARY KEY,
2231 ...
2232 );
2233 CREATE TABLE products
2235 (
2236 category_id INT REFERENCES categories (id),
2237 ...
2238 );
2239 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 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 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 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 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 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 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 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 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 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 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 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 CREATE TABLE topics
2307 (
2308 id SERIAL PRIMARY KEY,
2309 name VARCHAR(32)
2310 );
2311 CREATE TABLE codes
2313 (
2314 k1 INT NOT NULL,
2315 k2 INT NOT NULL,
2316 k3 INT NOT NULL,
2317 name VARCHAR(32),
2318 PRIMARY KEY(k1, k2, k3)
2320 );
2321 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 FOREIGN KEY (fk1, fk2, fk3) REFERENCES codes (k1, k2, k3)
2336 );
2337 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 First we'll auto-initialize the classes.
2347 package Code;
2349 use base qw(Rose::DB::Object);
2350 __PACKAGE__->meta->auto_initialize;
2351 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 package Product;
2360 use base qw(Rose::DB::Object);
2361 __PACKAGE__->meta->auto_initialize;
2362 package Price;
2364 use base qw(Rose::DB::Object);
2365 __PACKAGE__->meta->auto_initialize;
2366 Now we'll print the "Product" class definition;
2368 print Product->meta->perl_class_definition(braces => 'bsd',
2370 indent => 2);
2371 The output looks like this:
2373 package Product;
2375 use strict;
2377 use base qw(Rose::DB::Object);
2379 __PACKAGE__->meta->setup
2381 (
2382 table => 'products',
2383 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 primary_key_columns => [ 'id' ],
2399 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 topic =>
2414 {
2415 class => 'Category',
2416 key_columns =>
2417 {
2418 topic_id => 'id',
2419 },
2420 },
2421 ],
2422 relationships =>
2424 [
2425 prices =>
2426 {
2427 class => 'Price',
2428 key_columns => { id => 'product_id' },
2429 type => 'one to many',
2430 },
2431 ],
2432 );
2433 1;
2435 Here's the output when the "use_setup" parameter is explicitly set
2437 to false.
2438 print Product->meta->perl_class_definition(braces => 'bsd',
2440 indent => 2,
2441 use_setup => 0);
2442 Note that this approach is not recommended, but exists for
2444 historical reasons.
2445 package Product;
2447 use strict;
2449 use base qw(Rose::DB::Object);
2451 __PACKAGE__->meta->table('products');
2453 __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 __PACKAGE__->meta->primary_key_columns([ 'id' ]);
2469 __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 topic =>
2484 {
2485 class => 'Category',
2486 key_columns =>
2487 {
2488 topic_id => 'id',
2489 },
2490 },
2491 );
2492 __PACKAGE__->meta->relationships
2494 (
2495 prices =>
2496 {
2497 class => 'Price',
2498 key_columns => { id => 'product_id' },
2499 type => 'one to many',
2500 },
2501 );
2502 __PACKAGE__->meta->initialize;
2504 1;
2506 See the auto-initialization section for more discussion of Perl
2508 code generation.
2509 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 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 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 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 To see examples of the generated code, look in the documentation
2531 for the perl_class_definition method.
2532 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 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 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 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 To see examples of the generated code, look in the documentation
2555 for the perl_class_definition method.
2556 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 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 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 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 For example, given this class:
2582 package Product;
2584 use Rose::DB::Object;
2586 our @ISA = qw(Rose::DB::Object);
2587 ...
2588 print Product->meta->perl_manager_class(
2590 class => 'Prod::Mgr',
2591 base_name => 'prod');
2592 The following would be printed:
2594 package Prod::Mgr;
2596 use Rose::DB::Object::Manager;
2598 our @ISA = qw(Rose::DB::Object::Manager);
2599 sub object_class { 'Product' }
2601 __PACKAGE__->make_manager_methods('prod');
2603 1;
2605 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 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 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 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 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 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 To see examples of the generated code, look in the documentation
2637 for the perl_class_definition method.
2638 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 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 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 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 To see examples of the generated code, look in the documentation
2660 for the perl_class_definition method.
2661 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 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 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 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 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 The "array" style passes references to arrays of column names:
2689 __PACKAGE__->meta->unique_keys
2691 (
2692 [ 'id', 'name' ],
2693 [ 'flag', 'status' ],
2694 );
2695 The "object" style sets unique keys using calls to the
2697 Rose::DB::Object::Metadata::UniqueKey constructor:
2698 __PACKAGE__->meta->unique_keys
2700 (
2701 Rose::DB::Object::Metadata::UniqueKey->new(
2702 name => 'products_id_key',
2703 columns => [ 'id', 'name' ]),
2704 Rose::DB::Object::Metadata::UniqueKey->new(
2706 name => 'products_flag_key',
2707 columns => [ 'flag', 'status' ]),
2708 );
2709
2711 John C. Siracusa (siracusa@gmail.com)
2712
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.
2717perl v5.36.0 2023-01-20 Rose::DB::Object::Metadata(3)