NAME

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.

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.

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.

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 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:

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.

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 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).

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 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:

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.

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.

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:

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.

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.

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.

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.

(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.)

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.

Module Install Instructions

To install Rose::DB::Object::ConventionManager, simply copy and paste either of the commands in to your terminal