NAME

DBIx::SQLEngine::Record::Cache - Avoid Repeated Selects

SYNOPSIS

Setup: Several ways to create a class.

  my $sqldb = DBIx::SQLEngine->new( ... );

  $class_name = $sqldb->record_class( $table_name, undef, 'Cache' );
  
  $sqldb->record_class( $table_name, 'My::Record', 'Cache' );
  
  package My::Record;
  use DBIx::SQLEngine::Record::Class '-isasubclass', 'Cache';  
  My::Record->table( $sqldb->table($table_name) );

Cache: Uses Cache::Cache interface.

  $class_name->use_cache_style('simple');

  # requires Cache::FastMemoryCache
  $class_name->use_cache_style('active'); 

  use Cache::Cache;
  $class_name->cache_cache( $my_cache_cache_object );

Basics: Layered over superclass.

  # Fetches from cache if it's been seen before
  $record = $class_name->fetch_record( $primary_key );

  # Fetches from cache if we've run this query before
  @records = $class_name->fetch_select(%clauses)->records;
  
  # Clears cache so it's seen by next select query
  $record->insert_record();
  
  # Clears cache so it's seen by next select query
  $record->update_record();
  
  # Clears cache so it's seen by next select query
  $record->delete_record();

DESCRIPTION

This package provides a caching layer for DBIx::SQLEngine::Record objects.

Don't use this module directly; instead, pass its name as a trait when you create a new record class. This package provides a multiply-composable collection of functionality for Record classes. It is combined with the base class and other traits by DBIx::SQLEngine::Record::Class.

CACHE INTERFACE

Cache Configuration

cache_cache()

  $record_class->cache_cache() : $cache_cache
  $record_class->cache_cache( $cache_cache )

Gets or sets the cache object associated with this record class.

If no cache has been set for a given class, no caching is performed.

Cache Object Requirements: This package in intended to work with cache object that use the Cache::Cache interface. However, any package which support the limited cache interface used by this package should be sufficient.

Two small classes are included that support this interface; see DBIx::SQLEngine::Cache::TrivialCache and DBIx::SQLEngine::Cache::BasicCache.

The following methods are used

Constructor.

get_namespace()

Used to differentiate one cache object from another.

get()

Fetch a value from the cache, if it is present.

set()

Set a value in the cache.

clear()

Clear some or all values in the cache.

Cache Operations

cache_key()

  $record_class->cache_key( $key ) : $string_value
  $record_class->cache_key( \@key ) : $string_value
  $record_class->cache_key( \%key ) : $string_value

Returns the string value to be used as a cache key. The argument may be an existing string, a reference to a shallow array whose elements will be joined with "\0/\0", or any other reference value which will be stringified by Storable.

cache_get()

  $record_class->cache_get( $key ) : $value
  $record_class->cache_get( $key ) : ( $value, $updater_code_ref )

Returns the cached value associated with this key, if any. If called in a list context, also returns a reference to a subroutine which will save a new value for that key.

cache_set()

  $record_class->cache_set( $key, $value )

Caches this value under the provided key.

cache_get_set()

  $record_class->cache_get_set( $key, $code_ref, @args ) : $value

Returns the curent value provided by a cache_get on the provided key, or if it is undefined, invokes the subroutine reference with any additional arguments provided, and saves the subroutine's return value as the cached value.

cache_clear()

  $record_class->cache_clear()
  $record_class->cache_clear( $key )

Clear all values from the cache, or just those associated with the given key.

Cache Logging

CacheLogging()

  $record_class->CacheLogging() : $level
  $record_class->CacheLogging( $level )

Sets the logging level associated with a given class.

cache_log_operation()

  $record_class->cache_log_operation( $cache, $operation, $key )

Does nothing unless a CacheLogging level is set for this class.

Uses warn() to print a message to the error log, including the key string used, and the operation, which will be one of "hit", "miss", "write", and "clear".

If the level is greater than one, the message will also include a history of prior operations on this key.

Cache Styles

define_cache_styles()

  DBIx::SQLEngine->define_cache_styles( $name, $code_ref )
  DBIx::SQLEngine->define_cache_styles( %names_and_code_refs )

Define a named caching style. The code ref supplied for each name should create and return an object from the Cache::Cache hierarchy, or another caching class which supports the interface described in the "Cache Object Requirements" section above.

cache_styles()

  DBIx::SQLEngine->cache_styles() : %names_and_info
  DBIx::SQLEngine->cache_styles( $name ) : $info
  DBIx::SQLEngine->cache_styles( \@names ) : @info
  DBIx::SQLEngine->cache_styles( $name, $info, ... )
  DBIx::SQLEngine->cache_styles( \%names_and_info )

Accessor for global hash mapping cache names to initialization subroutines.

use_cache_style()

  $class_name->use_cache_style( $cache_style_name )
  $class_name->use_cache_style( $cache_style_name, @options )

Uses the named caching definition to create a new cache object, and associates it with the given class.

Use one of the predefined caching styles described in the "Default Caching Styles" section below, or define your own cache styles with define_cache_styles.

Default Caching Styles: The following cache styles are predefined. Except for 'simple', using any of these styles will require installation of the Cache::Cache distribution.

'simple': Uses DBIx::SQLEngine::Cache::TrivialCache.
'live': Uses Cache::FastMemoryCache with a default expiration time of 1 seconds.
'active': Uses Cache::FastMemoryCache with a default expiration time of 5 seconds.
'stable': Uses Cache::FastMemoryCache with a default expiration time of 30 seconds.
'file': Uses Cache::FileCache with a default expiration time of 30 seconds.

Examples:

  # requires DBIx::SQLEngine::Cache::TrivialCache
  $class_name->use_cache_style('simple');

  # requires Cache::FastMemoryCache from CPAN
  $class_name->use_cache_style('active');

FETCHING DATA (SQL DQL)

Each of these methods provides a cached version of the superclass method. The results of queries are cached based on the SQL statement and parameters used.

fetch_select()

  $class_name->fetch_select( %select_clauses ) : $record_set

Retrives records from the table using the provided SQL select clauses.

fetch_one_record()

  $sqldb->fetch_one_record( %select_clauses ) : $record_hash

Retrives one record from the table using the provided SQL select clauses.

select_record()

  $class_name->select_record ( $primary_key_value ) : $record_obj
  $class_name->select_record ( \@compound_primary_key ) : $record_obj
  $class_name->select_record ( \%hash_with_primary_key_value ) : $record_obj

Fetches a single record by primary key.

select_records()

  $class_name->select_records ( @primary_key_values_or_hashrefs ) : $record_set

Fetches a set of one or more records by primary key.

visit_select()

  $class_name->visit_select ( $sub_ref, %select_clauses ) : @results
  $class_name->visit_select ( %select_clauses, $sub_ref ) : @results

Calls the provided subroutine on each matching record as it is retrieved. Returns the accumulated results of each subroutine call (in list context).

To Do: This could perform caching of the matched records, but currently does not.

The conversion of select clauses to a SQL statement is performed by the sql_select method:

sql_select()

  $class_name->sql_select ( %sql_clauses ) : $sql_stmt, @params

Uses the table to call the sql_select method on the current SQLEngine driver.

Vivifying Records From The Database

These methods are called internally by the various select methods and do not need to be called directly.

record_from_db_data()

  $class_name->record_from_db_data( $hash_ref )

Calls SUPER method, then cache_records().

record_set_from_db_data()

  $class_name->record_set_from_db_data( $hash_array_ref )

Calls SUPER method, then cache_records().

cache_records()

  $class_name->cache_records( @records )

Adds records to the cache.

EDITING DATA (SQL DML)

Insert to Add Records

After constructing a record with one of the new_*() methods, you may save any changes by calling insert_record.

insert_record

  $record_obj->insert_record() : $flag

Attempt to insert the record into the database. Calls SUPER method, so implemented using MIXIN.

Clears the cache.

Update to Change Records

After retrieving a record with one of the fetch methods, you may save any changes by calling update_record.

update_record

  $record_obj->update_record() : $record_count

Attempts to update the record using its primary key as a unique identifier. Calls SUPER method, so implemented using MIXIN.

Clears the cache.

Delete to Remove Records

delete_record()

  $record_obj->delete_record() : $record_count

Delete this existing record based on its primary key. Calls SUPER method, so implemented using MIXIN.

Clears the cache.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 95:: You can't have =items (as at line 99) unless the first thing after the =over is an =item