NAME

Rose::DB::Object::Metadata::Column - Base class for database column metadata objects.

SYNOPSIS

package MyColumnType;

use Rose::DB::Object::Metadata::Column;
our @ISA = qw(Rose::DB::Object::Metadata::Column);
...

DESCRIPTION

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.

CONSTRUCTOR

new PARAMS

Constructs a new object based on PARAMS, where PARAMS are name/value pairs. Any object method is a valid parameter name.

OBJECT METHODS

accessor_method_name [NAME]

Get or set the name of the method used to get the column value. This is currently an alias for the method_name method.

default [VALUE]

Get or set the default value of the column.

format_value DB, VALUE

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.

is_primary_key_member [BOOL]

Get or set the boolean flag that indicates whether or not this column is part of the primary key for its table.

make_method PARAMS

Create an object method used to manipulate column values. To do this, the make_methods() class method of the method_maker_class is called. PARAMS are name/value pairs. Valid PARAMS are:

options HASHREF

A reference to a hash of options that will be passed as the first argument to the call to the make_methods() class method of the method_maker_class. This parameter is required, and the HASHREF must include a value for the key target_class, which make_methods() needs in order to determine where to make the method.

The call to make_methods() looks something like this:

my $method_name = $self->method_name;

# Use "name" if "method_name" is undefined
unless(defined $method_name)
{
  # ...and set "method_name" so it's defined now
  $method_name = $self->method_name($self->name);
}

$self->method_maker_class->make_methods(
  $args{'options'}, 
  $self->method_maker_type => 
  [
    $method_name => scalar $self->method_maker_arguments
  ]);

where $args{'options'} is the value of the "options" PARAM.

The method_maker_class is expected to be a subclass of (or otherwise conform to the interface of) Rose::Object::MakeMethods. See the Rose::Object::MakeMethods documentation for more information on the interface, and the make_methods() method in particular.

I know the call above looks confusing, but it is worth studying if you plan to subclass Rose::DB::Object::Metadata::Column. The various subclasses that are part of the Rose::DB::Object distribution provide some good examples.

More than one method may be created, but there must be at least one get/set accessor method created, and its name must match the method_name (or name if method_name is undefined).

manager_uses_method [BOOL]

If true, then Rose::DB::Object::QueryBuilder will pass column values through the object method 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.

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.

method_maker_arguments

Returns a hash (in list context) or a reference to a hash (in scalar context) or arguments that will be passed (as a hash ref) to the call to the make_methods() class method of the method_maker_class, as shown in the make_method example above.

The default implementation populates the hash with the defined return values of the object methods named by method_maker_argument_names. (Method names that return undefined values are not included in the hash.)

method_maker_argument_names

Returns a list of methods to call in order to generate the method_maker_arguments hash.

method_maker_class

Returns the name of the Rose::Object::MakeMethods-derived class used to create the object method that will manipulate the column value. The default implementation returns Rose::DB::Object::MakeMethods::Generic.

method_maker_type

Returns the method type, which is passed to the call to the make_methods() class method of the method_maker_class, as shown in the make_method example above. The default implementation returns scalar.

method_name [NAME]

Get or set the name of the method used to manipulate (get or set) the column value. This may be left undefined if the desired method name is stored in name instead. Once the method is actually created, the method_name will be set.

mutator_method_name [NAME]

Get or set the name of the method used to set the column value. This is currently an alias for the method_name method.

method_name [NAME]

Get or set the name of the object method to be created for this column. This may be left undefined if the desired method name is stored in name instead. Once the method is actually created, the method_name will be set.

name [NAME]

Get or set the name of the column, not including the table name, username, schema, or any other qualifier.

not_null [BOOL]

Get or set a boolean flag that indicated whether or not the column value can can be null.

parse_value DB, VALUE

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.

primary_key_position [INT]

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.

should_inline_value DB, VALUE

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.

This is just one example. Each subclass of Rose::DB::Object::Metadata::Column must determine for itself when a value needs to be inlined.

type

Returns the (possibly abstract) data type of the column. The default implementation returns "scalar".

AUTHOR

John C. Siracusa (siracusa@mindspring.com)

COPYRIGHT

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.