Rose::DB::Object::Metadata::Column - Base class for database column metadata objects.
package MyColumnType; use Rose::DB::Object::Metadata::Column; our @ISA = qw(Rose::DB::Object::Metadata::Column); ...
This is the base class for objects that store and manipulate database column metadata. Column metadata objects store information about columns (data type, size, etc.) and are responsible for parsing, formatting, and creating object methods that manipulate column values.
Rose::DB::Object::Metadata::Column objects stringify to the value returned by the name method. This allows full-blown column objects to be used in place of column name strings in most situations.
A Rose::DB::Object::Metadata::Column-derived object is responsible for creating object methods that manipulate column values. Each column object can make zero or more methods for each available column method type. A column method type describes the purpose of a method. The default column method types are:
get_set
A method that can both get and set the column value. If an argument is passed, then the column value is set. In either case, the current column value is returned.
get
A method that returns the current column value.
set
A method that sets the column value.
Methods are created by calling make_methods. A list of method types can be passed to the call to make_methods. If absent, the list of method types is determined by the auto_method_types method. A list of all possible method types is available through the available_method_types method.
These methods make up the "public" interface to column method creation. There are, however, several "protected" methods which are used internally to implement the methods described above. (The word "protected" is used here in a vaguely C++ sense, meaning "accessible to subclasses, but not to the public.") Subclasses will probably find it easier to override and/or call these protected methods in order to influence the behavior of the "public" method maker methods.
A Rose::DB::Object::Metadata::Column object delegates method creation to a Rose::Object::MakeMethods-derived class. Each Rose::Object::MakeMethods-derived class has its own set of method types, each of which takes it own set of arguments.
Using this system, four pieces of information are needed to create a method on behalf of a Rose::DB::Object::Metadata::Column-derived object:
The column method type (e.g., get_set, get, set)
The method maker class (e.g., Rose::DB::Object::MakeMethods::Generic)
The method maker method type (e.g., scalar)
The method maker arguments (e.g., interface => 'get_set_init')
interface => 'get_set_init'
This information can be organized conceptually into a "method map" that connects a column method type to a method maker class and, finally, to one particular method type within that class, and its arguments.
The default method map is:
Rose::DB::Object::MakeMethods::Generic, scalar, interface => 'get_set', ...
interface => 'get_set', ...
Rose::DB::Object::MakeMethods::Generic, scalar, interface => 'get', ...
interface => 'get', ...
Rose::DB::Object::MakeMethods::Generic, scalar, interface => 'set', ...
interface => 'set', ...
Each item in the map is a column method type. For each column method type, the method maker class, the method maker method type, and the "interesting" method maker arguments are listed, in that order.
The "..." in the method maker arguments is meant to indicate that other arguments have been omitted. For example, the column object's default value is passed as part of the arguments for all method types. These arguments that are common to all column method types are routinely omitted from the method map for the sake of brevity. If there are no "interesting" method maker arguments, then "..." may appear by itself.
The purpose of documenting the method map is to answer the question, "What kind of method(s) will be created by this column object for a given method type?" Given the method map, it's possible to read the documentation for each method maker class to determine how methods of the specified type behave when passed the listed arguments.
To this end, each Rose::DB::Object::Metadata::Column-derived class in the Rose::DB::Object module distribution will list its method map in its documentation. This is a concise way to document the behavior that is specific to each column class, while omitting the common functionality (which is documented here, in the column base class).
Remember, the existence and behavior of the method map is really implementation detail. A column object is free to implement the public method-making interface however it wants, without regard to any conceptual or actual method map. It must then, of course, document what kinds of methods it makes for each of its method types, but it does not have to use a method map to do so.
Get or set the default list of auto_method_types. TYPES should be a list of column method types. Returns the list of default column method types (in list context) or a reference to an array of the default column method types (in scalar context). The default list contains only the "get_set" column method type.
Constructs a new object based on PARAMS, where PARAMS are name/value pairs. Any object method is a valid parameter name.
Returns the name of the method used to get the column value. This is a convenient shortcut for:
$column->method_name('get') || $column->method_name('get_set');
Get or set an alternate name for this column.
Returns the full list of column method types supported by this class.
Get or set the list of column method types that are automatically created when make_methods is called without an explicit list of column method types. The default list is determined by the default_auto_method_types class method.
Return a method name for the column method type TYPE. The default implementation returns the column's alias (if defined) or name for the method type "get_set", and the same thing with a "get_" or "set_" prefix for the "get" and "set" column method types, respectively.
Get or set the default value of the column.
Convert VALUE into a string suitable for the database column of this type. VALUE is expected to be like the return value of the parse_value method. DB is a Rose::DB object that may be used as part of the parsing process. Both arguments are required.
Get or set the boolean flag that indicates whether or not this column is part of the primary key for its table.
Create object method used to manipulate column values. PARAMS are name/value pairs. Valid PARAMS are:
preserve_existing BOOL
Boolean flag that indicates whether or not to preserve existing methods in the case of a name conflict.
replace_existing BOOL
Boolean flag that indicates whether or not to replace existing methods in the case of a name conflict.
target_class CLASS
The class in which to make the method(s). If omitted, it defaults to the calling class.
types ARRAYREF
A reference to an array of column method types to be created. If omitted, it defaults to the list of column method types returned by auto_method_types.
If any of the methods could not be created for any reason, a fatal error will occur.
If true, then Rose::DB::Object::QueryBuilder will pass column values through the object method(s) associated with this column when composing SQL queries where query_is_sql is not set. The default value is false. See the Rose::DB::Object::QueryBuilder documentation for more information.
query_is_sql
Note: the method is named "manager_uses_method" instead of, say, "query_builder_uses_method" because Rose::DB::Object::QueryBuilder is rarely used directly. Instead, it's mostly used indirectly through the Rose::DB::Object::Manager class.
Get or set the name of the column method of type TYPE.
Returns the name of the method used to set the column value. This is a convenient shortcut for:
$column->method_name('set') || $column->method_name('get_set');
Get or set the name of the column, not including the table name, username, schema, or any other qualifier.
Get or set a boolean flag that indicates whether or not the column value can can be null.
Parse and return a convenient Perl representation of VALUE. What form this value will take is up to the column subclass. If VALUE is a keyword or otherwise has special meaning to the underlying database, it may be returned unmodified. DB is a Rose::DB object that may be used as part of the parsing process. Both arguments are required.
Get or set the column's ordinal position in the primary key. Returns undef if the column is not part of the primary key. Position numbering starts from 1.
Returns the name of the method used to get or set the column value. This is a convenient shortcut for:
$column->method_name('get_set');
Given the Rose::DB-derived object DB and the column value VALUE, return true of the value should be "inlined" (i.e., not bound to a "?" placeholder and passed as an argument to DBI's execute method), false otherwise. The default implementation always returns false.
This method is necessary because some DBI drivers do not (or cannot) always do the right thing when binding values to placeholders in SQL statements. For example, consider the following SQL for the Informix database:
CREATE TABLE test (d DATETIME YEAR TO SECOND); INSERT INTO test (d) VALUES (CURRENT);
This is valid Informix SQL and will insert a row with the current date and time into the "test" table.
Now consider the following attempt to do the same thing using DBI placeholders (assume the table was already created as per the CREATE TABLE statement above):
$sth = $dbh->prepare('INSERT INTO test (d) VALUES (?)'); $sth->execute('CURRENT'); # Error!
What you'll end up with is an error like this:
DBD::Informix::st execute failed: SQL: -1262: Non-numeric character in datetime or interval.
In other words, DBD::Informix has tried to quote the string "CURRENT", which has special meaning to Informix only when it is not quoted.
In order to make this work, the value "CURRENT" must be "inlined" rather than bound to a placeholder when it is the value of a "DATETIME YEAR TO SECOND" column in an Informix database.
All of the information needed to make this decision is available to the call to should_inline_value. It gets passed a Rose::DB-derived object, from which it can determine the database driver, and it gets passed the actual value, which it can check to see if it matches /^current$/i.
/^current$/i
This is just one example. Each subclass of Rose::DB::Object::Metadata::Column must determine for itself when a value needs to be inlined.
Returns the (possibly abstract) data type of the column. The default implementation returns "scalar".
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::Column, 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.
Returns a hash (in list context) or reference to a hash (in scalar context) of name/value arguments that will be passed to the method_maker_class when making the column method type TYPE.
If CLASS is passed, the name of the Rose::Object::MakeMethods-derived class used to create the object method of type TYPE is set to CLASS.
Returns the name of the Rose::Object::MakeMethods-derived class used to create the object method of type TYPE.
If NAME is passed, the name of the method maker method type for the column method type TYPE is set to NAME.
Returns the method maker method type for the column method type TYPE.
John C. Siracusa (siracusa@mindspring.com)
Copyright (c) 2005 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.