Provided by: librose-db-object-perl_0.810-1_all bug

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.

   MAKING METHODS
       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'")

       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:

       "get_set"
           Rose::DB::Object::MakeMethods::Generic, scalar, "interface => 'get_set', ..."

       "get"
           Rose::DB::Object::MakeMethods::Generic, scalar, "interface => 'get', ..."

       "set"
           Rose::DB::Object::MakeMethods::Generic, scalar, "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.

   TRIGGERS
       Triggers allow code to run in response to certain column-related events.  An event may
       trigger zero or more pieces of code.  The names and behaviors of the various kinds of
       events are as follows.

       on_get
           Triggered when a column value is retrieved for some purpose other than storage in the
           database.  For example, when end-user code retrieves a column value by calling an
           accessor method, this event is triggered.  This event is not triggered when a column
           value is retrieved while the object is being saved into the database.

           Each piece of code responding to an "on_get" event will be passed a single argument: a
           reference to the object itself.  The return value is not used.

       on_set
           Triggered when a column value is set to a value that came from somewhere other than
           the database.  For example, when end-user code sets a column value by calling a
           mutator method, this event is triggered.  This event is not triggered when a column
           value is set while the object is being loaded from the database.

           The "on_set" event occurs after the column value has been set.  Each piece of code
           responding to an "on_set" event will be passed a single argument: a reference to the
           object itself.  The return value is not used.

       on_load
           Triggered when a column value is set while an object is being loaded from the
           database.

           The "on_load" event occurs after the column value has been loaded.  Each piece of code
           responding to an "on_load" event will be passed a single argument: a reference to the
           object itself.  The return value is not used.

       on_save
           Triggered when a column value is retrieved while an object is being saved into the
           database.

           Each piece of code responding to an "on_save" event will be passed a single argument:
           a reference to the object itself.  The return value is not used.

       inflate
           Triggered when a column value is retrieved for some purpose other than storage in the
           database.  For example, when end-user code retrieves a column value by calling an
           accessor method, and that value came directly from the database, this event is
           triggered.

           Inflation will only happen "as needed."  That is, a value that has already been
           inflated will not be inflated again, and a value that comes from the database and goes
           back into it without ever being retrieved by end-user code will never be inflated at
           all.

           Each piece of code responding to an "inflate" event will be passed two arguments: a
           reference to the object itself and the value to be inflated.  It should return an
           inflated version of that value.  Note that the value to be inflated may have come from
           the database, or from end-user code.  Be prepared to handle almost anything.

       deflate
           Triggered when a column value that did not come directly from the database needs to be
           put into the database.  For example, when a column value set by end-user code needs to
           be saved into the database, this event is triggered.

           Deflation will only happen "as needed."  That is, a value that has already been
           deflated will not be deflated again, and a value that comes from the database and goes
           back into it without ever being retrieved by end-user code will never need to be
           deflated at all.

           Each piece of code responding to a "deflate" event will be passed two arguments: a
           reference to the object itself and the value to be deflated.  It should return a
           deflated version of that value suitable for saving into the currently connected
           database.  Note that the value to be deflated may have come from the database, or from
           end-user code.  Be prepared to handle almost anything.

       All triggers are disabled while inside code called in response to a trigger event.  Such
       code may call any other column methods, including methods that belong to its own column,
       without fear of infinite recursion into trigger service subroutines.  Alternately,
       triggers may be explicitly enabled if desired.  Just watch out for infinite loops.

       For performance reasons, none of the column classes bundled with Rose::DB::Object use
       triggers by default.  Some of them do inflate and deflate values, but they do so
       internally (inside the accessor and mutator methods created by the
       Rose::Object::MakeMethods-derived classes that service those column types).  You can still
       add triggers to these column types, but the interaction between the internal
       inflate/deflate actions and the triggers for those same events can become a bit "non-
       obvious."

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:

           "code CODEREF"
               A reference to a subroutine that will be called in response to a trigger event.
               This parameter is required.  See the triggers section of this documentation for a
               description of the arguments to and return values expected from these routines for
               each type of event.

           "event EVENT"
               The name of the event that activates this trigger.  This parameter is required.
               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.

           "name NAME"
               An optional name mapped to the triggered subroutine.  If a name is not supplied,
               one will be generated.  A known name is necessary if you ever want to delete a
               particular subroutine from the list of triggered subroutine for a given event.

           "position POS"
               The position in the list of triggered subroutines to add this new code.  Triggered
               subroutines are kept in an ordered list.  By default, new triggers are added to
               the end of the list, which means they run last.  Valid position arguments are:

               "end", "last", or "push"
                   Add to the end of the list.

               "start", "first", or "unshift"
                   Add to the beginning of the list.

               If omitted, the position defaults to "end."

           Examples:

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

           "name NAME"
               The name applied to the triggered subroutine when it was added via the added
               method.  This parameter is required.

           "event EVENT"
               The name of the event that activates this trigger.  This parameter is required.
               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.

           A fatal error will occur if a matching trigger cannot be found.

           Examples:

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

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

       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

       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.

       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

       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.