Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Rose::DB::Object::CachUser)Contributed Perl DocumenRose::DB::Object::Cached(3)

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

SYNOPSIS
	 package Category;

	 use base 'Rose::DB::Object::Cached';

	 __PACKAGE__->meta->setup
	 (
	   table => 'categories',

	   columns =>
	   [
	     id		 => { type => 'int', primary_key => 1 },
	     name	 => { type => 'varchar', length	=> 255 },
	     description => { type => 'text' },
	   ],

	   unique_key => 'name',
	 );

	 ...

	 $cat1 = Category->new(id   => 123,
			       name => 'Art');

	 $cat1->save or	die $category->error;

	 $cat2 = Category->new(id => 123);

	 # This	will load from the memory cache, not the database
	 $cat2->load or	die $cat2->error;

	 # $cat2 is the	same object as $cat1
	 print "Yep, cached"  if($cat1 eq $cat2);

	 # No, really, it's the	same object
	 $cat1->name('Blah');
	 print $cat2->name; # prints "Blah"

	 # The object cache supports time-based	expiration
	 Category->cached_objects_expire_in('15	minutes');

	 $cat1 = Category->new(id => 123);
	 $cat1->save or	$cat1->die;

	 $cat1->load; #	loaded from cache

	 $cat2 = Category->new(id => 123);
	 $cat2->load; #	loaded from cache

	 <15 minutes pass>

	 $cat3 = Category->new(id => 123);
	 $cat3->load; #	NOT loaded from	cache

	 ...

DESCRIPTION
       "Rose::DB::Object::Cached" is a subclass	of Rose::DB::Object that is
       backed by a write-through memory	cache.	Whenever an object is loaded
       from or saved to	the database, it is cached in memory.  Any subsequent
       attempt to load an object of the	same class with	the same primary key
       or unique key value(s) will give	you the	cached object instead of
       loading from the	database.

       This means that modifications to	an object will also modify all other
       objects in memory that have the same primary key.  The synopsis above
       highlights this fact.

       This class is most useful for encapsulating "read-only" rows, or	other
       data that is updated very infrequently.	In the "Category" example
       above, it would be inefficient to repeatedly load category information
       in a long-running process (such as a mod_perl Apache web	server)	if
       that information	changes	infrequently.

       The memory cache	can be cleared for an individual object	or all objects
       of the same class.  There is also support for simple time-based cache
       expiration.  See	the clear_object_cache and cached_objects_expire_in
       methods for more	information.

       Only the	methods	that are overridden or otherwise behaviorally modified
       are documented here.  See the Rose::DB::Object documentation for	the
       rest.

CLASS METHODS
       cached_objects_expire_in	[DURATION]
	   This	method controls	the expiration of cached objects.

	   If called with no arguments,	the cache expiration limit in seconds
	   is returned.	 If passed a DURATION, the cache expiration is set.
	   Valid formats for DURATION are in the form "NUMBER UNIT" where
	   NUMBER is a positive	number and UNIT	is one of the following:

	       s sec secs second seconds
	       m min mins minute minutes
	       h hr hrs	hour hours
	       d day days
	       w wk wks	week weeks
	       y yr yrs	year years

	   All formats of the DURATION argument	are converted to seconds.
	   Days	are exactly 24 hours, weeks are	7 days,	and years are 365
	   days.

	   If an object	was read from the database the specified number	of
	   seconds ago or earlier, it is purged	from the cache and reloaded
	   from	the database the next time it is loaded.

	   A cached_objects_expire_in value of undef or	zero means that
	   nothing will	ever expire from the object cache.  This is the
	   default.

       clear_object_cache
	   Clear the memory cache for all objects of this class.

OBJECT METHODS
       delete [PARAMS]
	   This	method works like the delete method from Rose::DB::Object
	   except that it also calls the forget	method if the object was
	   deleted successfully	or did not exist in the	first place.

       forget
	   Delete the current object from the memory cache.

       load [PARAMS]
	   Load	an object based	on either a primary key	or a unique key.

	   If the object exists	in the memory cache, the current object
	   "becomes" the cached	object.	 See the synopsis or description above
	   for more information.

	   If the object is not	in the memory cache, it	is loaded from the
	   database.  If the load succeeds, it is also written to the memory
	   cache.

	   PARAMS are name/value pairs,	and are	optional.  Valid parameters
	   are:

	   refresh
	       If set to a true	value, then the	data is	always loaded from the
	       database	rather than from the memory cache.  If the load
	       succeeds, the object replaces whatever was in the cache.	 If it
	       fails, the cache	is not modified.

	   Returns true	if the object was loaded successfully, false if	the
	   row could not be loaded or did not exist in the database.  The true
	   value returned on success will be the object	itself.	 If the	object
	   overloads its boolean value such that it is not true, then a	true
	   value will be returned instead of the object	itself.

       insert [PARAMS]
	   This	method does the	same thing as the Rose::DB::Object method of
	   the same name, except that it also saves the	object to the memory
	   cache if the	insert succeeds.  If it	fails, the memory cache	is not
	   modified.

       remember
	   Save	the current object to the memory cache without saving it to
	   the database	as well.  Objects are cached based on their primary
	   key values and all their unique key values.

       remember_all [PARAMS]
	   Load	and remember all objects from this table, optionally filtered
	   by PARAMS which can be any valid
	   Rose::DB::Object::Manager->get_objects() parameters.	 Remembered
	   objects will	replace	any previously cached objects with the same
	   keys.

       remember_by_primary_key [PARAMS]
	   Save	the current object to the memory cache without saving it to
	   the database	as well.  The object will be cached based on its
	   primary key value only.  This is unlike the remeber method which
	   caches objects based	on their primary key values and	all their
	   unique key values.

       save [PARAMS]
	   This	method does the	same thing as the Rose::DB::Object method of
	   the same name, except that it also saves the	object to the memory
	   cache if the	save succeeds.	If it fails, the memory	cache is not
	   modified.

       update [PARAMS]
	   This	method does the	same thing as the Rose::DB::Object method of
	   the same name, except that it also saves the	object to the memory
	   cache if the	update succeeds.  If it	fails, the memory cache	is not
	   modified.

RESERVED METHODS
       In addition to the reserved methods listed in the Rose::DB::Object
       documentation, the following method names are also reserved for objects
       that inherit from this class:

	   cached_objects_expire_in
	   clear_object_cache
	   forget
	   remember
	   remember_all
	   remember_by_primary_key

       If you have a column with one of	these names, you must alias it.	 See
       the Rose::DB::Object documentation for more information on column
       aliasing	and reserved methods.

AUTHOR
       John C. Siracusa	(siracusa@gmail.com)

LICENSE
       Copyright (c) 2010 by John C. Siracusa.	All rights reserved.  This
       program is free software; you can redistribute it and/or	modify it
       under the same terms as Perl itself.

perl v5.24.1			  2015-03-17	   Rose::DB::Object::Cached(3)

NAME | SYNOPSIS | DESCRIPTION | CLASS METHODS | OBJECT METHODS | RESERVED METHODS | AUTHOR | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Rose::DB::Object::Cached&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help