NAME

SimpleDB::Class::Cache - Memcached interface for SimpleDB.

VERSION

version 1.0503

DESCRIPTION

An API that allows you to cache item data to a memcached server. Technically I should be storing the item itself, but since the item has a reference to the domain, and the domain has a reference to the simpledb object, it could cause all sorts of problems, so it's just safer to store just the item's data.

SYNOPSIS

            

              
              
use SimpleDB::Class::Cache;
my $cache = SimpleDB::Class::Cache->new(servers=>[{host=>'127.0.0.1', port=>11211}]);
$cache->set($domain->name, $id, $value);
my $value = $cache->get($domain->name, $id);
my ($val1, $val2) = @{$cache->mget([[$domain->name, $id1], [$domain->name, $id2]])};
$cache->delete($domain->name, $id);
$cache->flush;
            
          

METHODS

These methods are available from this class:

new ( params )

Constructor.

params

A hash containing configuration params to connect to memcached.

servers

An array reference of servers (sockets and/or hosts). It should look similar to:

            

              
              
[
   { host => '127.0.0.1', port=> '11211' },
   { socket  => '/path/to/unix/socket' },
]
            
          

servers ( )

Returns the array reference of servers passed into the constructor.

memcached ( )

Returns a Memcached::libmemcached object, which is constructed using the information passed into the constructor.

fix_key ( domain, id )

Returns a key after it's been processed for completeness. Merges a domain name and a key name with a colon. Keys cannot have any spaces in them, and this fixes that. However, it means that "foo bar" and "foo_bar" are the same thing.

domain

They domain name to process.

id

They id name to process.

delete ( domain, id )

Delete a key from the cache.

Throws SimpleDB::Class::Exception::InvalidParam, SimpleDB::Class::Exception::Connection and SimpleDB::Class::Exception.

domain

The domain name to delete from.

id

The key to delete.

flush ( )

Empties the caching system.

Throws SimpleDB::Class::Exception::Connection and SimpleDB::Class::Exception.

get ( domain, id )

Retrieves a key value from the cache.

Throws SimpleDB::Class::Exception::InvalidObject, SimpleDB::Class::Exception::InvalidParam, SimpleDB::Class::Exception::ObjectNotFound, SimpleDB::Class::Exception::Connection and SimpleDB::Class::Exception.

domain

The domain name to retrieve from.

id

The key to retrieve.

mget ( keys )

Retrieves multiple values from cache at once, which is much faster than retrieving one at a time. Returns an array reference containing the values in the order they were requested.

Throws SimpleDB::Class::Exception::InvalidParam, SimpleDB::Class::Exception::Connection and SimpleDB::Class::Exception.

keys

An array reference of domain names and ids to retrieve.

set ( domain, id, value [, ttl] )

Sets a key value to the cache.

Throws SimpleDB::Class::Exception::InvalidParam, SimpleDB::Class::Exception::Connection, and SimpleDB::Class::Exception.

domain

The name of the domain to set the info into.

id

The name of the key to set.

value

A hash reference to store.

ttl

A time in seconds for the cache to exist. Default is 3600 seconds (1 hour).

EXCEPTIONS

This class throws a lot of inconvenient, but useful exceptions. If you just want to avoid them you could:

            

              
              
my $value = eval { $cache->get($key) };
if (SimpleDB::Class::Exception::ObjectNotFound->caught) {
   $value = $db->fetchValueFromTheDatabase;
}
            
          

The exceptions that can be thrown are:

SimpleDB::Class::Exception

When an uknown exception happens, or there are no configured memcahed servers in the cacheServers directive in your config file.

SimpleDB::Class::Exception::Connection

When it can't connect to the memcached servers that are configured.

SimpleDB::Class::Exception::InvalidParam

When you pass in the wrong arguments.

SimpleDB::Class::Exception::ObjectNotFound

When you request a cache key that doesn't exist on any configured memcached server.

SimpleDB::Class::Exception::InvalidObject

When an object can't be thawed from cache due to corruption of some sort.

LEGAL

SimpleDB::Class is Copyright 2009-2010 Plain Black Corporation (http://www.plainblack.com/) and is licensed under the same terms as Perl itself.

cpanm SimpleDB::Class

perl -MCPAN -e shell
install SimpleDB::Class