NAME

CAM::Template::Cache - Template files with database storage

LICENSE

Copyright 2005 Clotho Advanced Media, Inc., <cpan@clotho.com>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SYNOPSIS

use CAM::Template::Cache;
CAM::Template::Cache->setDBH($dbh);
CAM::Template::Cache->setExpiration(60*60); # seconds ago

my $key = $username.":".$pagetype;  # whatever you like
my $template = new CAM::Template::Cache($key);
$template->setExpiration(24*60*60); # seconds ago
if ($template->isFresh()) {
   $template->printCache();
} else {
   $template->setFilename($templateFilename);
   $template->addParams(blah blah);
   $template->print();
}

DESCRIPTION

CAM::Template provides an interface for parameter replacement in a template file. This package provides the additional functionality of storing the completed template in a MySQL database for later quick retrieval.

Use of the cached version of the template requires a unique key that will allow retrieval of the completed file, if present. The cache uses a time stamp and an expiration interval (default: 1 day) to decide if the cached copy is recent enough.

This module also includes the class methods setup() and clean() as convenience functions for initialization and maintenance of the cache database.

FUNCTIONS

new

new CACHEKEY

new CACHEKEY, DBIHANDLE

Create a new template object. To get the caching functionality, the cachekey is required, and must uniquely identify the content of interest. If the cachekey is not specified, then this template behaves without any of the caching infrastructure.

If the database handle is not set here, it must have been set previously via the class method setDBH().

Any additional function arguments (namely, a filename or replacement parameters) are passed on to the CAM::Template constructor.

setDBH DBI_HANDLE

Set the global database handle for this package. Use like this:

CAM::Template::Cache->setDBH($dbh);

setExpiration SECONDS

Set the duration for the cached content. If the cache is older than the specified time, the isFresh() method will return false.

Use like this:

CAM::Template::Cache->setExpiration($seconds);

or like this:

$template->setExpiration($seconds);

setTableName NAME

Set the name of the database table that is used for the cache.

Use like this:

CAM::Template::Cache->setTableName($name);

or like this:

$template->setTableName($name);

setUseLock 0|1

Set the global preference for whether to lock the database table when doing a save (since save() does both a delete and an insert). Turning off lock may lead to a (rare!) race condition where two inserts happen, leading to a duplicate record. Turning on locking may lead to performance bottlenecks. The default is off.

isFresh

Returns a boolean indicating whether the cache is present and whether it is up to date.

clear

clear CACHEKEY

Invalidates the existing cached data for this key. This can be called as a class method, in which case the cache key argument is required. As an instance method, the instance's key is used if a key is not passed as an argument.

toStringCache

Returns the cached content, or undef on failure. If isFresh() has already been called, information is recycled from that inquiry.

printCache

Prints the cached content. Returns a boolean indicating success or failure. If isFresh() has already been called, information is recycled from that inquiry.

save CONTENT

Record the content in the database. This is typically only called from within toString(), but is provided here for the benefit of subclasses.

toString

Same as CAM::Template->toString except that the result is stored in the database.

print

Same as CAM::Template->print except that the result is stored in the database.

setup

setup DBIHANDLE, TABLENAME

Create a database table for storing cached templates. This is not intended to be called often, if ever. This is a class method. It should be used in a separate script like this:

use DBI;
use CAM::Template::Cache;
my $dbh = DBI->connect(...);
CAM::Template::Cache->setup($dbh, "TemplateCache");

clean

clean DBIHANDLE, TABLENAME, SECONDS

Cleans out all records older than the specified number of seconds. This is a class method. It should be used in a separate script like this, likely running as a cron:

use DBI;
use CAM::Template::Cache;
my $dbh = DBI->connect(...);
CAM::Template::Cache->clean($dbh, "TemplateCache", 2*60*60);

AUTHOR

Clotho Advanced Media Inc., cpan@clotho.com

Primary developer: Chris Dolan