NAME

Rose::DB::Cache - A cache for Rose::DB objects.

SYNOPSIS

# Usage
package My::DB;

use base 'Rose::DB';
...

$cache = My::DB->db_cache;

$db = $cache->get_db(...);

$cache->set_db($db);

$cache->clear;


# Subclassing
package My::DB::Cache;

use Rose::DB::Cache;
our @ISA = qw(Rose::DB::Cache);

# Override methods as desired
sub get_db          { ... }
sub set_db          { ... }
sub prepare_db      { ... }
sub build_cache_key { ... }
sub clear           { ... }

DESCRIPTION

Rose::DB::Cache provides both an API and a default implementation of a caching system for Rose::DB objects. Each Rose::DB-derived class references a Rose::DB::Cache-derived object to which it delegates cache-related activites. See the new_or_cached method for an example.

The default implementation caches and returns Rose::DB objects using the combination of their type and domain as the cache key. There is no cache expiration or other cache cleaning. The only sophistication in the default implementation is that it is Apache::DBI-aware: it will do the right thing during apache server start-up and will ensure that Apache::DBI's "ping" and rollback features work as expected, keeping the DBI database handles contained within each Rose::DB object connected and alive. Bot mod_perl 1.x and 2.x are supported.

Subclasses can override any and all methods described below in order to implement their own caching strategy.

CLASS METHODS

build_cache_key PARAMS

Given the name/value pairs PARAMS, return a string representing the corresponding cache key. Calls to this method from within Rose::DB::Cache will include at least type and domain parameters, but you may pass any parameters if you override all methods that call this method in your subclass.

entry_class [CLASS]

Get or set the name of the Rose::DB::Cache::Entry-derived class used to store cached Rose::DB objects on behalf of this class. The default value is Rose::DB::Cache::Entry.

CONSTRUCTORS

new PARAMS

Constructs a new Rose::DB::Cache object based on PARAMS, where PARAMS are name/value pairs. Any object method is a valid parameter name.

OBJECT METHODS

clear

Clears the cache entirely.

get_db [PARAMS]

Return the cached Rose::DB-derived object corresponding to the name/value pairs passed in PARAMS. PARAMS are passed to the build_cache_key method, and the key returned is used to look up the cached object.

If a cached object is found, the prepare_db method is called, passing the cached db object and its corresponding Rose::DB::Cache::Entry object as arguments. The cached db object is then returned.

If no such object exists in the cache, undef is returned.

prepare_db [DB, ENTRY]

Prepare the cached Rose::DB-derived object DB for usage. The cached's db object's Rose::DB::Cache::Entry object, ENTRY, is also passed.

When NOT running under Apache::DBI, this method does nothing.

When running under Apache::DBI, using either mod_perl 1.x or 2.x, this method will do the following:

• Any DBI database handle created inside a Rose::DB object during apache server startup will be discarded and replaced the first time it is used after server startup has completed.

• All DBI database handles contained in cached Rose::DB objects will be cleared at the end of each request using a PerlCleanupHandler. This will cause DBI->connect to be called the next time a dbh is requested from a cached Rose::DB object, which in turn will trigger Apache::DBI's ping mechanism to ensure that the database handle is fresh.

Putting all the pieces together, the following implementation of the init_db method in your Rose::DB::Object-derived common base class will ensure that database connections are shared and fresh under mod_perl and Apache::DBI, but unshared elsewhere:

package My::DB::Object;

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

use My::DB; # isa Rose::DB
...

BEGIN:
{
  if($ENV{'MOD_PERL'})
  {
    *init_db = sub { My::DB->new_or_cached };
  }
  else # act "normally" when not under mod_perl
  {
    *init_db = sub { My::DB->new };
  }
}

set_db DB

Add the Rose::DB-derived object DB to the cache. The DB's domain, type, and the db object itself (under the param name db) are all are passed to the build_cache_key method and the DB object is stored under the key returned.

AUTHOR

John C. Siracusa (siracusa@gmail.com)

COPYRIGHT

Copyright (c) 2007 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.