1Rose::DB::Object::CacheUds(e3r)Contributed Perl DocumentRaotsieo:n:DB::Object::Cached(3)
2
3
4

NAME

6       Rose::DB::Object::Cached - Memory cached object representation of a
7       single row in a database table.
8

SYNOPSIS

10         package Category;
11
12         use base 'Rose::DB::Object::Cached';
13
14         __PACKAGE__->meta->setup
15         (
16           table => 'categories',
17
18           columns =>
19           [
20             id          => { type => 'int', primary_key => 1 },
21             name        => { type => 'varchar', length => 255 },
22             description => { type => 'text' },
23           ],
24
25           unique_key => 'name',
26         );
27
28         ...
29
30         $cat1 = Category->new(id   => 123,
31                               name => 'Art');
32
33         $cat1->save or die $category->error;
34
35
36         $cat2 = Category->new(id => 123);
37
38         # This will load from the memory cache, not the database
39         $cat2->load or die $cat2->error;
40
41         # $cat2 is the same object as $cat1
42         print "Yep, cached"  if($cat1 eq $cat2);
43
44         # No, really, it's the same object
45         $cat1->name('Blah');
46         print $cat2->name; # prints "Blah"
47
48         # The object cache supports time-based expiration
49         Category->cached_objects_expire_in('15 minutes');
50
51         $cat1 = Category->new(id => 123);
52         $cat1->save or $cat1->die;
53
54         $cat1->load; # loaded from cache
55
56         $cat2 = Category->new(id => 123);
57         $cat2->load; # loaded from cache
58
59         <15 minutes pass>
60
61         $cat3 = Category->new(id => 123);
62         $cat3->load; # NOT loaded from cache
63
64         ...
65

DESCRIPTION

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
74       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
78       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
84       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
89       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

CLASS METHODS

94       cached_objects_expire_in [DURATION]
95           This method controls the expiration of cached objects.
96
97           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
102               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
109           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
113           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
117           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
121       clear_object_cache
122           Clear the memory cache for all objects of this class.
123

OBJECT METHODS

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
130       forget
131           Delete the current object from the memory cache.
132
133       load [PARAMS]
134           Load an object based on either a primary key or a unique key.
135
136           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
140           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
144           PARAMS are name/value pairs, and are optional.  Valid parameters
145           are:
146
147           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
153           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
159       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
165       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
170       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
177       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
184       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
190       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

RESERVED METHODS

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
201           cached_objects_expire_in
202           clear_object_cache
203           forget
204           remember
205           remember_all
206           remember_by_primary_key
207
208       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

AUTHOR

213       John C. Siracusa (siracusa@gmail.com)
214

LICENSE

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.
219
220
221
222perl v5.36.0                      2023-01-20       Rose::DB::Object::Cached(3)
Impressum