NAME

Rose::DB::Object::Metadata::Column - Base class for an object encapsulation of database column metadata.

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

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:

    $self->method_maker_class->make_methods(
      $args{'options'}, 
      $self->method_maker_type => 
      [
        $self->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 return value of method_name().

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_class

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

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.

name [NAME]

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

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.