NAME

SYNOPSIS

  package MyColumnType;

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

DESCRIPTION

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.

CLASS METHODS

default_auto_method_types [TYPES]

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.

default_undef_overrides_default [BOOL]

Get or set the default value of the undef_overrides_default attribute. The default value is undef.

This default only applies when the column does not have a parent metadata object or if the metadata object's column_undef_overrides_default method returns undef.

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

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');
    

add_trigger [ EVENT, CODEREF | PARAMS ]

Add a trigger, as specified by either an event and a code reference, or a set of named parameters that include an event, a code reference, and an optional name and position for the trigger.

If there are only two arguments, and the first is a valid event name, then the second must be a code reference. Otherwise, the arguments are taken as named parameters.

Valid parameters are:

    # Add trigger using an event name and a code reference
    $column->add_trigger(on_set => sub { print "set!\n" });

    # Same as above, but using named parameters
    $column->add_trigger(event => 'on_set',
                         code  => sub { print "set!\n" });

    # Same as the above, but with a custom name and explicit position
    $column->add_trigger(event    => 'on_set',
                         code     => sub { print "set!\n" },
                         name     => 'debugging',
                         position => 'end');

alias [NAME]

Get or set an alternate name for this column.

available_method_types

Returns the full list of column method types supported by this class.

auto_method_types [TYPES]

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.

build_method_name_for_type TYPE

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.

default [VALUE]

Get or set the default value of the column.

default_exists

Returns true if a default value exists for this column (even if it is undef), false otherwise.

delete_default

Deletes the default value for this column.

delete_trigger PARAMS

Delete a triggered subroutine from the list of triggered subroutines for a given event. You must know the name applied to the triggered subroutine when it was added in order to delete it. PARAMS are name/value pairs.

    # Add two named triggers
    $column->add_trigger(event => 'on_set',
                         code  => sub { print "set!\n" },
                         name  => 'debugging');

    $column->add_trigger(event => 'on_set',
                         code  => sub { shift->do_something() },
                         name  => 'side_effect');

    # Delete the side_effect trigger
    $column->delete_trigger(event => 'on_set',
                            name  => 'side_effect');

    # Fatal error: no trigger subroutine for this column
    # named "nonesuch" for the event type "on_set"
    $column->delete_trigger(event => 'on_set',
                            name  => 'nonesuch');

delete_triggers [EVENT]

Delete all triggers for EVENT. If EVENT is omitted, delete all triggers for all events for this column.

Valid event names are "on_get", "on_set", "on_load", "on_save", "inflate", and "deflate". See the triggers section of this documentation for more information on these event types.

disable_triggers

Disable all triggers for this column.

enable_triggers

Enable all triggers for this 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.

load_on_demand [BOOL]

Get or set a boolean value that indicates whether or not a column's value should be loaded only when needed. If true, then the column's value will not automatically be fetched from the database when an object is loaded. It will be fetched only if the column value is subsequently requested through its accessor method. (This is often referred to as "lazy loading.") The default value is false.

Note: a column that is part of a primary key cannot be loaded on demand.

lazy [BOOL]

This is an alias for the load_on_demand method. It exists to allow this common usage scenario:

    __PACKAGE__->meta->columns
    (
      ...
      notes => { type => 'text', length => 1024, lazy => 1 },
    );
    

without requiring the longer "load_on_demand" parameter name to be used.

make_methods PARAMS

Create object method used to manipulate column values. PARAMS are name/value pairs. Valid PARAMS are:

manager_uses_method [BOOL]

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.

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_name TYPE [, NAME]

Get or set the name of the column method of type TYPE.

mutator_method_name

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');
    

name [NAME]

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

nonpersistent [BOOL]

Get or set a boolean flag that indicates whether or not the column is non-persistent.

not_null [BOOL]

Get or set a boolean flag that indicates whether or not the column value 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.

remarks [TEXT]

Get or set a text description of the column.

rw_method_name

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');
    

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.

triggers EVENT [, CODEREF | ARRAYREF ]

Get or set the list of trigger subroutines for EVENT. Valid event names are "on_get", "on_set", "on_load", "on_save", "inflate", and "deflate". See the triggers section of this documentation for more information on these event types.

If passed a code ref or a reference to an array of code refs, then the list of trigger subroutines for EVENT is replaced with those code ref(s).

Returns a reference to an array of trigger subroutines for the event type EVENT. If there are no triggers for EVENT, undef will be returned.

triggers_disabled

Returns true if triggers are disabled for this column, false otherwise.

type

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

undef_overrides_default [BOOL]

Get or set a boolean value that indicates whether or not setting the column to an undef value overrides the column's default value.

The default value of this attribute is determined by the parent metadata object's column_undef_overrides_default method, or the column's default_undef_overrides_default class method id the metadata object's column_undef_overrides_default method returns undef, or if the column has no parent metadata object.

Example: consider a Rose::DB::Object-derived "Person" class with a "name" column set up like this:

    package Person;
    ...
       columns =>
       [
         name => { type => 'varchar', default => 'John Doe' },
         ...
       ],
    ...
    

The following behavior is the same regardless of the setting of the undef_overrides_default attribute for the "name" column:

    $p = Person->new;
    print $p->name; # John Doe

    $p->name('Larry Wall');
    print $p->name; # Larry Wall
    

If undef_overrides_default is false for the "name" column, then this is the behavior of explicitly setting the column to undef:

    $p->name(undef);
    print $p->name; # John Doe
    

If undef_overrides_default is true for the "name" column, then this is the behavior of explicitly setting the column to undef:

    $p->name(undef);
    print $p->name; # undef
    

The undef_overrides_default attribute can be set directly on the column:

    name => { type => 'varchar', default => 'John Doe', 
              undef_overrides_default => 1 },
    

or it can be set class-wide using the meta object's column_undef_overrides_default attribute:

    Person->meta->column_undef_overrides_default(1);
    

or it can be set for all classes that use a given Rose::DB::Object::Metadata-derived class using the default_column_undef_overrides_default class method:

    My::DB::Object::Metadata->default_column_undef_overrides_default(1);
    

PROTECTED API

method_maker_arguments TYPE

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.

method_maker_class TYPE [, CLASS]

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.

method_maker_type TYPE [, NAME]

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.

AUTHOR

LICENSE