1Rose::DB::Object::MetadUastear::CCoonlturminb(u3t)ed PerRlosDeo:c:uDmBe:n:tOabtjieocnt::Metadata::Column(3)
2
3
4

NAME

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

SYNOPSIS

10         package MyColumnType;
11
12         use Rose::DB::Object::Metadata::Column;
13         our @ISA = qw(Rose::DB::Object::Metadata::Column);
14         ...
15

DESCRIPTION

17       This is the base class for objects that store and manipulate database
18       column metadata.  Column metadata objects store information about
19       columns (data type, size, etc.) and are responsible for parsing,
20       formatting, and creating object methods that manipulate column values.
21
22       Rose::DB::Object::Metadata::Column objects stringify to the value
23       returned by the name method.  This allows full-blown column objects to
24       be used in place of column name strings in most situations.
25
26   MAKING METHODS
27       A Rose::DB::Object::Metadata::Column-derived object is responsible for
28       creating object methods that manipulate column values.  Each column
29       object can make zero or more methods for each available column method
30       type.  A column method type describes the purpose of a method.  The
31       default column method types are:
32
33       "get_set"
34           A method that can both get and set the column value.  If an
35           argument is passed, then the column value is set.  In either case,
36           the current column value is returned.
37
38       "get"
39           A method that returns the current column value.
40
41       "set"
42           A method that sets the column value.
43
44       Methods are created by calling make_methods.  A list of method types
45       can be passed to the call to make_methods.  If absent, the list of
46       method types is determined by the auto_method_types method.  A list of
47       all possible method types is available through the
48       available_method_types method.
49
50       These methods make up the "public" interface to column method creation.
51       There are, however, several "protected" methods which are used
52       internally to implement the methods described above.  (The word
53       "protected" is used here in a vaguely C++ sense, meaning "accessible to
54       subclasses, but not to the public.")  Subclasses will probably find it
55       easier to override and/or call these protected methods in order to
56       influence the behavior of the "public" method maker methods.
57
58       A Rose::DB::Object::Metadata::Column object delegates method creation
59       to a  Rose::Object::MakeMethods-derived class.  Each
60       Rose::Object::MakeMethods-derived class has its own set of method
61       types, each of which takes it own set of arguments.
62
63       Using this system, four pieces of information are needed to create a
64       method on behalf of a Rose::DB::Object::Metadata::Column-derived
65       object:
66
67       •   The column method type (e.g., "get_set", "get", "set")
68
69       •   The method maker class (e.g.,
70           Rose::DB::Object::MakeMethods::Generic)
71
72       •   The method maker method type (e.g., scalar)
73
74       •   The method maker arguments (e.g., "interface => 'get_set_init'")
75
76       This information can be organized conceptually into a "method map" that
77       connects a column method type to a method maker class and, finally, to
78       one particular method type within that class, and its arguments.
79
80       The default method map is:
81
82       "get_set"
83           Rose::DB::Object::MakeMethods::Generic, scalar, "interface =>
84           'get_set', ..."
85
86       "get"
87           Rose::DB::Object::MakeMethods::Generic, scalar, "interface =>
88           'get', ..."
89
90       "set"
91           Rose::DB::Object::MakeMethods::Generic, scalar, "interface =>
92           'set', ..."
93
94       Each item in the map is a column method type.  For each column method
95       type, the method maker class, the method maker method type, and the
96       "interesting" method maker arguments are listed, in that order.
97
98       The "..." in the method maker arguments is meant to indicate that other
99       arguments have been omitted.  For example, the column object's default
100       value is passed as part of the arguments for all method types.  These
101       arguments that are common to all column method types are routinely
102       omitted from the method map for the sake of brevity.  If there are no
103       "interesting" method maker arguments, then "..." may appear by itself.
104
105       The purpose of documenting the method map is to answer the question,
106       "What kind of method(s) will be created by this column object for a
107       given method type?"  Given the method map, it's possible to read the
108       documentation for each method maker class to determine how methods of
109       the specified type behave when passed the listed arguments.
110
111       To this end, each Rose::DB::Object::Metadata::Column-derived class in
112       the Rose::DB::Object module distribution will list its method map in
113       its documentation.  This is a concise way to document the behavior that
114       is specific to each column class, while omitting the common
115       functionality (which is documented here, in the column base class).
116
117       Remember, the existence and behavior of the method map is really
118       implementation detail.  A column object is free to implement the public
119       method-making interface however it wants, without regard to any
120       conceptual or actual method map.  It must then, of course, document
121       what kinds of methods it makes for each of its method types, but it
122       does not have to use a method map to do so.
123
124   TRIGGERS
125       Triggers allow code to run in response to certain column-related
126       events.  An event may trigger zero or more pieces of code.  The names
127       and behaviors of the various kinds of events are as follows.
128
129       on_get
130           Triggered when a column value is retrieved for some purpose other
131           than storage in the database.  For example, when end-user code
132           retrieves a column value by calling an accessor method, this event
133           is triggered.  This event is not triggered when a column value is
134           retrieved while the object is being saved into the database.
135
136           Each piece of code responding to an "on_get" event will be passed a
137           single argument: a reference to the object itself.  The return
138           value is not used.
139
140       on_set
141           Triggered when a column value is set to a value that came from
142           somewhere other than  the database.  For example, when end-user
143           code sets a column value by calling a mutator method, this event is
144           triggered.  This event is not triggered when a column value is set
145           while the object is being loaded from the database.
146
147           The "on_set" event occurs after the column value has been set.
148           Each piece of code responding to an "on_set" event will be passed a
149           single argument: a reference to the object itself.  The return
150           value is not used.
151
152       on_load
153           Triggered when a column value is set while an object is being
154           loaded from the database.
155
156           The "on_load" event occurs after the column value has been loaded.
157           Each piece of code responding to an "on_load" event will be passed
158           a single argument: a reference to the object itself.  The return
159           value is not used.
160
161       on_save
162           Triggered when a column value is retrieved while an object is being
163           saved into the database.
164
165           Each piece of code responding to an "on_save" event will be passed
166           a single argument: a reference to the object itself.  The return
167           value is not used.
168
169       inflate
170           Triggered when a column value is retrieved for some purpose other
171           than storage in the database.  For example, when end-user code
172           retrieves a column value by calling an accessor method, and that
173           value came directly from the database, this event is triggered.
174
175           Inflation will only happen "as needed."  That is, a value that has
176           already been inflated will not be inflated again, and a value that
177           comes from the database and goes back into it without ever being
178           retrieved by end-user code will never be inflated at all.
179
180           Each piece of code responding to an "inflate" event will be passed
181           two arguments: a reference to the object itself and the value to be
182           inflated.  It should return an inflated version of that value.
183           Note that the value to be inflated may have come from the database,
184           or from end-user code.  Be prepared to handle almost anything.
185
186       deflate
187           Triggered when a column value that did not come directly from the
188           database needs to be put into the database.  For example, when a
189           column value set by end-user code needs to be saved into the
190           database, this event is triggered.
191
192           Deflation will only happen "as needed."  That is, a value that has
193           already been deflated will not be deflated again, and a value that
194           comes from the database and goes back into it without ever being
195           retrieved by end-user code will never need to be deflated at all.
196
197           Each piece of code responding to a "deflate" event will be passed
198           two arguments: a reference to the object itself and the value to be
199           deflated.  It should return a deflated version of that value
200           suitable for saving into the currently connected database.  Note
201           that the value to be deflated may have come from the database, or
202           from end-user code.  Be prepared to handle almost anything.
203
204       All triggers are disabled while inside code called in response to a
205       trigger event.  Such code may call any other column methods, including
206       methods that belong to its own column, without fear of infinite
207       recursion into trigger service subroutines.  Alternately, triggers may
208       be explicitly enabled if desired.  Just watch out for infinite loops.
209
210       For performance reasons, none of the column classes bundled with
211       Rose::DB::Object use triggers by default.  Some of them do inflate and
212       deflate values, but they do so internally (inside the accessor and
213       mutator methods created by the Rose::Object::MakeMethods-derived
214       classes that service those column types).  You can still add triggers
215       to these column types, but the interaction between the internal
216       inflate/deflate actions and the triggers for those same events can
217       become a bit "non-obvious."
218

CLASS METHODS

220       default_auto_method_types [TYPES]
221           Get or set the default list of auto_method_types.  TYPES should be
222           a list of column method types.  Returns the list of default column
223           method types (in list context) or a reference to an array of the
224           default column method types (in scalar context).  The default list
225           contains only the "get_set" column method type.
226
227       default_undef_overrides_default [BOOL]
228           Get or set the default value of the undef_overrides_default
229           attribute.  The default value is undef.
230
231           This default only applies when the column does not have a parent
232           metadata object or if the metadata object's
233           column_undef_overrides_default method returns undef.
234

CONSTRUCTOR

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

OBJECT METHODS

241       accessor_method_name
242           Returns the name of the method used to get the column value.  This
243           is a convenient shortcut for:
244
245               $column->method_name('get') || $column->method_name('get_set');
246
247       add_trigger [ EVENT, CODEREF | PARAMS ]
248           Add a trigger, as specified by either an event and a code
249           reference, or a set of named parameters that include an event, a
250           code reference, and an optional name and position for the trigger.
251
252           If there are only two arguments, and the first is a valid event
253           name, then the second must be a code reference.  Otherwise, the
254           arguments are taken as named parameters.
255
256           Valid parameters are:
257
258           "code CODEREF"
259               A reference to a subroutine that will be called in response to
260               a trigger event.  This parameter is required.  See the triggers
261               section of this documentation for a description of the
262               arguments to and return values expected from these routines for
263               each type of event.
264
265           "event EVENT"
266               The name of the event that activates this trigger.  This
267               parameter is required.  Valid event names are "on_get",
268               "on_set", "on_load", "on_save", "inflate", and "deflate".  See
269               the triggers section of this documentation for more information
270               on these event types.
271
272           "name NAME"
273               An optional name mapped to the triggered subroutine.  If a name
274               is not supplied, one will be generated.  A known name is
275               necessary if you ever want to delete a particular subroutine
276               from the list of triggered subroutine for a given event.
277
278           "position POS"
279               The position in the list of triggered subroutines to add this
280               new code.  Triggered subroutines are kept in an ordered list.
281               By default, new triggers are added to the end of the list,
282               which means they run last.  Valid position arguments are:
283
284               "end", "last", or "push"
285                   Add to the end of the list.
286
287               "start", "first", or "unshift"
288                   Add to the beginning of the list.
289
290               If omitted, the position defaults to "end."
291
292           Examples:
293
294               # Add trigger using an event name and a code reference
295               $column->add_trigger(on_set => sub { print "set!\n" });
296
297               # Same as above, but using named parameters
298               $column->add_trigger(event => 'on_set',
299                                    code  => sub { print "set!\n" });
300
301               # Same as the above, but with a custom name and explicit position
302               $column->add_trigger(event    => 'on_set',
303                                    code     => sub { print "set!\n" },
304                                    name     => 'debugging',
305                                    position => 'end');
306
307       alias [NAME]
308           Get or set an alternate name for this column.
309
310       available_method_types
311           Returns the full list of column method types supported by this
312           class.
313
314       auto_method_types [TYPES]
315           Get or set the list of column method types that are automatically
316           created when make_methods is called without an explicit list of
317           column method types.  The default list is determined by the
318           default_auto_method_types class method.
319
320       build_method_name_for_type TYPE
321           Return a method name for the column method type TYPE.  The default
322           implementation returns the column's alias (if defined) or name for
323           the method type "get_set", and the same thing with a "get_" or
324           "set_" prefix for the "get" and "set" column method types,
325           respectively.
326
327       default [VALUE]
328           Get or set the default value of the column.
329
330       default_exists
331           Returns true if a default value exists for this column (even if it
332           is undef), false otherwise.
333
334       delete_default
335           Deletes the default value for this column.
336
337       delete_trigger PARAMS
338           Delete a triggered subroutine from the list of triggered
339           subroutines for a given event.  You must know the name applied to
340           the triggered subroutine when it was added in order to delete it.
341           PARAMS are name/value pairs.
342
343           "name NAME"
344               The name applied to the triggered subroutine when it was added
345               via the added method.  This parameter is required.
346
347           "event EVENT"
348               The name of the event that activates this trigger.  This
349               parameter is required.  Valid event names are "on_get",
350               "on_set", "on_load", "on_save", "inflate", and "deflate".  See
351               the triggers section of this documentation for more information
352               on these event types.
353
354           A fatal error will occur if a matching trigger cannot be found.
355
356           Examples:
357
358               # Add two named triggers
359               $column->add_trigger(event => 'on_set',
360                                    code  => sub { print "set!\n" },
361                                    name  => 'debugging');
362
363               $column->add_trigger(event => 'on_set',
364                                    code  => sub { shift->do_something() },
365                                    name  => 'side_effect');
366
367               # Delete the side_effect trigger
368               $column->delete_trigger(event => 'on_set',
369                                       name  => 'side_effect');
370
371               # Fatal error: no trigger subroutine for this column
372               # named "nonesuch" for the event type "on_set"
373               $column->delete_trigger(event => 'on_set',
374                                       name  => 'nonesuch');
375
376       delete_triggers [EVENT]
377           Delete all triggers for EVENT.  If EVENT is omitted, delete all
378           triggers for all events for this column.
379
380           Valid event names are "on_get", "on_set", "on_load", "on_save",
381           "inflate", and "deflate".  See the triggers section of this
382           documentation for more information on these event types.
383
384       disable_triggers
385           Disable all triggers for this column.
386
387       enable_triggers
388           Enable all triggers for this column.
389
390       format_value DB, VALUE
391           Convert VALUE into a string suitable for the database column of
392           this type.  VALUE is expected to be like the return value of the
393           parse_value method.  DB is a Rose::DB object that may be used as
394           part of the parsing process.  Both arguments are required.
395
396       is_primary_key_member [BOOL]
397           Get or set the boolean flag that indicates whether or not this
398           column is part of the primary key for its table.
399
400       load_on_demand [BOOL]
401           Get or set a boolean value that indicates whether or not a column's
402           value should be loaded only when needed.  If true, then the
403           column's value will not automatically be fetched from the database
404           when an object is loaded.  It will be fetched only if the column
405           value is subsequently requested through its accessor method.  (This
406           is often referred to as "lazy loading.")  The default value is
407           false.
408
409           Note: a column that is part of a primary key cannot be loaded on
410           demand.
411
412       lazy [BOOL]
413           This is an alias for the load_on_demand method.  It exists to allow
414           this common usage scenario:
415
416               __PACKAGE__->meta->columns
417               (
418                 ...
419                 notes => { type => 'text', length => 1024, lazy => 1 },
420               );
421
422           without requiring the longer "load_on_demand" parameter name to be
423           used.
424
425       make_methods PARAMS
426           Create object method used to manipulate column values.  PARAMS are
427           name/value pairs.  Valid PARAMS are:
428
429           "preserve_existing BOOL"
430               Boolean flag that indicates whether or not to preserve existing
431               methods in the case of a name conflict.
432
433           "replace_existing BOOL"
434               Boolean flag that indicates whether or not to replace existing
435               methods in the case of a name conflict.
436
437           "target_class CLASS"
438               The class in which to make the method(s).  If omitted, it
439               defaults to the calling class.
440
441           "types ARRAYREF"
442               A reference to an array of column method types to be created.
443               If omitted, it defaults to the list of column method types
444               returned by auto_method_types.
445
446           If any of the methods could not be created for any reason, a fatal
447           error will occur.
448
449       manager_uses_method [BOOL]
450           If true, then Rose::DB::Object::QueryBuilder will pass column
451           values through the object method(s) associated with this column
452           when composing SQL queries where "query_is_sql" is not set.  The
453           default value is false.  See the Rose::DB::Object::QueryBuilder
454           documentation for more information.
455
456           Note: the method is named "manager_uses_method" instead of, say,
457           "query_builder_uses_method" because Rose::DB::Object::QueryBuilder
458           is rarely used directly.  Instead, it's mostly used indirectly
459           through the Rose::DB::Object::Manager class.
460
461       method_name TYPE [, NAME]
462           Get or set the name of the column method of type TYPE.
463
464       mutator_method_name
465           Returns the name of the method used to set the column value.  This
466           is a convenient shortcut for:
467
468               $column->method_name('set') || $column->method_name('get_set');
469
470       name [NAME]
471           Get or set the name of the column, not including the table name,
472           username, schema, or any other qualifier.
473
474       nonpersistent [BOOL]
475           Get or set a boolean flag that indicates whether or not the column
476           is non-persistent.
477
478       not_null [BOOL]
479           Get or set a boolean flag that indicates whether or not the column
480           value can be null.
481
482       parse_value DB, VALUE
483           Parse and return a convenient Perl representation of VALUE.  What
484           form this value will take is up to the column subclass.  If VALUE
485           is a keyword or otherwise has special meaning to the underlying
486           database, it may be returned unmodified.  DB is a Rose::DB object
487           that may be used as part of the parsing process.  Both arguments
488           are required.
489
490       primary_key_position [INT]
491           Get or set the column's ordinal position in the primary key.
492           Returns undef if the column is not part of the primary key.
493           Position numbering starts from 1.
494
495       remarks [TEXT]
496           Get or set a text description of the column.
497
498       rw_method_name
499           Returns the name of the method used to get or set the column value.
500           This is a convenient shortcut for:
501
502               $column->method_name('get_set');
503
504       should_inline_value DB, VALUE
505           Given the Rose::DB-derived object DB and the column value VALUE,
506           return true of the value should be "inlined" (i.e., not bound to a
507           "?" placeholder and passed as an argument to DBI's execute method),
508           false otherwise.  The default implementation always returns false.
509
510           This method is necessary because some DBI drivers do not (or
511           cannot) always do the right thing when binding values to
512           placeholders in SQL statements.  For example, consider the
513           following SQL for the Informix database:
514
515               CREATE TABLE test (d DATETIME YEAR TO SECOND);
516               INSERT INTO test (d) VALUES (CURRENT);
517
518           This is valid Informix SQL and will insert a row with the current
519           date and time into the "test" table.
520
521           Now consider the following attempt to do the same thing using DBI
522           placeholders (assume the table was already created as per the
523           CREATE TABLE statement above):
524
525               $sth = $dbh->prepare('INSERT INTO test (d) VALUES (?)');
526               $sth->execute('CURRENT'); # Error!
527
528           What you'll end up with is an error like this:
529
530               DBD::Informix::st execute failed: SQL: -1262: Non-numeric
531               character in datetime or interval.
532
533           In other words, DBD::Informix has tried to quote the string
534           "CURRENT", which has special meaning to Informix only when it is
535           not quoted.
536
537           In order to make this work, the value "CURRENT" must be "inlined"
538           rather than bound to a placeholder when it is the value of a
539           "DATETIME YEAR TO SECOND" column in an Informix database.
540
541           All of the information needed to make this decision is available to
542           the call to should_inline_value.  It gets passed a Rose::DB-derived
543           object, from which it can determine the database driver, and it
544           gets passed the actual value, which it can check to see if it
545           matches "/^current$/i".
546
547           This is just one example.  Each subclass of
548           Rose::DB::Object::Metadata::Column must determine for itself when a
549           value needs to be inlined.
550
551       triggers EVENT [, CODEREF | ARRAYREF ]
552           Get or set the list of trigger subroutines for EVENT.  Valid event
553           names are "on_get", "on_set", "on_load", "on_save", "inflate", and
554           "deflate".  See the triggers section of this documentation for more
555           information on these event types.
556
557           If passed a code ref or a reference to an array of code refs, then
558           the list of trigger subroutines for EVENT is replaced with those
559           code ref(s).
560
561           Returns a reference to an array of trigger subroutines for the
562           event type EVENT.  If there are no triggers for EVENT, undef will
563           be returned.
564
565       triggers_disabled
566           Returns true if triggers are disabled for this column, false
567           otherwise.
568
569       type
570           Returns the (possibly abstract) data type of the column.  The
571           default implementation returns "scalar".
572
573       undef_overrides_default [BOOL]
574           Get or set a boolean value that indicates whether or not setting
575           the column to an undef value overrides the column's default value.
576
577           The default value of this attribute is determined by the parent
578           metadata object's column_undef_overrides_default method, or the
579           column's default_undef_overrides_default class method id the
580           metadata object's column_undef_overrides_default method returns
581           undef, or if the column has no parent metadata object.
582
583           Example: consider a Rose::DB::Object-derived "Person" class with a
584           "name" column set up like this:
585
586               package Person;
587               ...
588                  columns =>
589                  [
590                    name => { type => 'varchar', default => 'John Doe' },
591                    ...
592                  ],
593               ...
594
595           The following behavior is the same regardless of the setting of the
596           undef_overrides_default attribute for the "name" column:
597
598               $p = Person->new;
599               print $p->name; # John Doe
600
601               $p->name('Larry Wall');
602               print $p->name; # Larry Wall
603
604           If undef_overrides_default is false for the "name" column, then
605           this is the behavior of explicitly setting the column to undef:
606
607               $p->name(undef);
608               print $p->name; # John Doe
609
610           If undef_overrides_default is true for the "name" column, then this
611           is the behavior of explicitly setting the column to undef:
612
613               $p->name(undef);
614               print $p->name; # undef
615
616           The undef_overrides_default attribute can be set directly on the
617           column:
618
619               name => { type => 'varchar', default => 'John Doe',
620                         undef_overrides_default => 1 },
621
622           or it can be set class-wide using the meta object's
623           column_undef_overrides_default attribute:
624
625               Person->meta->column_undef_overrides_default(1);
626
627           or it can be set for all classes that use a given
628           Rose::DB::Object::Metadata-derived class using the
629           default_column_undef_overrides_default class method:
630
631               My::DB::Object::Metadata->default_column_undef_overrides_default(1);
632

PROTECTED API

634       These methods are not part of the public interface, but are supported
635       for use by subclasses.  Put another way, given an unknown object that
636       "isa" Rose::DB::Object::Metadata::Column, there should be no
637       expectation that the following methods exist.  But subclasses, which
638       know the exact class from which they inherit, are free to use these
639       methods in order to implement the public API described above.
640
641       method_maker_arguments TYPE
642           Returns a hash (in list context) or reference to a hash (in scalar
643           context) of name/value arguments that will be passed to the
644           method_maker_class when making the column method type TYPE.
645
646       method_maker_class TYPE [, CLASS]
647           If CLASS is passed, the name of the
648           Rose::Object::MakeMethods-derived class used to create the object
649           method of type TYPE is set to CLASS.
650
651           Returns the name of the Rose::Object::MakeMethods-derived class
652           used to create the object method of type TYPE.
653
654       method_maker_type TYPE [, NAME]
655           If NAME is passed, the name of the method maker method type for the
656           column method type TYPE is set to NAME.
657
658           Returns the method maker method type for the column method type
659           TYPE.
660

AUTHOR

662       John C. Siracusa (siracusa@gmail.com)
663

LICENSE

665       Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This
666       program is free software; you can redistribute it and/or modify it
667       under the same terms as Perl itself.
668
669
670
671perl v5.36.0                      2023-01-R2o0se::DB::Object::Metadata::Column(3)
Impressum