1Rose::DB::Object::Util(U3s)er Contributed Perl DocumentatRioosne::DB::Object::Util(3)
2
3
4

NAME

6       Rose::DB::Object::Util - Utility functions for use in Rose::DB::Object
7       subclasses and method makers.
8

SYNOPSIS

10         package MyDBObject;
11
12         use Rose::DB::Object::Util qw(:all);
13
14         use Rose::DB::Object;
15         our @ISA = qw(Rose::DB::Object);
16         ...
17         sub whatever
18         {
19           my($self) = shift;
20           ...
21           if(is_loading($self))
22           {
23             ...
24             set_state_in_db($self);
25           }
26           ...
27         }
28

DESCRIPTION

30       Rose::DB::Object::Util provides functions that are useful for
31       developers who are subclassing Rose::DB::Object or otherwise extending
32       or modifying its behavior.
33
34       Rose::DB::Objects have some awareness of their current situation.
35       Certain optimizations rely on this awareness.  For example, when
36       loading column values directly from the database, there's no reason to
37       validate the format of the data or immediately "inflate" the values.
38       The is_loading function will tell you when these steps can safely be
39       skipped.
40
41       Similarly, it may be useful to set these state characteristics in your
42       code.  The "set_sate_*" functions provide that ability.
43

EXPORTS

45       "Rose::DB::Object::Util" does not export any function names by default.
46
47       The 'get_state' tag:
48
49           use Rose::DB::Object::Util qw(:get_state);
50
51       will cause the following function names to be imported:
52
53           is_in_db()
54           is_loading()
55           is_saving()
56
57       The 'set_state' tag:
58
59           use Rose::DB::Object::Util qw(:set_state);
60
61       will cause the following function names to be imported:
62
63           set_state_in_db()
64           set_state_loading()
65           set_state_saving()
66
67       The 'unset_state' tag:
68
69           use Rose::DB::Object::Util qw(:unset_state);
70
71       will cause the following function names to be imported:
72
73           unset_state_in_db()
74           unset_state_loading()
75           unset_state_saving()
76
77       the 'state' tag:
78
79           use Rose::DB::Object::Util qw(:unset_state);
80
81       will cause the following function names to be imported:
82
83           is_in_db()
84           is_loading()
85           is_saving()
86           set_state_in_db()
87           set_state_loading()
88           set_state_saving()
89           unset_state_in_db()
90           unset_state_loading()
91           unset_state_saving()
92
93       The 'columns' tag:
94
95           use Rose::DB::Object::Util qw(:columns);
96
97       will cause the following function names to be imported:
98
99           get_column_value_modified()
100           set_column_value_modified()
101           unset_column_value_modified()
102           modified_column_names()
103           has_modified_columns()
104
105       The 'children' tag:
106
107           use Rose::DB::Object::Util qw(:children);
108
109       will cause the following function names to be imported:
110
111           has_loaded_related()
112           has_modified_children()
113
114       The 'all' tag:
115
116           use Rose::DB::Object::Util qw(:all);
117
118       will cause the following function names to be imported:
119
120           is_in_db()
121           is_loading()
122           is_saving()
123
124           set_state_in_db()
125           set_state_loading()
126           set_state_saving()
127
128           unset_state_in_db()
129           unset_state_loading()
130           unset_state_saving()
131
132           get_column_value_modified()
133           set_column_value_modified()
134           unset_column_value_modified()
135           modified_column_names()
136           has_modified_columns()
137
138           has_loaded_related()
139           has_modified_children()
140

FUNCTIONS

142       get_column_value_modified OBJECT, COLUMN
143           Returns true if the column named COLUMN in OBJECT is modified,
144           false otherwise.
145
146       has_loaded_related [ OBJECT, NAME | PARAMS ]
147           Given an OBJECT and a foreign key or relationship name, return true
148           if one or more related objects have been loaded into OBJECT, false
149           otherwise.
150
151           If the name is passed as a plain string NAME, then a foreign key
152           with that name is looked up.  If no such foreign key exists, then a
153           relationship with that name is looked up.  If no such relationship
154           or foreign key exists, a fatal error will occur.  Example:
155
156               has_loaded_related($object, 'bar');
157
158           It's generally not a good idea to add a foreign key and a
159           relationship with the same name, but it is technically possible.
160           To specify the domain of the name, pass the name as the value of a
161           "foreign_key" or "relationship" parameter.  You must also pass the
162           object as the value of the "object" parameter.  Example:
163
164               has_loaded_related(object => $object, foreign_key => 'bar');
165               has_loaded_related(object => $object, relationship => 'bar');
166
167       has_modified_children OBJECT
168           Returns true if OBJECT has_loaded_related objects, at least one of
169           which has_modified_columns or has_modified_children, false
170           otherwise.
171
172       has_modified_columns OBJECT
173           Returns true if OBJECT has any modified columns, false otherwise.
174
175       is_in_db OBJECT
176           Given the Rose::DB::Object-derived object OBJECT, returns true if
177           the object was loaded from, or has ever been saved into, the
178           database, or false if it has not.
179
180       is_loading OBJECT
181           Given the Rose::DB::Object-derived object OBJECT, returns true if
182           the object is currently being loaded, false otherwise.
183
184       is_saving OBJECT
185           Given the Rose::DB::Object-derived object OBJECT, returns true if
186           the object is currently being saved, false otherwise.
187
188       modified_column_names OBJECT
189           Returns a list containing the names of all the modified columns in
190           OBJECT.
191
192       set_column_value_modified OBJECT, COLUMN
193           Mark the column named COLUMN in OBJECT as modified.
194
195       unset_column_value_modified OBJECT, COLUMN
196           Clear the modified mark, if any, on the column named COLUMN in
197           OBJECT.
198
199       set_state_in_db OBJECT
200           Mark the Rose::DB::Object-derived object OBJECT as having been
201           loaded from or saved into the database at some point in the past.
202
203       set_state_loading OBJECT
204           Indicate that the Rose::DB::Object-derived object OBJECT is
205           currently being loaded from the database.
206
207       set_state_saving OBJECT
208           Indicate that the Rose::DB::Object-derived object OBJECT is
209           currently being saved into the database.
210
211       unset_state_in_db OBJECT
212           Mark the Rose::DB::Object-derived object OBJECT as not having been
213           loaded from or saved into the database at some point in the past.
214
215       unset_state_loading OBJECT
216           Indicate that the Rose::DB::Object-derived object OBJECT is not
217           currently being loaded from the database.
218
219       unset_state_saving OBJECT
220           Indicate that the Rose::DB::Object-derived object OBJECT is not
221           currently being saved into the database.
222

AUTHOR

224       John C. Siracusa (siracusa@gmail.com)
225

LICENSE

227       Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This
228       program is free software; you can redistribute it and/or modify it
229       under the same terms as Perl itself.
230
231
232
233perl v5.38.0                      2023-07-21         Rose::DB::Object::Util(3)