1Rose::DB::Object(3)   User Contributed Perl Documentation  Rose::DB::Object(3)
2
3
4

NAME

6       Rose::DB::Object - Extensible, high performance object-relational
7       mapper (ORM).
8

SYNOPSIS

10         ## For an informal overview of Rose::DB::Object, please
11         ## see the Rose::DB::Object::Tutorial documentation.  The
12         ## reference documentation follows.
13
14         ## First, set up your Rose::DB data sources, otherwise you
15         ## won't be able to connect to the database at all.  See
16         ## the Rose::DB documentation for more information.  For
17         ## a quick start, see the Rose::DB::Tutorial documentation.
18
19         ##
20         ## Create classes - two possible approaches:
21         ##
22
23         #
24         # 1. Automatic configuration
25         #
26
27         package Category;
28         use base qw(Rose::DB::Object);
29         __PACKAGE__->meta->setup
30         (
31           table => 'categories',
32           auto  => 1,
33         );
34
35         ...
36
37         package Price;
38         use base qw(Rose::DB::Object);
39         __PACKAGE__->meta->setup
40         (
41           table => 'prices',
42           auto  => 1,
43         );
44
45         ...
46
47         package Product;
48         use base qw(Rose::DB::Object);
49         __PACKAGE__->meta->setup
50         (
51           table => 'products',
52           auto  => 1,
53         );
54
55         #
56         # 2. Manual configuration
57         #
58
59         package Category;
60
61         use base qw(Rose::DB::Object);
62
63         __PACKAGE__->meta->setup
64         (
65           table => 'categories',
66
67           columns =>
68           [
69             id          => { type => 'int', primary_key => 1 },
70             name        => { type => 'varchar', length => 255 },
71             description => { type => 'text' },
72           ],
73
74           unique_key => 'name',
75         );
76
77         ...
78
79         package Price;
80
81         use base qw(Rose::DB::Object);
82
83         __PACKAGE__->meta->setup
84         (
85           table => 'prices',
86
87           columns =>
88           [
89             id         => { type => 'int', primary_key => 1 },
90             price      => { type => 'decimal' },
91             region     => { type => 'char', length => 3 },
92             product_id => { type => 'int' }
93           ],
94
95           unique_key => [ 'product_id', 'region' ],
96         );
97
98         ...
99
100         package Product;
101
102         use base qw(Rose::DB::Object);
103
104         __PACKAGE__->meta->setup
105         (
106           table => 'products',
107
108           columns =>
109           [
110             id          => { type => 'int', primary_key => 1 },
111             name        => { type => 'varchar', length => 255 },
112             description => { type => 'text' },
113             category_id => { type => 'int' },
114
115             status =>
116             {
117               type      => 'varchar',
118               check_in  => [ 'active', 'inactive' ],
119               default   => 'inactive',
120             },
121
122             start_date  => { type => 'datetime' },
123             end_date    => { type => 'datetime' },
124
125             date_created     => { type => 'timestamp', default => 'now' },
126             last_modified    => { type => 'timestamp', default => 'now' },
127           ],
128
129           unique_key => 'name',
130
131           foreign_keys =>
132           [
133             category =>
134             {
135               class       => 'Category',
136               key_columns => { category_id => 'id' },
137             },
138           ],
139
140           relationships =>
141           [
142             prices =>
143             {
144               type       => 'one to many',
145               class      => 'Price',
146               column_map => { id => 'product_id' },
147             },
148           ],
149         );
150
151         ...
152
153         #
154         # Example usage
155         #
156
157         $product = Product->new(id          => 123,
158                                 name        => 'GameCube',
159                                 status      => 'active',
160                                 start_date  => '11/5/2001',
161                                 end_date    => '12/1/2007',
162                                 category_id => 5);
163
164         $product->save;
165
166         ...
167
168         $product = Product->new(id => 123);
169         $product->load;
170
171         # Load foreign object via "one to one" relationship
172         print $product->category->name;
173
174         $product->end_date->add(days => 45);
175
176         $product->save;
177
178         ...
179
180         $product = Product->new(id => 456);
181         $product->load;
182
183         # Load foreign objects via "one to many" relationship
184         print join ' ', $product->prices;
185
186         ...
187

DESCRIPTION

189       Rose::DB::Object is a base class for objects that encapsulate a single
190       row in a database table.  Rose::DB::Object-derived objects are
191       sometimes simply called "Rose::DB::Object objects" in this
192       documentation for the sake of brevity, but be assured that derivation
193       is the only reasonable way to use this class.
194
195       Rose::DB::Object inherits from, and follows the conventions of,
196       Rose::Object.  See the Rose::Object documentation for more information.
197
198       For an informal overview of this module distribution, consult the
199       Rose::DB::Object::Tutorial.
200
201   Restrictions
202       Rose::DB::Object objects can represent rows in almost any database
203       table, subject to the following constraints.
204
205       ·   The database server must be supported by Rose::DB.
206
207       ·   The database table must have a primary key.
208
209       ·   The primary key must not allow null values in any of its columns.
210
211       Although the list above contains the only hard and fast rules, there
212       may be other realities that you'll need to work around.
213
214       The most common example is the existence of a column name in the
215       database table that conflicts with the name of a method in the
216       Rose::DB::Object API.  There are two possible workarounds: either
217       explicitly alias the column, or define a mapping function.  See the
218       alias_column and column_name_to_method_name_mapper methods in the
219       Rose::DB::Object::Metadata documentation for more details.
220
221       There are also varying degrees of support for data types in each
222       database server supported by Rose::DB.  If you have a table that uses a
223       data type not supported by an existing
224       Rose::DB::Object::Metadata::Column-derived class, you will have to
225       write your own column class and then map it to a type name using
226       Rose::DB::Object::Metadata's column_type_class method, yada yada.  (Or,
227       of course, you can map the new type to an existing column class.)
228
229       The entire framework is extensible.  This module distribution contains
230       straight-forward implementations of the most common column types, but
231       there's certainly more that can be done.  Submissions are welcome.
232
233   Features
234       Rose::DB::Object provides the following functions:
235
236       ·   Create a row in the database by saving a newly constructed object.
237
238       ·   Initialize an object by loading a row from the database.
239
240       ·   Update a row by saving a modified object back to the database.
241
242       ·   Delete a row from the database.
243
244       ·   Fetch an object referred to by a foreign key in the current object.
245           (i.e., "one to one" and "many to one" relationships.)
246
247       ·   Fetch multiple objects that refer to the current object, either
248           directly through foreign keys or indirectly through a mapping
249           table.  (i.e., "one to many" and "many to many" relationships.)
250
251       ·   Load an object along with "foreign objects" that are related
252           through any of the supported relationship types.
253
254       Objects can be loaded based on either a primary key or a unique key.
255       Since all tables fronted by Rose::DB::Objects must have non-null
256       primary keys, insert, update, and delete operations are done based on
257       the primary key.
258
259       In addition, its sibling class, Rose::DB::Object::Manager, can do the
260       following:
261
262       ·   Fetch multiple objects from the database using arbitrary query
263           conditions, limits, and offsets.
264
265       ·   Iterate over a list of objects, fetching from the database in
266           response to each step of the iterator.
267
268       ·   Fetch objects along with "foreign objects" (related through any of
269           the supported relationship types) in a single query by
270           automatically generating the appropriate SQL join(s).
271
272       ·   Count the number of objects that match a complex query.
273
274       ·   Update objects that match a complex query.
275
276       ·   Delete objects that match a complex query.
277
278       Rose::DB::Object::Manager can be subclassed and used separately (the
279       recommended approach), or it can create object manager methods within a
280       Rose::DB::Object subclass.  See the Rose::DB::Object::Manager
281       documentation for more information.
282
283       Rose::DB::Object can parse, coerce, inflate, and deflate column values
284       on your behalf, providing the most convenient possible data
285       representations on the Perl side of the fence, while allowing the
286       programmer to completely forget about the ugly details of the data
287       formats required by the database.  Default implementations are included
288       for most common column types, and the framework is completely
289       extensible.
290
291       Finally, the Rose::DB::Object::Loader can be used to automatically
292       create a suite of Rose::DB::Object and Rose::DB::Object::Manager
293       subclasses based on the contents of the database.
294
295   Configuration
296       Before Rose::DB::Object can do any useful work, you must register at
297       least one Rose::DB data source.  By default, Rose::DB::Object
298       instantiates a Rose::DB object by passing no arguments to its
299       constructor.  (See the db method.)  If you register a Rose::DB data
300       source using the default type and domain, this will work fine.
301       Otherwise, you must override the meta method in your Rose::DB::Object
302       subclass and have it return the appropriate Rose::DB-derived object.
303
304       To define your own Rose::DB::Object-derived class, you must describe
305       the table that your class will act as a front-end for.    This is done
306       through the Rose::DB::Object::Metadata object associated with each
307       Rose::DB::Object-derived class.  The metadata object is accessible via
308       Rose::DB::Object's meta method.
309
310       Metadata objects can be populated manually or automatically.  Both
311       techniques are shown in the synopsis above.  The automatic mode works
312       by asking the database itself for the information.  There are some
313       caveats to this approach.  See the auto-initialization section of the
314       Rose::DB::Object::Metadata documentation for more information.
315
316   Serial and Auto-Incremented Columns
317       Most databases provide a way to use a series of arbitrary integers as
318       primary key column values.  Some support a native "SERIAL" column data
319       type.  Others use a special auto-increment column attribute.
320
321       Rose::DB::Object supports at least one such serial or auto-incremented
322       column type in each supported database.  In all cases, the
323       Rose::DB::Object-derived class setup is the same:
324
325           package My::DB::Object;
326           ...
327           __PACKAGE__->meta->setup
328           (
329             columns =>
330             [
331               id => { type => 'serial', primary_key => 1, not_null => 1 },
332               ...
333             ],
334             ...
335           );
336
337       (Note that the column doesn't have to be named "id"; it can be named
338       anything.)
339
340       If the database column uses big integers, use "bigserial" column "type"
341       instead.
342
343       Given the column metadata definition above, Rose::DB::Object will
344       automatically generate and/or retrieve the primary key column value
345       when an object is save()d.  Example:
346
347           $o = My::DB::Object->new(name => 'bud'); # no id specified
348           $o->save; # new id value generated here
349
350           print "Generated new id value: ", $o->id;
351
352       This will only work, however, if the corresponding column definition in
353       the database is set up correctly.  The exact technique varies from
354       vendor to vendor.  Below are examples of primary key column definitions
355       that provide auto-generated values.  There's one example for each of
356       the databases supported by Rose::DB.
357
358       ·   PostgreSQL
359
360               CREATE TABLE mytable
361               (
362                 id   SERIAL PRIMARY KEY,
363                 ...
364               );
365
366       ·   MySQL
367
368               CREATE TABLE mytable
369               (
370                 id   INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
371                 ...
372               );
373
374       ·   SQLite
375
376               CREATE TABLE mytable
377               (
378                 id   INTEGER PRIMARY KEY AUTOINCREMENT,
379                 ...
380               );
381
382       ·   Informix
383
384               CREATE TABLE mytable
385               (
386                 id   SERIAL NOT NULL PRIMARY KEY,
387                 ...
388               );
389
390       ·   Oracle
391
392           Since Oracle does not natively support a serial or auto-incremented
393           column data type, an explicit sequence and trigger must be created
394           to simulate the behavior.  The sequence should be named according
395           to this convention: "<table>_<column>_seq".  For example, if the
396           table is named "mytable" and the column is named "id", then the
397           sequence should be named "mytable_id_seq".  Here's an example
398           database setup.
399
400               CREATE TABLE mytable
401               (
402                 id   INT NOT NULL PRIMARY KEY,
403                 ...
404               );
405
406               CREATE SEQUENCE mytable_id_seq;
407
408               CREATE TRIGGER mytable_insert BEFORE INSERT ON mytable
409               FOR EACH ROW
410               BEGIN
411                  IF :new.id IS NULL THEN
412                      :new.id := mytable_id_seq.nextval;
413                  END IF;
414               END;
415
416           Note the conditional that checks if ":new.id" is null, which allows
417           the value of the "id" column to be set explicitly.  If a non-NULL
418           value for the "id" column is provided, then a new value is not
419           pulled from the sequence.
420
421           If the sequence is not named according to the
422           "<table>_<column>_seq" convention, you can specify the sequence
423           name explicitly in the column metadata.  Example:
424
425               columns =>
426               [
427                 id => { type => 'serial', primary_key => 1, not_null => 1,
428                         sequence => 'some_other_seq' },
429                 ...
430
431       If the table has a multi-column primary key or does not use a column
432       type that supports auto-generated values, you can define a custom
433       primary key generator function using the primary_key_generator method
434       of the Rose::DB::Object::Metadata-derived object that contains the
435       metadata for this class.  Example:
436
437           package MyDBObject;
438
439           use base qw(Rose::DB::Object);
440
441           __PACKAGE__->meta->setup
442           (
443             table => 'mytable',
444
445             columns =>
446             [
447               k1   => { type => 'int', not_null => 1 },
448               k2   => { type => 'int', not_null => 1 },
449               name => { type => 'varchar', length => 255 },
450               ...
451             ],
452
453             primary_key_columns => [ 'k1', 'k2' ],
454
455             primary_key_generator => sub
456             {
457               my($meta, $db) = @_;
458
459               # Generate primary key values somehow
460               my $k1 = ...;
461               my $k2 = ...;
462
463               return $k1, $k2;
464             },
465           );
466
467       See the Rose::DB::Object::Metadata documentation for more information
468       on custom primary key generators.
469
470   Inheritance
471       Simple, single inheritance between Rose::DB::Object-derived classes is
472       supported.  (Multiple inheritance is not currently supported.)  The
473       first time the metadata object for a given class is accessed, it is
474       created by making a one-time "deep copy" of the base class's metadata
475       object (as long that the base class has one or more columns set).  This
476       includes all columns, relationships, foreign keys, and other metadata
477       from the base class.  From that point on, the subclass may add to or
478       modify its metadata without affecting any other class.
479
480       Tip: When using perl 5.8.0 or later, the Scalar::Util::Clone module is
481       highly recommended.  If it's installed, it will be used to more
482       efficiently clone base-class metadata objects.
483
484       If the base class has already been initialized, the subclass must
485       explicitly specify whether it wants to create a new set of column and
486       relationship methods, or merely inherit the methods from the base
487       class.  If the subclass contains any metadata modifications that affect
488       method creation, then it must create a new set of methods to reflect
489       those changes.
490
491       Finally, note that column types cannot be changed "in-place."  To
492       change a column type, delete the old column and add a new one with the
493       same name.  This can be done in one step with the replace_column
494       method.
495
496       Example:
497
498         package BaseClass;
499         use base 'Rose::DB::Object';
500
501         __PACKAGE__->meta->setup
502         (
503           table => 'objects',
504
505           columns =>
506           [
507             id    => { type => 'int', primary_key => 1 },
508             start => { type => 'scalar' },
509           ],
510         );
511
512         ...
513
514         package SubClass;
515         use base 'BaseClass';
516
517         # Set a default value for this column.
518         __PACKAGE__->meta->column('id')->default(123);
519
520         # Change the "start" column into a datetime column.
521         __PACKAGE__->meta->replace_column(start => { type => 'datetime' });
522
523         # Initialize, replacing any inherited methods with newly created ones
524         __PACKAGE__->meta->initialize(replace_existing => 1);
525
526         ...
527
528         $b = BaseClass->new;
529
530         $id = $b->id; # undef
531
532         $b->start('1/2/2003');
533         print $b->start; # '1/2/2003' (plain string)
534
535
536         $s = SubClass->new;
537
538         $id = $s->id; # 123
539
540         $b->start('1/2/2003'); # Value is converted to a DateTime object
541         print $b->start->strftime('%B'); # 'January'
542
543       To preserve all inherited methods in a subclass, do this instead:
544
545         package SubClass;
546         use base 'BaseClass';
547         __PACKAGE__->meta->initialize(preserve_existing => 1);
548
549   Error Handling
550       Error handling for Rose::DB::Object-derived objects is controlled by
551       the error_mode method of the Rose::DB::Object::Metadata object
552       associated with the class (accessible via the meta method).  The
553       default setting is "fatal", which means that Rose::DB::Object methods
554       will croak if they encounter an error.
555
556       PLEASE NOTE: The error return values described in the object method
557       documentation are only relevant when the error mode is set to something
558       "non-fatal."  In other words, if an error occurs, you'll never see any
559       of those return values if the selected error mode dies or croaks or
560       otherwise throws an exception when an error occurs.
561

CONSTRUCTOR

563       new PARAMS
564           Returns a new Rose::DB::Object constructed according to PARAMS,
565           where PARAMS are name/value pairs.  Any object method is a valid
566           parameter name.
567

CLASS METHODS

569       init_db
570           Returns the Rose::DB-derived object used to access the database in
571           the absence of an explicit db value.  The default implementation
572           simply calls Rose::DB->new() with no arguments.
573
574           Override this method in your subclass in order to use a different
575           default data source.  Note: This method must be callable as both an
576           object method and a class method.
577
578       meta
579           Returns the Rose::DB::Object::Metadata-derived object associated
580           with this class.  This object describes the database table whose
581           rows are fronted by this class: the name of the table, its columns,
582           unique keys, foreign keys, etc.
583
584           See the Rose::DB::Object::Metadata documentation for more
585           information.
586
587       meta_class
588           Return the name of the Rose::DB::Object::Metadata-derived class
589           used to store this object's metadata.  Subclasses should override
590           this method if they want to use a custom Rose::DB::Object::Metadata
591           subclass.  (See the source code for Rose::DB::Object::Std for an
592           example of this.)
593

OBJECT METHODS

595       db [DB]
596           Get or set the Rose::DB object used to access the database that
597           contains the table whose rows are fronted by the
598           Rose::DB::Object-derived class.
599
600           If it does not already exist, this object is created with a simple,
601           argument-less call to "Rose::DB->new()".  To override this default
602           in a subclass, override the init_db method and return the Rose::DB
603           to be used as the new default.
604
605       init_db
606           Returns the Rose::DB-derived object used to access the database in
607           the absence of an explicit db value.  The default implementation
608           simply calls Rose::DB->new() with no arguments.
609
610           Override this method in your subclass in order to use a different
611           default data source.  Note: This method must be callable as both an
612           object method and a class method.
613
614       dbh [DBH]
615           Get or set the DBI database handle contained in db.
616
617       delete [PARAMS]
618           Delete the row represented by the current object.  The object must
619           have been previously loaded from the database (or must otherwise
620           have a defined primary key value) in order to be deleted.  Returns
621           true if the row was deleted or did not exist, false otherwise.
622
623           PARAMS are optional name/value pairs.  Valid PARAMS are:
624
625           cascade TYPE
626               Also process related rows.  TYPE must be "delete", "null", or
627               "1".  The value "1" is an alias for "delete".  Passing an
628               illegal TYPE value will cause a fatal error.
629
630               For each "one to many" relationship, all of the rows in the
631               foreign ("many") table that reference the current object
632               ("one") will be deleted in "delete" mode, or will have the
633               column(s) that reference the current object set to NULL in
634               "null" mode.
635
636               For each "many to many" relationship, all of the rows in the
637               "mapping table" that reference the current object will deleted
638               in "delete" mode, or will have the columns that reference the
639               two tables that the mapping table maps between set to NULL in
640               "null" mode.
641
642               For each "one to one" relationship or foreign key with a "one
643               to one" relationship type, all of the rows in the foreign table
644               that reference the current object will deleted in "delete"
645               mode, or will have the column(s) that reference the current
646               object set to NULL in "null" mode.
647
648               In all modes, if the db is not currently in a transaction, a
649               new transaction is started.  If any part of the cascaded delete
650               fails, the transaction is rolled back.
651
652           prepare_cached BOOL
653               If true, then DBI's prepare_cached method will be used (instead
654               of the prepare method) when preparing the SQL statement that
655               will delete the object.  If omitted, the default value is
656               determined by the metadata object's dbi_prepare_cached class
657               method.
658
659           The cascaded delete feature described above plays it safe by only
660           deleting rows that are not referenced by any other rows (according
661           to the metadata provided by each Rose::DB::Object-derived class).
662           I strongly recommend that you implement "cascaded delete" in the
663           database itself, rather than using this feature.  It will
664           undoubtedly be faster and more robust than doing it "client-side."
665           You may also want to cascade only to certain tables, or otherwise
666           deviate from the "safe" plan.  If your database supports automatic
667           cascaded delete and/or triggers, please consider using these
668           features.
669
670       error
671           Returns the text message associated with the last error that
672           occurred.
673
674       insert [PARAMS]
675           Insert the current object to the database table.  This method
676           should only be used when you're absolutely sure that you want to
677           force the current object to be inserted, rather than updated.  It
678           is recommended that you use the save method instead of this one in
679           most circumstances.  The save method will "do the right thing,"
680           executing an insert or update as appropriate for the current
681           situation.
682
683           PARAMS are optional name/value pairs.  Valid PARAMS are:
684
685           changes_only BOOL
686               If true, then only the columns whose values have been modified
687               will be included in the insert query.  Otherwise, all columns
688               will be included.  Note that any column that has a default
689               value set in its column metadata is considered "modified"
690               during an insert operation.
691
692               If omitted, the default value of this parameter is determined
693               by the metadata object's default_insert_changes_only class
694               method, which returns false by default.
695
696           prepare_cached BOOL
697               If true, then DBI's prepare_cached method will be used (instead
698               of the prepare method) when preparing the SQL statement that
699               will insert the object.  If omitted, the default value is
700               determined by the metadata object's dbi_prepare_cached class
701               method.
702
703           Returns true if the row was inserted successfully, false otherwise.
704           The true value returned on success will be the object itself.  If
705           the object overloads its boolean value such that it is not true,
706           then a true value will be returned instead of the object itself.
707
708       load [PARAMS]
709           Load a row from the database table, initializing the object with
710           the values from that row.  An object can be loaded based on either
711           a primary key or a unique key.
712
713           Returns true if the row was loaded successfully, undef if the row
714           could not be loaded due to an error, or zero (0) if the row does
715           not exist.  The true value returned on success will be the object
716           itself.  If the object overloads its boolean value such that it is
717           not true, then a true value will be returned instead of the object
718           itself.
719
720           When loading based on a unique key, unique keys are considered in
721           the order in which they were defined in the metadata for this
722           class.  If the object has defined values for every column in a
723           unique key, then that key is used.  If no such key is found, then
724           the first key for which the object has at least one defined value
725           is used.
726
727           PARAMS are optional name/value pairs.  Valid PARAMS are:
728
729           for_update BOOL
730               If true, this parameter is translated to be the equivalent of
731               passing the lock parameter and setting the "type" to "for
732               update".  For example, these are both equivalent:
733
734                   $object->load(for_update => 1);
735                   $object->load(lock => { type => 'for update' });
736
737               See the lock parameter below for more information.
738
739           lock [ TYPE | HASHREF ]
740               Load the object using some form of locking.  These lock
741               directives have database-specific behavior and not all
742               directives are supported by all databases.  The value should be
743               a reference to a hash or a TYPE string, which is equivalent to
744               setting the value of the "type" key in the hash reference form.
745               For example, these are both equivalent:
746
747                   $object->load(lock => 'for update');
748                   $object->load(lock => { type => 'for update' });
749
750               Valid hash keys are:
751
752               columns ARRAYREF
753                   A reference to an array of column names to lock.
754                   References to scalars will be de-referenced and used as-is,
755                   included literally in the SQL locking clause.
756
757               "nowait BOOL"
758                   If true, do not wait to acquire the lock.    If supported,
759                   this is usually by adding a "NOWAIT" directive to the SQL.
760
761               "type TYPE"
762                   The lock type.  Valid values for TYPE are "for update" and
763                   "shared".  This parameter is required unless the for_update
764                   parameter was passed with a true value.
765
766               "wait TIME"
767                   Wait for the specified TIME (generally seconds) before
768                   giving up acquiring the lock.  If supported, this is
769                   usually by adding a "WAIT ..." clause to the SQL.
770
771           nonlazy BOOL
772               If true, then all columns will be fetched from the database,
773               even lazy columns.  If omitted, the default is false.
774
775           prepare_cached BOOL
776               If true, then DBI's prepare_cached method will be used (instead
777               of the prepare method) when preparing the SQL query that will
778               load the object.  If omitted, the default value is determined
779               by the metadata object's dbi_prepare_cached class method.
780
781           speculative BOOL
782               If this parameter is passed with a true value, and if the load
783               failed because the row was not found, then the error_mode
784               setting is ignored and zero (0) is returned.  In the absence of
785               an explicitly set value, this parameter defaults to the value
786               returned my the metadata object's default_load_speculative
787               method.
788
789           use_key KEY
790               Use the unique key named KEY to load the object.  This
791               overrides the unique key selection process described above.
792               The key must have a defined value in at least one of its
793               columns.
794
795           with OBJECTS
796               Load the object and the specified "foreign objects"
797               simultaneously.  OBJECTS should be a reference to an array of
798               foreign key or relationship names.
799
800           SUBCLASS NOTE: If you are going to override the load method in your
801           subclass, you must pass an alias to the actual object as the first
802           argument to the method, rather than passing a copy of the object
803           reference.  Example:
804
805               # This is the CORRECT way to override load() while still
806               # calling the base class version of the method.
807               sub load
808               {
809                 my $self = $_[0]; # Copy, not shift
810
811                 ... # Do your stuff
812
813                 shift->SUPER::load(@_); # Call superclass
814               }
815
816           Now here's the wrong way:
817
818               # This is the WRONG way to override load() while still
819               # calling the base class version of the method.
820               sub load
821               {
822                 my $self = shift; # WRONG! The alias to the object is now lost!
823
824                 ... # Do your stuff
825
826                 $self->SUPER::load(@_); # This won't work right!
827               }
828
829           This requirement exists in order to preserve some sneaky object-
830           replacement optimizations in the base class implementation of load.
831           At some point, those optimizations may change or go away.  But if
832           you follow these guidelines, your code will continue to work no
833           matter what.
834
835       not_found
836           Returns true if the previous call to load failed because a row in
837           the database table with the specified primary or unique key did not
838           exist, false otherwise.
839
840       meta
841           Returns the Rose::DB::Object::Metadata object associated with this
842           class.  This object describes the database table whose rows are
843           fronted by this class: the name of the table, its columns, unique
844           keys, foreign keys, etc.
845
846           See the Rose::DB::Object::Metadata documentation for more
847           information.
848
849       save [PARAMS]
850           Save the current object to the database table.  In the absence of
851           PARAMS, if the object was previously loaded from the database, the
852           row will be updated.  Otherwise, a new row will be inserted.
853           PARAMS are name/value pairs.  Valid PARAMS are listed below.
854
855           Actions associated with sub-objects that were added or deleted
856           using one of the "*_on_save" relationship or foreign key method
857           types are also performed when this method is called.  If there are
858           any such actions to perform, a new transaction is started if the db
859           is not already in one, and rollback() is called if any of the
860           actions fail during the save().  Example:
861
862               $product = Product->new(name => 'Sled');
863               $vendor  = Vendor->new(name => 'Acme');
864
865               $product->vendor($vendor);
866
867               # Product and vendor records created and linked together,
868               # all within a single transaction.
869               $product->save;
870
871           See the "making methods" sections of the
872           Rose::DB::Object::Metadata::Relationship and
873           Rose::DB::Object::Metadata::ForeignKey documentation for a
874           description of the "method map" associated with each relationship
875           and foreign key.  Only the actions initiated through one of the
876           "*_on_save" method types are handled when save() is called.  See
877           the documentation for each individual "*_on_save" method type for
878           more specific information.
879
880           Valid parameters to save() are:
881
882           cascade BOOL
883               If true, then sub-objects related to this object through a
884               foreign key or relationship that have been previously loaded
885               using methods called on this object and that contain unsaved
886               changes will be saved after the parent object is saved.  This
887               proceeds recursively through all sub-objects.  (All other
888               parameters to the original call to save are also passed on when
889               saving sub-objects.)
890
891               All database operations are done within a single transaction.
892               If the db is not currently in a transaction, a new transaction
893               is started.  If any part of the cascaded save fails, the
894               transaction is rolled back.
895
896               If omitted, the default value of this parameter is determined
897               by the metadata object's default_cascade_save class method,
898               which returns false by default.
899
900               Example:
901
902                   $p = Product->new(id => 123)->load;
903
904                   print join(', ', $p->colors); # related Color objects loaded
905                   $p->colors->[0]->code('zzz'); # one Color object is modified
906
907                   # The Product object and the modified Color object are saved
908                   $p->save(cascade => 1);
909
910           changes_only BOOL
911               If true, then only the columns whose values have been modified
912               will be included in the insert or update query.  Otherwise, all
913               eligible columns will be included.  Note that any column that
914               has a default value set in its column metadata is considered
915               "modified" during an insert operation.
916
917               If omitted, the default value of this parameter is determined
918               by the metadata object's default_update_changes_only class
919               method on update, and the default_insert_changes_only class
920               method on insert, both of which return false by default.
921
922           insert BOOL
923               If set to a true value, then an insert is attempted, regardless
924               of whether or not the object was previously loaded from the
925               database.
926
927           prepare_cached BOOL
928               If true, then DBI's prepare_cached method will be used (instead
929               of the prepare method) when preparing the SQL statement that
930               will save the object.  If omitted, the default value is
931               determined by the metadata object's dbi_prepare_cached class
932               method.
933
934           update BOOL
935               If set to a true value, then an update is attempted, regardless
936               of whether or not the object was previously loaded from the
937               database.
938
939           It is an error to pass both the "insert" and "update" parameters in
940           a single call.
941
942           Returns true if the row was inserted or updated successfully, false
943           otherwise.  The true value returned on success will be the object
944           itself.  If the object overloads its boolean value such that it is
945           not true, then a true value will be returned instead of the object
946           itself.
947
948           If an insert was performed and the primary key is a single column
949           that supports auto-generated values, then the object accessor for
950           the primary key column will contain the auto-generated value.  See
951           the Serial and Auto-Incremented Columns section for more
952           information.
953
954       update [PARAMS]
955           Update the current object in the database table.  This method
956           should only be used when you're absolutely sure that you want to
957           force the current object to be updated, rather than inserted.  It
958           is recommended that you use the save method instead of this one in
959           most circumstances.  The save method will "do the right thing,"
960           executing an insert or update as appropriate for the current
961           situation.
962
963           PARAMS are optional name/value pairs.  Valid PARAMS are:
964
965           changes_only BOOL
966               If true, then only the columns whose values have been modified
967               will be updated.  Otherwise, all columns whose values have been
968               loaded from the database will be updated.  If omitted, the
969               default value of this parameter is determined by the metadata
970               object's default_update_changes_only class method, which
971               returns false by default.
972
973           prepare_cached BOOL
974               If true, then DBI's prepare_cached method will be used (instead
975               of the prepare method) when preparing the SQL statement that
976               will insert the object.  If omitted, the default value of this
977               parameter is determined by the metadata object's
978               dbi_prepare_cached class method.
979
980           Returns true if the row was updated successfully, false otherwise.
981           The true value returned on success will be the object itself.  If
982           the object overloads its boolean value such that it is not true,
983           then a true value will be returned instead of the object itself.
984

RESERVED METHODS

986       As described in the Rose::DB::Object::Metadata documentation, each
987       column in the database table has an associated get/set accessor method
988       in the Rose::DB::Object.  Since the Rose::DB::Object API already
989       defines many methods (load, save, meta, etc.), accessor methods for
990       columns that share the name of an existing method pose a problem.  The
991       solution is to alias such columns using Rose::DB::Object::Metadata's
992       alias_column method.
993
994       Here is a list of method names reserved by the Rose::DB::Object API.
995       If you have a column with one of these names, you must alias it.
996
997           db
998           dbh
999           delete
1000           DESTROY
1001           error
1002           init_db
1003           _init_db
1004           insert
1005           load
1006           meta
1007           meta_class
1008           not_found
1009           save
1010           update
1011
1012       Note that not all of these methods are public.  These methods do not
1013       suddenly become public just because you now know their names!  Remember
1014       the stated policy of the Rose web application framework: if a method is
1015       not documented, it does not exist.  (And no, the list of method names
1016       above does not constitute "documentation.")
1017

DEVELOPMENT POLICY

1019       The Rose development policy applies to this, and all "Rose::*" modules.
1020       Please install Rose from CPAN and then run ""perldoc Rose"" for more
1021       information.
1022

SUPPORT

1024       For an informal overview of Rose::DB::Object, consult the
1025       Rose::DB::Object::Tutorial.
1026
1027           perldoc Rose::DB::Object::Tutorial
1028
1029       Any Rose::DB::Object questions or problems can be posted to the
1030       Rose::DB::Object mailing list.  To subscribe to the list or view the
1031       archives, go here:
1032
1033       <http://groups.google.com/group/rose-db-object>
1034
1035       Although the mailing list is the preferred support mechanism, you can
1036       also email the author (see below) or file bugs using the CPAN bug
1037       tracking system:
1038
1039       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Rose-DB-Object>
1040
1041       There's also a wiki and other resources linked from the Rose project
1042       home page:
1043
1044       <http://rosecode.org>
1045

CONTRIBUTORS

1047       Bradley C Bailey, Graham Barr, Kostas Chatzikokolakis, David
1048       Christensen, Lucian Dragus, Justin Ellison, Perrin Harkins, Cees Hek,
1049       Benjamin Hitz, Dave Howorth, Peter Karman, Ed Loehr, Adam Mackler,
1050       Michael Reece, Thomas Whaples, Douglas Wilson, Teodor Zlatanov
1051

AUTHOR

1053       John C. Siracusa (siracusa@gmail.com)
1054

LICENSE

1056       Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This
1057       program is free software; you can redistribute it and/or modify it
1058       under the same terms as Perl itself.
1059
1060
1061
1062perl v5.28.0                      2015-03-23               Rose::DB::Object(3)
Impressum