NAME¶
Rose::DB::Object::ConventionManager - Provide missing metadata by convention.
SYNOPSIS¶
package My::Product;
use base 'Rose::DB::Object';
__PACKAGE__->meta->setup(columns => [ ... ]);
# 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.
##
DESCRIPTION¶
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 convention
manager's class and the class on "the other side" of the inter-table
relationship, respectively.
SUMMARY OF DEFAULT CONVENTIONS¶
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 simplified for the sake of brevity, 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.
- Table, column, foreign key, and relationship names are lowercase, with
underscores separating words.
- Examples: "products", "street_address",
"date_created", "vendor_id".
- Table names are plural.
- Examples: "products", "vendors", "codes",
"customer_details", "employee_addresses".
(This convention can be overridden via the tables_are_singular method.)
- Class names are singular, title-cased, with nothing separating
words.
- Examples: "Product", "Vendor", "Code",
"CustomerDetail", "EmployeeAddress".
- Primary key column names do not contain the table name.
- 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".
- Foreign key column names are made from the singular version of the
foreign table's name joined (with an underscore) to the foreign table's key
column name.
- Examples: "product_sku", "vendor_id",
"employee_address_id".
- One-to-one and many-to-one relationship names are singular.
- 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.
- One-to-many and many-to-many relationship names are plural.
- 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.
- Mapping tables and their associated classes that participate in
many-to-many relationships are named according a formula that combines the
names of the two classes/tables that are being linked.
- See the auto_relationship, looks_like_map_class, and looks_like_map_table
documentation for all the details.
CONSTRUCTOR¶
- new PARAMS
- Constructs a new object based on PARAMS, where PARAMS are name/value
pairs. Any object attribute is a valid parameter name.
OBJECT METHODS¶
- auto_column_method_name TYPE, COLUMN, NAME, OBJECT_CLASS
- Given a Rose::DB::Object::Metadata::Column column type, a
Rose::DB::Object::Metadata::Column object or column name, a default method
name, and a Rose::DB::Object-derived class name, return an appropriate
method name. The default implementation simply returns undef, relying on
the hard-coded default method-type-to-name mapping implemented in
Rose::DB::Object::Metadata's method_name_from_column method.
- auto_foreign_key NAME [, SPEC]
- 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 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 }
- auto_foreign_key_name FOREIGN_CLASS, CURRENT_NAME, KEY_COLUMNS,
USED_NAMES
- Given the name of a foreign class, the current foreign key name (if any),
a reference to a hash of key columns, and a reference to a hash whose keys
are foreign key names already used in this class, return a name for the
foreign key.
If there is more than one pair of columns in KEY_COLUMNS, then the name is
generated by calling plural_to_singular, passing the table name of the
foreign class. The CURRENT_NAME is used if the call to plural_to_singular
does not return a true value.
If there is just one pair of columns in KEY_COLUMNS, and if the name of the
local column ends with an underscore and the name of the referenced
column, then that part of the column name is removed and the remaining
string is used as the foreign key name. For example, given the following
tables:
CREATE TABLE categories
(
id SERIAL PRIMARY KEY,
...
);
CREATE TABLE products
(
category_id INT REFERENCES categories (id),
...
);
The foreign key name would be "category", which is the name of the
referring column ("category_id") with an underscore and the name
of the referenced column ("_id") removed from the end of it.
If the foreign key has only one column, but it does not meet the criteria
described above, then the name is generated by calling plural_to_singular,
passing the table name of the foreign class. The CURRENT_NAME is used if
the call to plural_to_singular does not return a true value.
If the name selected using the above techniques is in the USED_NAMES hash,
or is the same as that of an existing or potential method in the target
class, then the suffixes "_obj" and "_object" are
tried in that order. If neither of those suffixes resolves the situation,
then ascending numeric suffixes starting with "1" are tried
until a unique name is found.
- auto_manager_base_name TABLE, CLASS
- 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.
If no table is specified then the table name is derived from the current
class name by calling class_to_table_plural.
If tables_are_singular is true, then TABLE is passed to the
singular_to_plural method and the result is returned. Otherwise, TABLE is
returned as-is.
- auto_manager_base_class
- Return the class that all manager classes will default to inheriting from.
By default this will be Rose::DB::Object::Manager.
- auto_manager_class_name CLASS
- 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.
- auto_manager_method_name TYPE, BASE_NAME, OBJECT_CLASS
- Given the specified Rose::DB::Object::Manager method type, base name, and
object class return an appropriate manager method name. The default
implementation simply returns undef, relying on the hard-coded default
method-type-to-name mapping implemented in Rose::DB::Object::Manager's
make_manager_methods method.
- auto_relationship_name_many_to_many FK, MAPCLASS
- Return the name of a "many to many" relationship that fetches
objects from the table pointed to by the
Rose::DB::Object::Metadata::ForeignKey object FK by going through the
class MAPCLASS.
The default implementation passes the name of the table pointed to by FK
through the singular_to_plural method in order to build the name.
If the selected name is the name of an existing or potential method in the
target class, then the suffixes "_objs" and "_objects"
are tried in that order. If neither of those suffixes resolves the
situation, then ascending numeric suffixes starting with "1" are
tried until a unique name is found.
- auto_relationship_name_one_to_many TABLE, CLASS
- Return the name of a "one to many" relationship that fetches
objects from the specified TABLE and CLASS.
If tables_are_singular is true, then TABLE is passed to the
singular_to_plural method and the result is used as the name. Otherwise,
TABLE is used as-is.
If the selected name is the name of an existing or potential method in the
target class, then the suffixes "_objs" and "_objects"
are tried in that order. If neither of those suffixes resolves the
situation, then ascending numeric suffixes starting with "1" are
tried until a unique name is found.
- auto_relationship_name_one_to_one TABLE, CLASS
- Return the name of a "one to one" relationship that fetches an
object from the specified TABLE and CLASS. The default implementation
returns a singular version of the table name.
If the selected name is the name of an existing or potential method in the
target class, then the suffixes "obj_" and "_object"
are tried in that order. If neither of those suffixes resolves the
situation, then ascending numeric suffixes starting with "1" are
tried until a unique name is found.
- auto_primary_key_column_names
- 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"
- auto_relationship NAME, RELATIONSHIP_CLASS [, SPEC]
- 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
Consider column maps in this order:
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 class prefix of the convention manager's class.
Example:
Given:
Local class: My::Product
Foreign class: My::Color
Relationship: colors
Generate these pieces:
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.
- auto_table_name
- 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.
Examples:
Class Table
----------- --------
Product products
My::Product products
My::BigBox big_boxes
My5HatPig my5_hat_pig
- class [CLASS]
- Get or set the Rose::DB::Object-derived class that this convention manager
belongs to.
- class_prefix CLASS
- 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.
Examples:
Class Prefix
----------- --------------
Product <empty string>
My::Product My::
A::B::C::D A::B::C::
- class_to_table_plural [CLASS]
- 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.)
Examples:
Class Table
----------- --------
Product products
My::Product products
My::Box boxes
- class_to_table_singular [CLASS]
- Given a class name, or the convention manager's class if omitted, return a
singular version of the corresponding table name.
Examples:
Class Table
----------- --------
Product product
My::Product product
My::Box box
- force_lowercase [BOOL]
- Get or set a boolean value that indicates whether or not metadata entity
names should be forced to lowercase even when the related entity is
uppercase or mixed case. ("Metadata entities" are thing like
columns, relationships, and foreign keys.) The default value is
false.
- is_map_class CLASS
- 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.
- looks_like_map_class CLASS
- 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.
- looks_like_map_table TABLE
- 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.
- meta [META]
- Get or set the Rose::DB::Object::Metadata object associated with the class
that this convention manager belongs to.
- plural_to_singular STRING
- Returns the singular version of STRING. If a plural_to_singular_function
is defined, then this method simply passes STRING to that function.
Otherwise, the following rules are applied, case-insensitively.
* If STRING ends in "ies", then the "ies" is replaced
with "y".
* If STRING ends in "ses" then the "ses" is replaced
with "s".
* If STRING matches "/[aeiouy]ss$/i", it is returned unmodified.
For all other cases, the letter "s" is removed from the end of
STRING and the result is returned.
- plural_to_singular_function [CODEREF]
- 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.
- related_table_to_class TABLE, LOCAL_CLASS
- 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.
Examples:
Table Local Class Related Class
----------- ------------ ----------------
prices My::Product My::Price
big_hats A::B::FooBar A::B::BigHat
a1_steaks Meat A1Steak
- singular_to_plural STRING
- 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 applied, case-insensitively, to form
the plural.
* If STRING ends in "x", "ss", or "es", then
"es" is appended.
* If STRING ends in "y" then the "y" is replaced with
"ies".
* If STRING ends in "s" then it is returned as-is.
* Otherwise, "s" is appended.
- singular_to_plural_function [CODEREF]
- 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.
- table_singular
- Let TABLE be the return value of the table method called on the meta
attribute of this object.
If tables_are_singular is true, then TABLE is returned as-is. Otherwise,
TABLE is passed to the plural_to_singular method and the result is
returned. Otherwise, TABLE is returned as-is.
- table_plural
- Let TABLE be the return value of the table method called on the meta
attribute of this object.
If tables_are_singular is true, then TABLE is passed to the
singular_to_plural method and the result is returned. Otherwise, TABLE is
returned as-is.
- table_to_class TABLE [, PREFIX]
- 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.
Examples:
Table Prefix Class
----------- ------ -----------
products My:: My::Product
products <none> Product
big_hats My:: My::BigHat
my5_hat_pig <none> My5HatPig
- tables_are_singular [BOOL]
- Get or set a boolean value that indicates whether or not table names are
expected to be singular. The default value is false, meaning that table
names are expected to be plural.
PROTECTED API¶
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.
- init_plural_to_singular_function
- 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.
- init_singular_to_plural_function
- 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.
TIPS AND TRICKS¶
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 Lingua::EN::Inflect 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.
EXAMPLE¶
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 base '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 base 'Rose::DB::Object';
sub init_db { My::DB->new }
...
package My::Price;
use base 'My::Object';
__PACKAGE__->meta->setup
(
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 },
],
foreign_keys => [ 'product' ],
);
...
package My::Vendor;
use base 'My::Object';
__PACKAGE__->meta->setup
(
columns =>
[
id => { type => 'serial', not_null => 1 },
name => { type => 'varchar', length => 255 },
],
);
...
package My::Color;
use base 'My::Object';
__PACKAGE__->meta->setup
(
columns =>
[
code => { type => 'char', length => 3, not_null => 1 },
name => { type => 'varchar', length => 255 },
],
);
...
package My::Product;
use base 'My::Object';
__PACKAGE__->meta->setup
(
columns =>
[
id => { type => 'serial', not_null => 1 },
name => { type => 'varchar', length => 255 },
vendor_id => { type => 'int' },
],
foreign_keys => [ 'vendor' ],
relationships =>
[
prices => { type => 'one to many' },
colors => { type => 'many to many' },
],
);
...
package My::ProductColors;
use base 'My::Object';
__PACKAGE__->meta->setup
(
columns => [ qw(id product_id color_code) ],
foreign_keys => [ 'product', 'color' ],
);
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');
(Be aware that not all databases are smart enough to track explicitly setting
serial column values as shown in the INSERT statements above. Subsequent
auto-generated serial values may conflict with the explicitly set serial
column values already in the table. Values are set explicitly here to make the
examples easier to follow. In "real" code, you should let the serial
columns populate automatically.)
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";
AUTO-INIT EXAMPLE¶
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 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.
Anyway, I don't recommend this kind of extreme approach, but it is an effective
demonstration of the power of the convention manager.
AUTHOR¶
John C. Siracusa (siracusa@gmail.com)
LICENSE¶
Copyright (c) 2010 by John C. Siracusa. All rights reserved. This program is
free software; you can redistribute it and/or modify it under the same terms
as Perl itself.