Rose::DB::Object::ConventionManager - Provide missing metadata by convention.
package My::Product; use Rose::DB::Object; our @ISA = qw(Rose::DB::Object); __PACKAGE__->meta->columns(...); __PACKAGE__->meta->initialize; # No table is set above, but look at this: the # convention manager provided one for us. print __PACKAGE__->meta->table; # "products" ## ## See the EXAMPLE section below for a more complete demonstration. ##
Each Rose::DB::Object-derived object has a convention manager that it uses to fill in missing metadata. The convention manager encapsulates a set of rules (conventions) for generating various pieces of metadata in the absence of explicitly specified values: table names, column names, etc.
Each Rose::DB::Object-derived class's convention manager object is stored in the convention_manager attribute of its Rose::DB::Object::Metadata (meta) object. Rose::DB::Object::ConventionManager is the default convention manager class.
The object method documentation below describes both the purpose of each convention manager method and the particular rules that Rose::DB::Object::ConventionManager follows to fulfill that purpose. Subclasses must honor the purpose of each method, but are free to use any rules they choose.
Note well: When reading the descriptions of the rules used by each convention manager method below, remember that only values that are missing will be set by the convention manager. Explicitly providing a value for a piece of metadata obviates the need for the convention manager to generate one.
If insufficient information is available, or if the convention manager simply declines to fulfill a request, undef may be returned from any metadata-generating method.
In the documentation, the adjectives "local" and "foreign" are used to distinguish between the things that belong to the the convention manager's class and the class on "the other side" of the inter-table relationship, respectively.
Although the object method documentation below includes all the information required to understand the default conventions, it's also quite spread out. What follows is a summary of the default conventions. Some details have necessarily been omitted or glossed over for the sake of brevity, of course. But this summary should give you a good starting point for further exploration.
Here's a brief summary of the default conventions as implemented in Rose::DB::Object::ConventionManager.
Examples: products, street_address, date_created, vendor_id.
products
street_address
date_created
vendor_id
Examples: products, vendors, codes, customer_details, employee_addresses.
vendors
codes
customer_details
employee_addresses
Examples: Product, Vendor, Code, CustomerDetails, EmployeeAddress.
Product
Vendor
Code
CustomerDetails
EmployeeAddress
For example, the primary key column name in the products table might be id or sku, but should not be product_id or product_sku.
id
sku
product_id
product_sku
Examples: product_sku, vendor_id, employee_address_id.
employee_address_id
Examples: product, vendor, code. These relationships may point to zero or one foreign object. The default method names generated from such relationships are based on the relationship names, so singular names make the most sense.
product
vendor
code
Examples: colors, prices, customer_details. These relationships may point to more than one foreign object. The default method names generated from such relationships are based on the relationship names, so plural names make the most sense.
colors
prices
See the auto_relationship, looks_like_map_class, and looks_like_map_table documentation for all the details.
Constructs a new object based on PARAMS, where PARAMS are name/value pairs. Any object attribute is a valid parameter name.
Given a foreign key name and an optional reference to a hash SPEC of the type passed to Rose::DB::Object::Metadata's add_foreign_keys method, return an appropriately constructed Rose::DB::Object::Metadata::ForeignKey object.
The foreign key's class name is generated by calling related_table_to_class, passing NAME and the convention manager's class as arguments. An attempt is made is load the class. If this fails, the foreign key's class name is not set.
The foreign key's key_columns are only set if both the "local" and "foreign" tables have single-column primary keys. The foreign class's primary key column name is used as the foreign column in the key_columns map. If there is a local column with the same name as the foreign key name, and if that column is aliased (making way for the foreign key method to use that name), then that is used as as the local column. If not, then the local column name is generated by joining the foreign key name and the foreign class's primary key column name with an underscore. If no column by that name exists, then the search is abandoned. Example:
Given these pieces:
Name Description Value --------- -------------------------------- ------- NAME Foreign key name vendor FCLASS Foreign class My::Vendor FPK Foreign primary key column name id
Consider column maps in this order:
Value Formula --------------------- ---------------------- { vendor => 'id' } { NAME => FPK } { vendor_id => 'id' } { <NAME>_<FPK> => FPK }
Given the name of a foreign class and an optional pre-existing foreign key name, return a name for the foreign key.
Calls plural_to_singular, passing the table name of the foreign class. Returns the current name if the call to plural_to_singular does not return a true value.
Given a table name and the name of the Rose::DB::Object-derived class that fronts it, return a base name suitable for use as the value of the base_name parameter to Rose::DB::Object::Manager's make_manager_methods method. The default implementation simply returns the table name.
base_name
Given the name of a Rose::DB::Object-derived class, returns a class name for a Rose::DB::Object::Manager-derived class to manage such objects. The default implementation simply appends "::Manager" to the Rose::DB::Object-derived class name.
Return the name of a "one to many" relationship that fetches objects from the specified TABLE and CLASS. The default implementation simply returns the table name.
Returns a reference to an array of primary key column names.
If a column named "id" exists, it is selected as the sole primary key column name. If not, the column name generated by joining the return value of class_to_table_singular with "_id" is considered. If no column with that name exists, then the first column (sorted alphabetically) whose type is "serial" is selected. If all of the above fails, then the first column is selected as the primary key column (assuming one exists).
Examples:
My::A->meta->columns(qw(a a_id id)); print My::A->meta->primary_key_columns; # "id" My::B->meta->columns(qw(b b_id foo)); print My::B->meta->primary_key_columns; # "a_id" My::D->meta->columns ( cnt => { type => 'int' }, dub => { type => 'serial' }, foo => { type => 'serial'}, a_id => { type => 'int' } ) print My::D->meta->primary_key_columns; # "dub" My::C->meta->columns(qw(foo bar baz)); print My::C->meta->primary_key_columns; # "foo"
Given a relationship name, a Rose::DB::Object::Metadata::Relationship-derived class name, and an optional reference to a hash SPEC of the type passed to Rose::DB::Object::Metadata's add_relationships method, return an appropriately constructed Rose::DB::Object::Metadata::Relationship-derived object.
If the relationship's type is "one to one" or "many to one", then the relationship's class name is generated by calling related_table_to_class, passing NAME and the convention manager's class as arguments. An attempt is made is load the class. If this fails, the relationship's class name is not set.
The column map for "one to one" and "many to one" relationships is generated using the same rules used to generate key_columns in the auto_foreign_key method.
If the relationship's type is "one to many" then the relationship's class name is generated by calling plural_to_singular on NAME, then passing that value along with the convention manager's class to the related_table_to_class method. An attempt is made is load the class. If this fails, the relationship's class name is not set.
The column map for a "one to many" relationship is only set if both the "local" and "foreign" tables have single-column primary keys. The following ordered list of combinations is considered.
Given:
Local class: My::Product Foreign class: My::Price Relationship: prices
Generate these pieces:
Name Description Value --------- --------------------------------- ------- LTABLE_S Local class_to_table_singular() product LPK Local primary key column name id FPK Foreign primary key column name id
Value Formula ---------------------- -------------------------- { id => 'product' } { LPK => LTABLE_S } { id => 'product_id' } { LPK => <LTABLE_S>_<PK> }
The first value whose foreign column actually exists in the foreign table is chosen.
If the relationship's type is "many to many" then the relationship's map_class is chosen from a list of possibilities. This list is generated by constructing singular and plural versions of the local and foreign class names (sans prefixes) and then joining them in various ways, all re-prefixed by the the class prefix of the convention manager's class. Example:
Local class: My::Product Foreign class: My::Color Relationship: colors
Name Description Value --------- --------------------------------- ------- PREFIX Local class prefix My:: LCLASS_S Unprefixed local class, singular Product LCLASS_P Unprefixed local class, plural Products FCLASS_S Unprefixed foreign class, singular Color FCLASS_P Unprefixed foreign class, plural Colors
Consider map class names in this order:
Value Formula --------------- --------------------- My::ProductsColorsMap <PREFIX><LCLASS_P><FCLASS_P>Map My::ProductColorMap <PREFIX><LCLASS_S><FCLASS_S>Map My::ColorsProductsMap <PREFIX><FCLASS_P><LCLASS_P>Map My::ColorProductMap <PREFIX><FCLASS_S><LCLASS_S>Map My::ProductsColors <PREFIX><LCLASS_P><FCLASS_P> My::ProductColors <PREFIX><LCLASS_S><FCLASS_P> My::ColorsProducts <PREFIX><FCLASS_P><LCLASS_P> My::ColorProducts <PREFIX><FCLASS_S><LCLASS_P> My::ColorMap <PREFIX><FCLASS_S>Map My::ColorsMap <PREFIX><FCLASS_P>Map My::ProductMap <PREFIX><LCLASS_S>Map My::ProductsMap <PREFIX><LCLASS_P>Map
The first class found that inherits from Rose::DB::Object and is loaded successfully will be chosen as the relationship's map_class.
Returns a table name for the convention manager's class.
Class names are singular and table names are plural. To build the table name, the class prefix is removed from the class name, transitions from lowercase letters or digits to uppercase letters have underscores inserted, and the whole thing is converted to lowercase.
Class Table ----------- -------- Product products My::Product products My::BigBox big_boxes My5HatPig my5_hat_pig
Get or set the Rose::DB::Object-derived class that this convention manager belongs to.
Given a class name, return the prefix, if any, before the last component of the namespace, including the final "::". If there is no prefix, an empty string is returned.
Class Prefix ----------- -------------- Product <empty string> My::Product My:: A::B::C::D A::B::C::
Given a class name, or the convention manager's class if omitted, return a plural version of the corresponding table name.
To do this, the output of the class_to_table_singular method is passed to a call to the singular_to_plural method. (The CLASS argument, if any, is passed to the call to class_to_table_singular.)
Class Table ----------- -------- Product products My::Product products My::Box boxes
Given a class name, or the convention manager's class if omitted, return a singular version of the corresponding table name.
Class Table ----------- -------- Product product My::Product product My::Box box
Returns true if CLASS is a map class used as part of a many to many relationship, false if it does not.
The default implementations returns true if CLASS is derived from Rose::DB::Object and its table name looks like a map table name according to the looks_like_map_table method and the looks_like_map_class method returns either true or undef.
Override this method to control which classes are considered map classes. Note that it may be called several times on the same class at various stages of that class's construction.
Given the class name CLASS, returns true if it looks like the name of a map class used as part of a many to many relationship, false (but defined) if it does not, and undef if it's unsure.
The default implementation returns true if CLASS is derived from Rose::DB::Object and has exactly two foreign keys. It returns false (but defined) if CLASS is derived from Rose::DB::Object and has been initialized (or if the foreign keys have been auto-initialized) and the CLASS has no deferred foreign keys. It returns undef otherwise.
Returns true if TABLE looks like the name of a mapping table used as part of a many to many relationship, false (but defined) if it does not, and undef if it's unsure.
The default implementation returns true if TABLE is in one of these forms:
Regex Examples ----------------------- ----------------------------- (\w+_){2,}map pig_toe_map, pig_skin_toe_map (\w+_)*\w+_(\w+_)*\w+s pig_toes, pig_skin_toe_jams (\w+_)*\w+s_(\w+_)*\w+s pigs_toes, pig_skins_toe_jams
It returns false otherwise.
Get or set the Rose::DB::Object::Metadata object associated with the class that this convention manager belongs to.
Returns the singular version of STRING. If a plural_to_singular_function is defined, then this method simply passes STRING to that function. Otherwise, "s" is removed from the end of STRING and the result is returned.
Get or set a reference to the function used to convert strings to singular. The function should take a single string as an argument and return a singular version of the string. This function is undefined by default.
Returns the plural version of STRING. If a singular_to_plural_function is defined, then this method simply passes STRING to that function. Otherwise, the following rules are used to form the plural.
* If STRING ends in "x", "ss", or "es", then "es" is appended.
* If STRING ends in "s" then it is returned as-is.
* Otherwise, "s" is appended.
Get or set a reference to the function used to convert strings to plural. The function should take a single string as an argument and return a plural version of the string. This function is undefined by default.
Given a table name and a local class name, return the name of the related class that fronts the table.
To do this, table_to_class is called with TABLE and the class_prefix of LOCAL_CLASS passed as arguments.
Table Local Class Related Class ----------- ------------ ---------------- prices My::Product My::Price big_hats A::B::FooBar A::B::BigHat a1_steaks Meat A1Steak
Given a table name and an optional class prefix, return the corresponding class name. The prefix will be appended to the class name, if present. The prefix should end in "::".
To do this, any letter that follows an underscore ("_") in the table name is replaced with an uppercase version of itself, and the underscore is removed.
Table Prefix Class ----------- ------ ----------- products My:: My::Product products <none> Product big_hats My:: My::BigHat my5_hat_pig <none> My5HatPig
These methods are not part of the public interface, but are supported for use by subclasses. Put another way, given an unknown object that "isa" Rose::DB::Object::Metadata::ConventionManager, there should be no expectation that the following methods exist. But subclasses, which know the exact class from which they inherit, are free to use these methods in order to implement the public API described above.
Override this method and return a reference to a function that takes a single string as an argument and returns a singular version of that string.
Override this method and return a reference to a function that takes a single string as an argument and returns a plural version of that string.
Much of the richness of a convention manager relies upon the quality of the singular_to_plural and plural_to_singular methods. The default implementations are primitive at best. For example, singular_to_plural will not correctly form the plural of the word "alumnus".
One easy way to improve this is by setting a custom singular_to_plural_function. Here's an example using the handy Lingua::EN::Inflect module:
package My::Product; ... use Lingua::EN::Inflect; $cm = __PACKAGE__->meta->convention_manager; $cm->singular_to_plural_function(\&Lingua::EN::Inflect::PL); print $cm->singular_to_plural('person'); # "people"
But that's a bit of a pain to do in every single class. An easier way to do it for all of your classes is to make a new Rose::DB::Object::Metadata subclass that overrides the init_convention_manager method, then make a Rose::DB::Object-derived base class that uses your new metadata class. Example:
package My::DB::Metadata; use Rose::DB::Object::Metadata; our @ISA = qw(Rose::DB::Object::Metadata); use Lingua::EN::Inflect; sub init_convention_manager { my $self = shift; # Let the base class make ths convention manager object my $cm = $self->SUPER::init_convention_manager(@_); # Set the new singular-to-plural function $cm->singular_to_plural_function(\&Lingua::EN::Inflect::PL); # Return the modified convention manager return $cm; } ... package My::DB::Object; use My::DB::Metadata; use Rose::DB::Object; our @ISA = qw(Rose::DB::Object); sub meta_class { 'My::DB::Metadata' } ... package My::Person; use My::DB::Object; our @ISA = qw(My::DB::Object); # The big pay-off: smart plurals! print __PACKAGE__->meta->table; # "people"
You might wonder why I don't use Lingua::EN::Inflect in Rose::DB::Object::ConventionManager to save you this effort. The answer is that the Rose::DB::Object::ConventionManager module adds almost a megabyte of memory overhead on my system. I'd rather not incur that overhead just for the sake of being more clever about naming conventions. Furthermore, as primitive as the default plural-forming is, at least it's deterministic. Guessing what Lingua::EN::Inflect will return is not always easy, and the results can change depending on which version Lingua::EN::Inflect you have installed.
Here's a complete example of nearly all of the major features of Rose::DB::Object::ConventionManager. Let's start with the database schema. (This example uses PostgreSQL, but any supported database with native foreign key support will work.)
CREATE TABLE vendors ( id SERIAL NOT NULL PRIMARY KEY, name VARCHAR(255) ); CREATE TABLE colors ( code CHAR(3) NOT NULL PRIMARY KEY, name VARCHAR(255) ); CREATE TABLE products ( id SERIAL NOT NULL PRIMARY KEY, name VARCHAR(255), vendor_id INT NOT NULL REFERENCES vendors (id) ); CREATE TABLE prices ( price_id SERIAL NOT NULL PRIMARY KEY, product_id INT NOT NULL REFERENCES products (id), region CHAR(2) NOT NULL DEFAULT 'US', price DECIMAL(10,2) NOT NULL ); CREATE TABLE product_colors ( id SERIAL NOT NULL PRIMARY KEY, product_id INT NOT NULL REFERENCES products (id), color_code CHAR(3) NOT NULL REFERENCES colors (code) );
Now the classes:
# Rose::DB subclass to handle the db connection package My::DB; use Rose::DB; our @ISA = qw(Rose::DB); My::DB->register_db ( type => 'default', domain => 'default', driver => 'Pg', database => 'test', username => 'postgres', ); ... # Common Rose::DB::Object-derived base class for the other objects package My::Object; use My::DB; use Rose::DB::Object; our @ISA = qw(Rose::DB::Object); sub init_db { My::DB->new } ... package My::Price; use My::Object; our @ISA = qw(My::Object); __PACKAGE__->meta->columns ( price_id => { type => 'serial', not_null => 1 }, product_id => { type => 'int' }, region => { type => 'char', length => 2, default => 'US' }, price => { type => 'decimal', precision => 10, scale => 2 }, ); __PACKAGE__->meta->foreign_keys(qw(product)); __PACKAGE__->meta->initialize; ... package My::Vendor; use My::Object; our @ISA = qw(My::Object); __PACKAGE__->meta->columns ( id => { type => 'serial', not_null => 1 }, name => { type => 'varchar', length => 255 }, ); __PACKAGE__->meta->initialize; ... package My::Color; use My::Object; our @ISA = qw(My::Object); __PACKAGE__->meta->columns ( code => { type => 'char', length => 3, not_null => 1 }, name => { type => 'varchar', length => 255 }, ); __PACKAGE__->meta->initialize; ... package My::Product; use My::Object; our @ISA = qw(My::Object); __PACKAGE__->meta->columns ( id => { type => 'serial', not_null => 1 }, name => { type => 'varchar', length => 255 }, vendor_id => { type => 'int' }, ); __PACKAGE__->meta->foreign_keys(qw(vendor)); __PACKAGE__->meta->relationships ( prices => { type => 'one to many' }, colors => { type => 'many to many' }, ); __PACKAGE__->meta->initialize; ... package My::ProductColors; use My::Object; our @ISA = qw(My::Object); __PACKAGE__->meta->columns(qw(id product_id color_code)); __PACKAGE__->meta->foreign_keys(qw(product color)); __PACKAGE__->meta->initialize;
Let's add some data:
INSERT INTO vendors (id, name) VALUES (1, 'V1'); INSERT INTO vendors (id, name) VALUES (2, 'V2'); INSERT INTO products (id, name, vendor_id) VALUES (1, 'A', 1); INSERT INTO products (id, name, vendor_id) VALUES (2, 'B', 2); INSERT INTO products (id, name, vendor_id) VALUES (3, 'C', 1); INSERT INTO prices (product_id, region, price) VALUES (1, 'US', 1.23); INSERT INTO prices (product_id, region, price) VALUES (1, 'DE', 4.56); INSERT INTO prices (product_id, region, price) VALUES (2, 'US', 5.55); INSERT INTO prices (product_id, region, price) VALUES (3, 'US', 5.78); INSERT INTO prices (product_id, region, price) VALUES (3, 'US', 9.99); INSERT INTO colors (code, name) VALUES ('CC1', 'red'); INSERT INTO colors (code, name) VALUES ('CC2', 'green'); INSERT INTO colors (code, name) VALUES ('CC3', 'blue'); INSERT INTO colors (code, name) VALUES ('CC4', 'pink'); INSERT INTO product_colors (product_id, color_code) VALUES (1, 'CC1'); INSERT INTO product_colors (product_id, color_code) VALUES (1, 'CC2'); INSERT INTO product_colors (product_id, color_code) VALUES (2, 'CC4'); INSERT INTO product_colors (product_id, color_code) VALUES (3, 'CC2'); INSERT INTO product_colors (product_id, color_code) VALUES (3, 'CC3');
Finally, the classes in action:
$p = My::Product->new(id => 1)->load; print $p->vendor->name, "\n"; # "V1" # "US: 1.23, DE: 4.56" print join(', ', map { $_->region .': '. $_->price } $p->prices), "\n"; # "red, green" print join(', ', map { $_->name } $p->colors), "\n";
Using Rose::DB::Object's auto-initialization feature, the Perl code can be reduced to an absurd degree. Given the same database schema and data shown in the example above, consider the following classes:
package My::Auto::Color; use base 'My::Object'; __PACKAGE__->meta->auto_initialize; ... package My::Auto::Price; use base 'My::Object'; __PACKAGE__->meta->auto_initialize; ... package My::Auto::ProductColors; use base 'My::Object'; __PACKAGE__->meta->auto_initialize; ... package My::Auto::Vendor; use base 'My::Object'; __PACKAGE__->meta->auto_initialize; ... package My::Auto::Product; use base 'My::Object'; __PACKAGE__->meta->auto_initialize;
Not a single table, column, foreign key, or relationship is specified, yet everything still works:
$p = My::Auto::Product->new(id => 1)->load; print $p->vendor->name, "\n"; # "V1" # "US: 1.23, DE: 4.56" print join(', ', map { $_->region .': '. $_->price } $p->prices), "\n"; # "red, green" print join(', ', map { $_->name } $p->colors), "\n";
More precisely, everything still works provided that you load all the of the related modules. For example, if you don't load My::Auto::Product but don't load My::Auto::Price (either from within the My::Auto::Product class or in your program itself), then the My::Auto::Product will not have a prices() method (since your program will have no knowledge of the My::Auto::Price class). Use the loader if you want to set up a bunch of related classes automatically without worrying about this kind of thing.
My::Auto::Product
My::Auto::Price
prices()
Anyway, I don't recommend this kind of extreme approach, but it is an effective demonstration of the power of the convention manager.
John C. Siracusa (siracusa@mindspring.com)
Copyright (c) 2006 by John C. Siracusa. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Rose::DB::Object, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Rose::DB::Object
CPAN shell
perl -MCPAN -e shell install Rose::DB::Object
For more information on module installation, please visit the detailed CPAN module installation guide.