NAME

Cache::Cache -- the Cache interface.

DESCRIPTION

The Cache interface is implemented by classes that support the get, set, remove, size, purge, and clear instance methods and their corresponding static methods for persisting data across method calls.

SYNOPSIS

To implement the Cache::Cache interface:

package Cache::MyCache;

use Cache::Cache;
use vars qw( @ISA );

@ISA = qw( Cache::Cache );

sub get
{
  my ( $self, $identifier ) = @_;

  # implement the get method here
}

sub set
{
  my ( $self, $identifier, $data, $expires_in ) = @_;

  # implement the set method here
}

# implement the other interface methods here

To use a Cache implementation, such as Cache::MemoryCache:

use Cache::Cache qw( $EXPIRES_NEVER $EXPIRES_NOW );
use Cache::MemoryCache;

my $options_hash_ref = { 'default_expires_in' => '10 seconds' };

my $cache = new Cache::MemoryCache( $options_hash_ref );

my $expires_in = '10 minutes';

$cache->set( 'Key', 'Value', $expires_in );

# if the next line is called within 10 minutes, then this 
# will return the cache value

my $value = $cache->get( 'Key' );

CONSTANTS

$SUCCESS

Typically returned from a subroutine, this value is synonymous with 1 and can be used as the typical perl "boolean" for true

$FAILURE

Typically returned from a subroutine, this value is synonymous with 0 and can be used as the typical perl "boolean" for false

$EXPIRES_NEVER

The item being set in the cache will never expire.

$EXPIRES_NOW

The item being set in the cache will expire immediately.

$EXPIRES_NEVER

The item being set in the cache will never expire.

METHODS

Clear( )

Remove all objects from all caches of this type.

Returns

Either $SUCCESS or $FAILURE

Purge( )

Remove all objects that have expired from all caches of this type.

Returns

Either $SUCCESS or $FAILURE

Size( $optional_namespace )

Calculate the total size of all objects in all caches of this type.

Returns

The total size of all the objects in all caches of this type.

new( $options_hash_ref )

Construct a new instance of a Cache::Cache

$options_hash_ref

A reference to a hash containing configuration options for the cache. See the section OPTIONS below.

clear( )

Remove all objects from the namespace associated with this cache instance.

Returns

Either $SUCCESS or $FAILURE

get( $identifier )

Fetch the data specified.

$identifier

A string uniquely identifying the data.

Returns

The data specified.

get_object( $identifier )

Fetch the underlying Cache::Object object that is used to store the cached data. This will not trigger a removal of the cached object even if the object has expired.

$identifier

A string uniquely identifying the data.

Returns

The underlying Cache::Object object, which may or may not have expired.

purge( )

Remove all objects that have expired from the namespace associated with this cache instance.

Returns

Either $SUCCESS or $FAILURE

remove( $identifier )

Delete the data associated with the $identifier from the cache.

$identifier

A string uniquely identifying the data.

Returns

Either $SUCCESS or $FAILURE

set( $identifier, $data, $expires_in )

$identifier

A string uniquely identifying the data.

$data

A scalar or reference to the object to be stored.

$expires_in

Either the time in seconds until this data should be erased, or the constant $EXPIRES_NOW, or the constant $EXPIRES_NEVER. Defaults to $EXPIRES_NEVER. This variable can also be in the extended format of "[number] [unit]", e.g., "10 minutes". The valid units are s, second, seconds, sec, m, minute, minutes, min, h, hour, hours, w, week, weeks, M, month, months, y, year, and years. Additionally, $EXPIRES_NOW can be represented as "now" and $EXPIRES_NEVER can be represented as "never".

Returns

Either $SUCCESS or $FAILURE

size( )

Calculate the total size of all objects in the namespace associated with this cache instance.

Returns

The total size of all objects in the namespace associated with this cache instance.

OPTIONS

The options are set by passing in a reference to a hash containing any of the following keys:

namespace

The namespace associated with this cache. Defaults to "Default" if not explicitly set.

default_expires_in

The default expiration time for objects place in the cache. Defaults to $EXPIRES_NEVER if not explicitly set.

PROPERTIES

get_namespace( )

The namespace of this cache instance

get_default_expires_in( )

The default expiration time for objects placed in this cache instance

get_identifiers( )

The list of identifiers specifying objects in the namespace associated with this cache instance

SEE ALSO

Cache::Object, Cache::MemoryCache, Cache::FileCache, Cache::SharedMemoryCache, and Cache::SizeAwareFileCache

AUTHOR

Original author: DeWitt Clinton <dewitt@unto.net>

Last author: $Author: dclinton $

Copyright (C) 2001 DeWitt Clinton