1Rose::DB::Object::MetadUastear::CCoonlturminb(u3t)ed PerRlosDeo:c:uDmBe:n:tOabtjieocnt::Metadata::Column(3)
2
6 Rose::DB::Object::Metadata::Column - Base class for database column
7 metadata objects.
8
10 package MyColumnType;
11 use Rose::DB::Object::Metadata::Column;
13 our @ISA = qw(Rose::DB::Object::Metadata::Column);
14 ...
15
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 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 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 "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 "get"
39 A method that returns the current column value.
40 "set"
42 A method that sets the column value.
43 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 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 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 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 • The column method type (e.g., "get_set", "get", "set")
68 • The method maker class (e.g.,
70 Rose::DB::Object::MakeMethods::Generic)
71 • The method maker method type (e.g., scalar)
73 • The method maker arguments (e.g., "interface => 'get_set_init'")
75 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 The default method map is:
81 "get_set"
83 Rose::DB::Object::MakeMethods::Generic, scalar, "interface =>
84 'get_set', ..."
85 "get"
87 Rose::DB::Object::MakeMethods::Generic, scalar, "interface =>
88 'get', ..."
89 "set"
91 Rose::DB::Object::MakeMethods::Generic, scalar, "interface =>
92 'set', ..."
93 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 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 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 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 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 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 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 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 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 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 on_load
153 Triggered when a column value is set while an object is being
154 loaded from the database.
155 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 on_save
162 Triggered when a column value is retrieved while an object is being
163 saved into the database.
164 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 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 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 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 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 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 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 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 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
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 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 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
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
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 $column->method_name('get') || $column->method_name('get_set');
246 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 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 Valid parameters are:
257 "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 "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 "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 "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 "end", "last", or "push"
285 Add to the end of the list.
286 "start", "first", or "unshift"
288 Add to the beginning of the list.
289 If omitted, the position defaults to "end."
291 Examples:
293 # Add trigger using an event name and a code reference
295 $column->add_trigger(on_set => sub { print "set!\n" });
296 # Same as above, but using named parameters
298 $column->add_trigger(event => 'on_set',
299 code => sub { print "set!\n" });
300 # 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 alias [NAME]
308 Get or set an alternate name for this column.
309 available_method_types
311 Returns the full list of column method types supported by this
312 class.
313 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 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 default [VALUE]
328 Get or set the default value of the column.
329 default_exists
331 Returns true if a default value exists for this column (even if it
332 is undef), false otherwise.
333 delete_default
335 Deletes the default value for this column.
336 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 "name NAME"
344 The name applied to the triggered subroutine when it was added
345 via the added method. This parameter is required.
346 "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 A fatal error will occur if a matching trigger cannot be found.
355 Examples:
357 # Add two named triggers
359 $column->add_trigger(event => 'on_set',
360 code => sub { print "set!\n" },
361 name => 'debugging');
362 $column->add_trigger(event => 'on_set',
364 code => sub { shift->do_something() },
365 name => 'side_effect');
366 # Delete the side_effect trigger
368 $column->delete_trigger(event => 'on_set',
369 name => 'side_effect');
370 # 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 delete_triggers [EVENT]
377 Delete all triggers for EVENT. If EVENT is omitted, delete all
378 triggers for all events for this column.
379 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 disable_triggers
385 Disable all triggers for this column.
386 enable_triggers
388 Enable all triggers for this column.
389 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 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 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 Note: a column that is part of a primary key cannot be loaded on
410 demand.
411 lazy [BOOL]
413 This is an alias for the load_on_demand method. It exists to allow
414 this common usage scenario:
415 __PACKAGE__->meta->columns
417 (
418 ...
419 notes => { type => 'text', length => 1024, lazy => 1 },
420 );
421 without requiring the longer "load_on_demand" parameter name to be
423 used.
424 make_methods PARAMS
426 Create object method used to manipulate column values. PARAMS are
427 name/value pairs. Valid PARAMS are:
428 "preserve_existing BOOL"
430 Boolean flag that indicates whether or not to preserve existing
431 methods in the case of a name conflict.
432 "replace_existing BOOL"
434 Boolean flag that indicates whether or not to replace existing
435 methods in the case of a name conflict.
436 "target_class CLASS"
438 The class in which to make the method(s). If omitted, it
439 defaults to the calling class.
440 "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 If any of the methods could not be created for any reason, a fatal
447 error will occur.
448 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 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 method_name TYPE [, NAME]
462 Get or set the name of the column method of type TYPE.
463 mutator_method_name
465 Returns the name of the method used to set the column value. This
466 is a convenient shortcut for:
467 $column->method_name('set') || $column->method_name('get_set');
469 name [NAME]
471 Get or set the name of the column, not including the table name,
472 username, schema, or any other qualifier.
473 nonpersistent [BOOL]
475 Get or set a boolean flag that indicates whether or not the column
476 is non-persistent.
477 not_null [BOOL]
479 Get or set a boolean flag that indicates whether or not the column
480 value can be null.
481 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 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 remarks [TEXT]
496 Get or set a text description of the column.
497 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 $column->method_name('get_set');
503 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 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 CREATE TABLE test (d DATETIME YEAR TO SECOND);
516 INSERT INTO test (d) VALUES (CURRENT);
517 This is valid Informix SQL and will insert a row with the current
519 date and time into the "test" table.
520 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 $sth = $dbh->prepare('INSERT INTO test (d) VALUES (?)');
526 $sth->execute('CURRENT'); # Error!
527 What you'll end up with is an error like this:
529 DBD::Informix::st execute failed: SQL: -1262: Non-numeric
531 character in datetime or interval.
532 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 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 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 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 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 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 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 triggers_disabled
566 Returns true if triggers are disabled for this column, false
567 otherwise.
568 type
570 Returns the (possibly abstract) data type of the column. The
571 default implementation returns "scalar".
572 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 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 Example: consider a Rose::DB::Object-derived "Person" class with a
584 "name" column set up like this:
585 package Person;
587 ...
588 columns =>
589 [
590 name => { type => 'varchar', default => 'John Doe' },
591 ...
592 ],
593 ...
594 The following behavior is the same regardless of the setting of the
596 undef_overrides_default attribute for the "name" column:
597 $p = Person->new;
599 print $p->name; # John Doe
600 $p->name('Larry Wall');
602 print $p->name; # Larry Wall
603 If undef_overrides_default is false for the "name" column, then
605 this is the behavior of explicitly setting the column to undef:
606 $p->name(undef);
608 print $p->name; # John Doe
609 If undef_overrides_default is true for the "name" column, then this
611 is the behavior of explicitly setting the column to undef:
612 $p->name(undef);
614 print $p->name; # undef
615 The undef_overrides_default attribute can be set directly on the
617 column:
618 name => { type => 'varchar', default => 'John Doe',
620 undef_overrides_default => 1 },
621 or it can be set class-wide using the meta object's
623 column_undef_overrides_default attribute:
624 Person->meta->column_undef_overrides_default(1);
626 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 My::DB::Object::Metadata->default_column_undef_overrides_default(1);
632
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 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 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 Returns the name of the Rose::Object::MakeMethods-derived class
652 used to create the object method of type TYPE.
653 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 Returns the method maker method type for the column method type
659 TYPE.
660
662 John C. Siracusa (siracusa@gmail.com)
663
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.
668perl v5.36.0 2023-01-R2o0se::DB::Object::Metadata::Column(3)