NAME

Rose::DBx::CannedQuery::SimpleQueryCache - simple canned query cache

SYNOPSIS

  use Rose::DBx::CannedQuery::SimpleQueryCache;
  my $cache =
     Rose::DBx::CannedQuery::SimpleQueryCache->new(
       backend => CHI->new(...),
       args_to_key => \&my_converter
     );
  my $canned = $cache->get_query_from_cache(%desc);
  my $canned = $cache->add_query_to_cache($canned_query, %desc);
  $cache->remove_query_from_cache(%desc); # Drop one query
  $cache->clear_query_cache(); # Drop them all

DESCRIPTION

This class provides a simple API and default implementation for the query cache available through Rose::DBx::CannedQuery. The goal of the query cache is to simplify the structure of programs that use Rose::DBx::CannedQuery: code elsewhere can reuse a canned query with some frequency without being required to keep track of the query object across function calls or the like. Because query objects involve live database connections, the duration of caching, and the number of queries that can be cached, is generally limited. In particular, the default implementation does not contemplate freezing and thawing of query objects.

The behavior of the query cache is determined by two attributes:

ATTRIBUTES

backend

This is the object that provides the cache. It must implement get, set, remove, and clear methods; their behavior is fairly obvious from their names.

You may provide any cache object that is compatible with the above API; in particular, this is intended to accommodate cache modules that conform to the CHI API. If you do not, a default backend is used that provides a simple in-memory cache with no expiration or other active management.

args_to_key($args)

This is a code reference to a function that uses the contents of the hash reference $args to construct a key compatible with the query backend.

Rose::DBx::CannedQuery passes the arguments given to its constructor in $args. This means that the query cache may be aware of database connection information and SQL code, but will not know about bind parameter values for a specific execution of the canned query.

The default implementation uses the stringified form of all the arguments passed to it to generate the key. The order of arguments, whitespace within arguments, and alphabetic case of strings are not significant.

METHODS

Rose::DBx::CannedQuery::SimpleQueryCache objects provide the following methods to manage the query cache:

add_query_to_cache($query,$args)

Adds $query to the cache, using the key generated from $args, which must be a hash reference.

Returns $query if the backend's set method returns a true value, and whatever set returned otherwise.

get_query_from_cache($args)

Retrieves from the cache the query whose key is specified by $args. If a query object is retrived, but neither its "sth" in DBI nor the associated "dbh" in DBI has a true Active attribute, the object is deleted from the cache and discarded.

Returns the query object on success, and nothing on failure.

remove_query_from_cache($args)

Deletes the query object whose key is specified by $args from the cache.

Returns whatever the backend's remove method returns (the default backend returns the query object).

clear_query_cache()

Clears the query cache entirely.

Returns whatever the backend's clear method returns (the default backend returns a true value).

INTERNAL METHODS

Since Rose::DBx::CannedQuery::SimpleQueryCache is built using Moo, you have the option of changing its default behavior by creating a subclass that replaces its attribute defaults via the standard builder methods:

_build_backend

Creates the default object for the "backend". Currently returns an object implementing the simple hash-based cache described above. For more details about the required behavior of the cache backend, see the "backend" documentation above.

_build_args_to_key

Creates the default for the "args_to_key" function. Returns a code reference whose calling sequence is described under "args_to_key" above.

EXPORT

None.

SEE ALSO

Rose::DBx::CannedQuery, CHI

DIAGNOSTICS

Any message produced by an included package.

BUGS AND CAVEATS

Are there, for certain, but have yet to be cataloged.

VERSION

version 1.00

AUTHOR

Charles Bailey <cbail@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2015 by Charles Bailey

This software may be used under the terms of the Artistic License or the GNU General Public License, as the user prefers.