1Rose::DB::Object::CacheUds(e3r)Contributed Perl DocumentRaotsieo:n:DB::Object::Cached(3)
2
6 Rose::DB::Object::Cached - Memory cached object representation of a
7 single row in a database table.
8
10 package Category;
11 use base 'Rose::DB::Object::Cached';
13 __PACKAGE__->meta->setup
15 (
16 table => 'categories',
17 columns =>
19 [
20 id => { type => 'int', primary_key => 1 },
21 name => { type => 'varchar', length => 255 },
22 description => { type => 'text' },
23 ],
24 unique_key => 'name',
26 );
27 ...
29 $cat1 = Category->new(id => 123,
31 name => 'Art');
32 $cat1->save or die $category->error;
34 $cat2 = Category->new(id => 123);
37 # This will load from the memory cache, not the database
39 $cat2->load or die $cat2->error;
40 # $cat2 is the same object as $cat1
42 print "Yep, cached" if($cat1 eq $cat2);
43 # No, really, it's the same object
45 $cat1->name('Blah');
46 print $cat2->name; # prints "Blah"
47 # The object cache supports time-based expiration
49 Category->cached_objects_expire_in('15 minutes');
50 $cat1 = Category->new(id => 123);
52 $cat1->save or $cat1->die;
53 $cat1->load; # loaded from cache
55 $cat2 = Category->new(id => 123);
57 $cat2->load; # loaded from cache
58 <15 minutes pass>
60 $cat3 = Category->new(id => 123);
62 $cat3->load; # NOT loaded from cache
63 ...
65
67 "Rose::DB::Object::Cached" is a subclass of Rose::DB::Object that is
68 backed by a write-through memory cache. Whenever an object is loaded
69 from or saved to the database, it is cached in memory. Any subsequent
70 attempt to load an object of the same class with the same primary key
71 or unique key value(s) will give you the cached object instead of
72 loading from the database.
73 This means that modifications to an object will also modify all other
75 objects in memory that have the same primary key. The synopsis above
76 highlights this fact.
77 This class is most useful for encapsulating "read-only" rows, or other
79 data that is updated very infrequently. In the "Category" example
80 above, it would be inefficient to repeatedly load category information
81 in a long-running process (such as a mod_perl Apache web server) if
82 that information changes infrequently.
83 The memory cache can be cleared for an individual object or all objects
85 of the same class. There is also support for simple time-based cache
86 expiration. See the clear_object_cache and cached_objects_expire_in
87 methods for more information.
88 Only the methods that are overridden or otherwise behaviorally modified
90 are documented here. See the Rose::DB::Object documentation for the
91 rest.
92
94 cached_objects_expire_in [DURATION]
95 This method controls the expiration of cached objects.
96 If called with no arguments, the cache expiration limit in seconds
98 is returned. If passed a DURATION, the cache expiration is set.
99 Valid formats for DURATION are in the form "NUMBER UNIT" where
100 NUMBER is a positive number and UNIT is one of the following:
101 s sec secs second seconds
103 m min mins minute minutes
104 h hr hrs hour hours
105 d day days
106 w wk wks week weeks
107 y yr yrs year years
108 All formats of the DURATION argument are converted to seconds.
110 Days are exactly 24 hours, weeks are 7 days, and years are 365
111 days.
112 If an object was read from the database the specified number of
114 seconds ago or earlier, it is purged from the cache and reloaded
115 from the database the next time it is loaded.
116 A cached_objects_expire_in value of undef or zero means that
118 nothing will ever expire from the object cache. This is the
119 default.
120 clear_object_cache
122 Clear the memory cache for all objects of this class.
123
125 delete [PARAMS]
126 This method works like the delete method from Rose::DB::Object
127 except that it also calls the forget method if the object was
128 deleted successfully or did not exist in the first place.
129 forget
131 Delete the current object from the memory cache.
132 load [PARAMS]
134 Load an object based on either a primary key or a unique key.
135 If the object exists in the memory cache, the current object
137 "becomes" the cached object. See the synopsis or description above
138 for more information.
139 If the object is not in the memory cache, it is loaded from the
141 database. If the load succeeds, it is also written to the memory
142 cache.
143 PARAMS are name/value pairs, and are optional. Valid parameters
145 are:
146 refresh
148 If set to a true value, then the data is always loaded from the
149 database rather than from the memory cache. If the load
150 succeeds, the object replaces whatever was in the cache. If it
151 fails, the cache is not modified.
152 Returns true if the object was loaded successfully, false if the
154 row could not be loaded or did not exist in the database. The true
155 value returned on success will be the object itself. If the object
156 overloads its boolean value such that it is not true, then a true
157 value will be returned instead of the object itself.
158 insert [PARAMS]
160 This method does the same thing as the Rose::DB::Object method of
161 the same name, except that it also saves the object to the memory
162 cache if the insert succeeds. If it fails, the memory cache is not
163 modified.
164 remember
166 Save the current object to the memory cache without saving it to
167 the database as well. Objects are cached based on their primary
168 key values and all their unique key values.
169 remember_all [PARAMS]
171 Load and remember all objects from this table, optionally filtered
172 by PARAMS which can be any valid
173 Rose::DB::Object::Manager->get_objects() parameters. Remembered
174 objects will replace any previously cached objects with the same
175 keys.
176 remember_by_primary_key [PARAMS]
178 Save the current object to the memory cache without saving it to
179 the database as well. The object will be cached based on its
180 primary key value only. This is unlike the remeber method which
181 caches objects based on their primary key values and all their
182 unique key values.
183 save [PARAMS]
185 This method does the same thing as the Rose::DB::Object method of
186 the same name, except that it also saves the object to the memory
187 cache if the save succeeds. If it fails, the memory cache is not
188 modified.
189 update [PARAMS]
191 This method does the same thing as the Rose::DB::Object method of
192 the same name, except that it also saves the object to the memory
193 cache if the update succeeds. If it fails, the memory cache is not
194 modified.
195
197 In addition to the reserved methods listed in the Rose::DB::Object
198 documentation, the following method names are also reserved for objects
199 that inherit from this class:
200 cached_objects_expire_in
202 clear_object_cache
203 forget
204 remember
205 remember_all
206 remember_by_primary_key
207 If you have a column with one of these names, you must alias it. See
209 the Rose::DB::Object documentation for more information on column
210 aliasing and reserved methods.
211
213 John C. Siracusa (siracusa@gmail.com)
214
216 Copyright (c) 2010 by John C. Siracusa. All rights reserved. This
217 program is free software; you can redistribute it and/or modify it
218 under the same terms as Perl itself.
219perl v5.36.0 2022-07-22 Rose::DB::Object::Cached(3)