NAME

DBIx::SQLEngine::Record::Trait::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 is not yet complete.

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 ) 

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.

new()

Constructor.

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.

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

Cache Operations

cache_get()

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

cache_set()

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

cache_get_set()

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

cache_clear()

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

Cache Logging

CacheLogging()

cache_log_operation()

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.

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 )

Defaults: 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::Record::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.

FETCHING DATA (SQL DQL)

fetch_select()

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

fetch_one_record()

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

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

select_records()

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

visit_select()

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

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_table()

  $class_name->record_from_table( $hash_ref )

Calls SUPER method, then cache_records().

record_set_from_table()

  $class_name->record_set_from_table( $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.

SEE ALSO

For more about the Record classes, see DBIx::SQLEngine::Record::Class.

See DBIx::SQLEngine for the overall interface and developer documentation.

See DBIx::SQLEngine::Docs::ReadMe for general information about this distribution, including installation and license information.

cpanm DBIx::SQLEngine

perl -MCPAN -e shell
install DBIx::SQLEngine