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

BASIC USAGE

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

USAGE

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

TRANSACTION SUPPORT AND METHODS

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

DIAGNOSTICS

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

BUGS AND LIMITATIONS

545       There are no known bugs in this module.
546

SEE ALSO

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

LICENSE

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