view release on metacpan or  search on metacpan

lib/Class/DBI/Cacheable.pm  view on Meta::CPAN

package Class::DBI::Cacheable;

use strict;
use warnings;
use base qw( Class::DBI::ObjectCache Class::DBI );
use CLASS;

our $VERSION = 0.03;

=head1 NAME

Class::DBI::Cacheable - Class::DBI object cache framework

=head1 SYNOPSIS

    package YourApp::DB;
    use base 'Class::DBI::Cacheable';
    __PACKAGE__->set_db( Main => 'dbi:Pg:dbname=database', 'username', 'password' );

=head1 DESCRIPTION

Class::DBI::Cacheable transparently acts as a cacheing wrapper around L<Class::DBI>, storing
retrieved and created data in a local object cache, and returning data out of the cache
wherever possible.

Intended for better performance of L<Class::DBI>-based applications, this can prevent unnecessary
database queries by using previously-retrieved object data rather than having to go to the
database server every time a object is retrieved.

It is highly configurable so you can customize both on an per-application and per-class basis
the directory root where objects are stored, expire times, and other important parameters.

=head1 Method Reference

=cut

=head2 CLASS->retrieve( [args] )

This method overrides the C<retrieve()> method of L<Class::DBI>, and adds
caching capabilities.  It first constructs a cache key from the supplied
arguments, and tries to retrieve that object from the data store.  If a
valid object is returned, that is given to the caller and the entire
L<Class::DBI>->retrieve method is bypassed.

However, in the event the object does not exist in the cache, Class::DBI
is used to retrieve the object.

=cut

sub retrieve {
    my $class = shift;

    my $key = $class->getCacheKey(\@_);
    if ($class->can('getCache')) {
        my $obj = $class->getCache($key);
        return $obj if (defined($obj));
    }

    return $class->SUPER::retrieve(@_);
}

=head2 CLASS->construct(data)

This method overrides the C<construct()> method of L<Class::DBI>, which is responsible
for constructing an object from searched or otherwise retrieved database data.  This
method circumvents this system to try and retrieve a cached object first.  Next, the
real C<construct()> method is called, after which this data is then stored in the cache.

=cut

sub construct {
    my $class = shift;
    my $data = shift;

    if ($class->can('getCache')) {
        my $obj = $class->getCache($data);
        if (defined($obj)) {
            return $obj;
        }
    }

    my $obj = $class->SUPER::construct($data);