1Data::ObjectDriver::BasUesOebrjeCcotn(t3rpimb)uted PerlDDaotcau:m:eOnbtjaetcitoDnriver::BaseObject(3pm)
2
3
4

NAME

6       Data::ObjectDriver::BaseObject - base class for modeled objects
7

SYNOPSIS

9           package Ingredient;
10           use base qw( Data::ObjectDriver::BaseObject );
11
12           __PACKAGE__->install_properties({
13               columns     => [ 'ingredient_id', 'recipe_id', 'name', 'quantity' ],
14               datasource  => 'ingredient',
15               primary_key => [ 'recipe_id', 'ingredient_id' ],
16               driver      => FoodDriver->driver,
17           });
18
19           __PACKAGE__->has_a(
20               { class => 'Recipe', column => 'recipe_id', }
21           );
22
23           package main;
24
25           my ($ingredient) = Ingredient->search({ recipe_id => 4, name => 'rutabaga' });
26           $ingredient->quantity(7);
27           $ingredient->save();
28

DESCRIPTION

30       Data::ObjectDriver::BaseObject provides services to data objects
31       modeled with the Data::ObjectDriver object relational mapper.
32

CLASS DEFINITION

34   "Class->install_properties(\%params)"
35       Defines all the properties of the specified object class. Generally you
36       should call "install_properties()" in the body of your class
37       definition, so the properties can be set when the class is "use"d or
38       "require"d.
39
40       Required members of %params are:
41
42       ·   "columns"
43
44           All the columns in the object class. This property is an arrayref.
45
46       ·   "datasource"
47
48           The identifier of the table in which the object class's data are
49           stored.  Usually the datasource is simply the table name, but the
50           datasource can be decorated into the table name by the
51           "Data::ObjectDriver::DBD" module if the database requires special
52           formatting of table names.
53
54       ·   "driver" or "get_driver"
55
56           The driver used to perform database operations (lookup, update,
57           etc) for the object class.
58
59           "driver" is the instance of "Data::ObjectDriver" to use. If your
60           driver requires configuration options not available when the
61           properties are initially set, specify a coderef as "get_driver"
62           instead. It will be called the first time the driver is needed,
63           storing the driver in the class's "driver" property for subsequent
64           calls.
65
66       The optional members of %params are:
67
68       ·   "primary_key"
69
70           The column or columns used to uniquely identify an instance of the
71           object class. If one column (such as a simple numeric ID)
72           identifies the class, "primary_key" should be a scalar. Otherwise,
73           "primary_key" is an arrayref.
74
75       ·   "column_defs"
76
77           Specifies types for specially typed columns, if any, as a hashref.
78           For example, if a column holds a timestamp, name it in
79           "column_defs" as a "date" for proper handling with some
80           "Data::ObjectDriver::Driver::DBD" database drivers.  Columns for
81           which types aren't specified are handled as "char" columns.
82
83           Known "column_defs" types are:
84
85           ·   "blob"
86
87               A blob of binary data. "Data::ObjectDriver::Driver::DBD::Pg"
88               maps this to "DBI::Pg::PG_BYTEA", "DBD::SQLite" to
89               "DBI::SQL_BLOB" and "DBD::Oracle" to "ORA_BLOB".
90
91           ·   "bin_char"
92
93               A non-blob string of binary data.
94               "Data::ObjectDriver::Driver::DBD::SQLite" maps this to
95               "DBI::SQL_BINARY".
96
97           Other types may be defined by custom database drivers as needed, so
98           consult their documentation.
99
100       ·   "db"
101
102           The name of the database. When used with
103           "Data::ObjectDriver::Driver::DBI" type object drivers, this name is
104           passed to the "init_db" method when the actual database handle is
105           being created.
106
107       Custom object drivers may define other properties for your object
108       classes.  Consult the documentation of those object drivers for more
109       information.
110
111   "Class->install_column($col, $def)"
112       Modify the Class definition to declare a new column $col of definition
113       <$def> (see column_defs).
114
115   "Class->has_a(@definitions)"
116       NOTE: "has_a" is an experimental system, likely to both be buggy and
117       change in future versions.
118
119       Defines a foreign key reference between two classes, creating accessor
120       methods to retrieve objects both ways across the reference. For each
121       defined reference, two methods are created: one for objects of class
122       "Class" to load the objects they reference, and one for objects of the
123       referenced class to load the set of "Class" objects that reference
124       them.
125
126       For example, this definition:
127
128           package Ingredient;
129           __PACKAGE__->has_a(
130               { class => 'Recipe', column => 'recipe_id' },
131           );
132
133       would create "Ingredient->recipe_obj" and "Recipe->ingredient_objs"
134       instance methods.
135
136       Each member of @definitions is a hashref containing the parameters for
137       creating one accessor method. The required members of these hashes are:
138
139       ·   "class"
140
141           The class to associate.
142
143       ·   "column"
144
145           The column or columns in this class that identify the primary key
146           of the associated object. As with primary keys, use a single scalar
147           string for a single column or an arrayref for a composite key.
148
149       The optional members of "has_a()" definitions are:
150
151       ·   "method"
152
153           The name of the accessor method to create.
154
155           By default, the method name is the concatenated set of column names
156           with each "_id" suffix removed, and the suffix "_obj" appended at
157           the end of the method name. For example, if "column" were
158           "['recipe_id', 'ingredient_id']", the resulting method would be
159           called "recipe_ingredient_obj" by default.
160
161       ·   "cached"
162
163           Whether to keep a reference to the foreign object once it's loaded.
164           Subsequent calls to the accessor method would return that reference
165           immediately.
166
167       ·   "parent_method"
168
169           The name of the reciprocal method created in the referenced class
170           named in "class".
171
172           By default, that method is named with the lowercased name of the
173           current class with the suffix "_objs". For example, if in your
174           "Ingredient" class you defined a relationship with "Recipe" on the
175           column "recipe_id", this would create a "$recipe->ingredient_objs"
176           method.
177
178           Note that if you reference one class with multiple sets of fields,
179           you can omit only one parent_method; otherwise the methods would be
180           named the same thing.  For instance, if you had a "Friend" class
181           with two references to "User" objects in its "user_id" and
182           "friend_id" columns, one of them would need a "parent_method".
183
184   "Class->has_partitions(%param)"
185       Defines that the given class is partitioned, configuring it for use
186       with the "Data::ObjectDriver::Driver::SimplePartition" object driver.
187       Required members of %param are:
188
189       ·   "number"
190
191           The number of partitions in which objects of this class may be
192           stored.
193
194       ·   "get_driver"
195
196           A function that returns an object driver, given a partition ID and
197           any extra parameters specified when the class's
198           "Data::ObjectDriver::Driver::SimplePartition" was instantiated.
199
200       Note that only the parent object for use with the "SimplePartition"
201       driver should use "has_partitions()". See
202       "Data::ObjectDriver::Driver::SimplePartition" for more about
203       partitioning.
204

BASIC USAGE

206   "Class->lookup($id)"
207       Returns the instance of "Class" with the given value for its primary
208       key. If "Class" has a complex primary key (more than one column), $id
209       should be an arrayref specifying the column values in the same order as
210       specified in the "primary_key" property.
211
212   "Class->search(\%terms, [\%args])"
213       Returns all instances of "Class" that match the values specified in
214       "\%terms", keyed on column names. In list context, "search" returns the
215       objects containing those values. In scalar context, "search" returns an
216       iterator function containing the same set of objects.
217
218       Your search can be customized with parameters specified in "\%args".
219       Commonly recognized parameters (those implemented by the standard
220       "Data::ObjectDriver" object drivers) are:
221
222       ·   "sort"
223
224           A column by which to order the object results.
225
226       ·   "direction"
227
228           If set to "descend", the results (ordered by the "sort" column) are
229           returned in descending order. Otherwise, results will be in
230           ascending order.
231
232       ·   "limit"
233
234           The number of results to return, at most. You can use this with
235           "offset" to paginate your "search()" results.
236
237       ·   "offset"
238
239           The number of results to skip before the first returned result. Use
240           this with "limit" to paginate your "search()" results.
241
242       ·   "fetchonly"
243
244           A list (arrayref) of columns that should be requested. If
245           specified, only the specified columns of the resulting objects are
246           guaranteed to be set to the correct values.
247
248           Note that any caching object drivers you use may opt to ignore
249           "fetchonly" instructions, or decline to cache objects queried with
250           "fetchonly".
251
252       ·   "for_update"
253
254           If true, instructs the object driver to indicate the query is a
255           search, but the application may want to update the data after. That
256           is, the generated SQL "SELECT" query will include a "FOR UPDATE"
257           clause.
258
259       All options are passed to the object driver, so your driver may support
260       additional options.
261
262   "Class->result(\%terms, [\%args])"
263       Takes the same %terms and %args arguments that search takes, but
264       instead of executing the query immediately, returns a
265       Data::ObjectDriver::ResultSet object representing the set of results.
266
267   "$obj->exists()"
268       Returns true if $obj already exists in the database.
269
270   "$obj->save()"
271       Saves $obj to the database, whether it is already there or not. That
272       is, "save()" is functionally:
273
274           $obj->exists() ? $obj->update() : $obj->insert()
275
276   "$obj->update()"
277       Saves changes to $obj, an object that already exists in its database.
278
279   "$obj->insert()"
280       Adds $obj to the database in which it should exist, according to its
281       object driver and configuration.
282
283   "$obj->remove()"
284       Deletes $obj from its database.
285
286   "$obj->replace()"
287       Replaces $obj in the database. Does the right thing if the driver knows
288       how to REPLACE object, ala MySQL.
289

USAGE

291   "Class->new(%columns)"
292       Returns a new object of the given class, initializing its columns with
293       the values in %columns.
294
295   "$obj->init(%columns)"
296       Initializes $obji by initializing its columns with the values in
297       %columns.
298
299       Override this method if you must do initial configuration to new
300       instances of $obj's class that are not more appropriate as a
301       "post_load" callback.
302
303   "Class->properties()"
304       Returns the named object class's properties as a hashref. Note that
305       some of the standard object class properties, such as "primary_key",
306       have more convenient accessors than reading the properties directly.
307
308   "Class->driver()"
309       Returns the object driver for this class, invoking the class's
310       get_driver function (and caching the result for future calls) if
311       necessary.
312
313   "Class->get_driver($get_driver_fn)"
314       Sets the function used to find the object driver for Class objects
315       (that is, the "get_driver" property).
316
317       Note that once "driver()" has been called, the "get_driver" function is
318       not used. Usually you would specify your function as the "get_driver"
319       parameter to "install_properties()".
320
321   "Class->is_pkless()"
322       Returns whether the given object class has a primary key defined.
323
324   "Class->is_primary_key($column)"
325       Returns whether the given column is or is part of the primary key for
326       "Class" objects.
327
328   "$obj->primary_key()"
329       Returns the values of the primary key fields of $obj.
330
331   "Class->primary_key_tuple()"
332       Returns the names of the primary key fields of "Class" objects.
333
334   "$obj->is_same($other_obj)"
335       Do a primary key check on $obj and $<other_obj> and returns true only
336       if they are identical.
337
338   "$obj->object_is_stored()"
339       Returns true if the object hasn't been stored in the database yet.
340       This is particularly useful in triggers where you can then determine if
341       the object is being INSERTED or just UPDATED.
342
343   "$obj->pk_str()"
344       returns the primary key has a printable string.
345
346   "$obj->has_primary_key()"
347       Returns whether the given object has values for all of its primary key
348       fields.
349
350   "$obj->uncache_object()"
351       If you use a Cache driver, returned object will be automatically cached
352       as a result of common retrieve operations. In some rare cases you may
353       want the cache to be cleared explicitly, and this method provides you
354       with a way to do it.
355
356   "$obj->primary_key_to_terms([$id])"
357       Returns $obj's primary key as a hashref of values keyed on column
358       names, suitable for passing as "search()" terms. If $id is specified,
359       convert that primary key instead of $obj's.
360
361   "Class->datasource()"
362       Returns the datasource for objects of class "Class". That is, returns
363       the "datasource" property of "Class".
364
365   "Class->columns_of_type($type)"
366       Returns the list of columns in "Class" objects that hold data of type
367       $type, as an arrayref. Columns are of a certain type when they are set
368       that way in "Class"'s "column_defs" property.
369
370   "$obj->set_values(\%values)"
371       Sets all the columns of $obj that are members of "\%values" to the
372       values specified there.
373
374   "$obj->set_values_internal(\%values)"
375       Sets new specified values of $obj, without using any overridden mutator
376       methods of $obj and without marking the changed columns changed.
377
378   "$obj->clone()"
379       Returns a new object of the same class as $obj containing the same
380       data, except for primary keys, which are set to "undef".
381
382   "$obj->clone_all()"
383       Returns a new object of the same class as $obj containing the same
384       data, including all key fields.
385
386   "Class->has_column($column)"
387       Returns whether a column named $column exists in objects of class
388       <Class>.
389
390   "Class->column_names()"
391       Returns the list of columns in "Class" objects as an arrayref.
392
393   "$obj->column_values()"
394       Returns the columns and values in the given object as a hashref.
395
396   "$obj->column($column, [$value])"
397       Returns the value of $obj's column $column. If $value is specified,
398       "column()" sets the first.
399
400       Note the usual way of accessing and mutating column values is through
401       the named accessors:
402
403           $obj->column('fred', 'barney');  # possible
404           $obj->fred('barney');            # preferred
405
406   "$obj->is_changed([$column])"
407       Returns whether any values in $obj have changed. If $column is given,
408       returns specifically whether that column has changed.
409
410   "$obj->changed_cols_and_pk()"
411       Returns the list of all columns that have changed in $obj since it was
412       last loaded from or saved to the database, as a list.
413
414   "$obj->changed_cols()"
415       Returns the list of changed columns in $obj as a list, except for any
416       columns in $obj's primary key (even if they have changed).
417
418   "Class->lookup_multi(\@ids)"
419       Returns a list (arrayref) of objects as specified by their primary
420       keys.
421
422   "Class->bulk_insert(\@columns, \@data)"
423       Adds the given data, an arrayref of arrayrefs containing column values
424       in the order of column names given in "\@columns", as directly to the
425       database as "Class" records.
426
427       Note that only some database drivers (for example,
428       "Data::ObjectDriver::Driver::DBD::Pg") implement the bulk insert
429       operation.
430
431   "$obj->fetch_data()"
432       Returns the current values from $obj as saved in the database, as a
433       hashref.
434
435   "$obj->refresh()"
436       Resets the values of $obj from the database. Any unsaved modifications
437       to $obj will be lost, and any made meanwhile will be reflected in $obj
438       afterward.
439
440   "$obj->column_func($column)"
441       Creates an accessor/mutator method for column $column, returning it as
442       a coderef.
443
444       Override this if you need special behavior in all accessor/mutator
445       methods.
446
447   "$obj->deflate()"
448       Returns a minimal representation of the object, for use in caches where
449       you might want to preserve space (like memcached). Can also be
450       overridden by subclasses to store the optimal representation of an
451       object in the cache. For example, if you have metadata attached to an
452       object, you might want to store that in the cache, as well.
453
454   "Class->inflate($deflated)"
455       Inflates the deflated representation of the object $deflated into a
456       proper object in the class Class. That is, undoes the operation
457       "$deflated = $obj->deflate()" by returning a new object equivalent to
458       $obj.
459

TRANSACTION SUPPORT AND METHODS

461   Introduction
462       When dealing with the methods on this class, the transactions are
463       global, i.e: applied to all drivers. You can still enable transactions
464       per driver if you directly use the driver API.
465
466   "Class->begin_work"
467       This enable transactions globally for all drivers until the next
468       rollback or commit call on the class.
469
470       If begin_work is called while a transaction is still active (nested
471       transaction) then the two transactions are merged. So inner
472       transactions are ignored and a warning will be emitted.
473
474   "Class->rollback"
475       This rollbacks all the transactions since the last begin work, and
476       exits from the active transaction state.
477
478   "Class->commit"
479       Commits the transactions, and exits from the active transaction state.
480
481   "Class->txn_debug"
482       Just return the value of the global flag and the current working
483       drivers in a hashref.
484
485   "Class->txn_active"
486       Returns true if a transaction is already active.
487

DIAGNOSTICS

489       ·   "Please specify a valid column for class"
490
491           One of the class relationships you defined with "has_a()" was
492           missing a "column" member.
493
494       ·   "Please define a valid method for column"
495
496           One of the class relationships you defined with "has_a()" was
497           missing its "method" member and a method name could not be
498           generated, or the class for which you specified the relationship
499           already has a method by that name. Perhaps you specified an
500           additional accessor by the same name for that class.
501
502       ·   "keys don't match with primary keys: list"
503
504           The hashref of values you passed as the ID to
505           "primary_key_to_terms()" was missing or had extra members. Perhaps
506           you used a full "column_values()" hash instead of only including
507           that class's key fields.
508
509       ·   "You tried to set inexistent column column name to value data on
510           class name"
511
512           The hashref you specified to "set_values()" contained keys that are
513           not defined columns for that class of object. Perhaps you invoked
514           it on the wrong class, or did not fully filter members of the hash
515           out before using it.
516
517       ·   "Cannot find column 'column' for class 'class'"
518
519           The column you specified to "column()" does not exist for that
520           class, you attempted to use an automatically generated
521           accessor/mutator for a column that doesn't exist, or attempted to
522           use a column accessor as a class method instead of an instance
523           method. Perhaps you performed your call on the wrong class or
524           variable, or misspelled a method or column name.
525
526       ·   "Must specify column"
527
528           You invoked the "column_func()" method without specifying a column
529           name.  Column names are required to create the accessor/mutator
530           function, so it knows what data member of the object to use.
531
532       ·   "number (of partitions) is required"
533
534           You attempted to define partitioning for a class without specifying
535           the number of partitions for that class in the "number" member.
536           Perhaps your logic for determining the number of partitions
537           resulted in "undef" or 0.
538
539       ·   "get_driver is required"
540
541           You attempted to define partitioning for a class without specifying
542           the function to find the object driver for a partition ID as the
543           "get_driver" member.
544

BUGS AND LIMITATIONS

546       There are no known bugs in this module.
547

SEE ALSO

549       Data::ObjectDriver, Data::ObjectDriver::Driver::DBI,
550       Data::ObjectDriver::Driver::SimplePartition
551

LICENSE

553       Data::ObjectDriver is free software; you may redistribute it and/or
554       modify it under the same terms as Perl itself.
555
557       Except where otherwise noted, Data::ObjectDriver is Copyright 2005-2006
558       Six Apart, cpan@sixapart.com. All rights reserved.
559
560
561
562perl v5.28.0                      2017-04-19Data::ObjectDriver::BaseObject(3pm)
Impressum