view release on metacpan or  search on metacpan

lib/Bio/EnsEMBL/DBSQL/Support/BaseCache.pm  view on Meta::CPAN

=head1 NAME

Bio::EnsEMBL::DBSQL::Support::BaseCache - Base cache code 

=head1 SYNOPSIS

  package Cache;
  
  use base qw/Bio::EnsEMBL::DBSQL::Support::BaseCache/;
  
  sub build_cache {
    return {}; #sends back a very basic cache which is a hash
  }
  
  1;
  
  #In use
  $cache->put(1, 'a');
  is($cache->get(1), 'a');
  is($cache->put(1, 'b'), 'a'); #put returns the object it replaced
  is($cache->delete(1), 'b');   #delete returns the object it removed
  
  is_deeply([$cache->cache_keys()], [1]);
  
  $cache->clear_cache();
  
  is($cache->size(), 0);

  #Try using SQL - cache will be consulted accordingly
  my $ids = $cache->get_by_sql('select dbid from table where val like ?', ['someval%']);

=head1 DESCRIPTION

A base class used for holding methods common to all cache implementations. 
Never use this class to do direct caching instead use one of the following

=over 8

=item C<Bio::EnsEMBL::DBSQL::Support::LruIdCache>

=item C<Bio::EnsEMBL::DBSQL::Support::FullIdCache>

=back

To provide exta functionality to the caches you should override one of the above
classes and extend. Caches work when you use inheritence by composition in their
target adaptor.

=head1 METHODS

=cut

package Bio::EnsEMBL::DBSQL::Support::BaseCache;
$Bio::EnsEMBL::DBSQL::Support::BaseCache::VERSION = '114.0.0';
use strict;
use warnings;

use Bio::EnsEMBL::Utils::Exception qw/throw/;
use Bio::EnsEMBL::Utils::Scalar qw/assert_ref/;
use Scalar::Util qw/weaken/;

=head2 new

  Arg [1]    : Bio::EnsEMBL::DBSQL::BaseAdaptor $db_adaptor
  Example    : $cache = CacheInheritedFromBaseCache->new($db_adaptor);
  Description: Creates a new cache class which handles all the basics of
               working with a cache apart from what that cache implementation
               is (apart from a hash)
  Returntype : Bio::EnsEMBL::DBSQL::Support::BaseCache
  Exceptions : none
  Caller     : BaseAdaptors
  Status     : Beta

=cut

sub new {
  my ($class, $adaptor) = @_;
  
  $class = ref($class) || $class;
  my $self = bless({}, $class);
  
  throw "Need an adaptor instance to delegate calls to" unless $adaptor;
  $self->adaptor($adaptor);
  
  return $self;
}

=head2 adaptor

  Arg [1]    : Bio::EnsEMBL::DBSQL::BaseAdaptor $db_adaptor
  Description: Getter setter for the adaptor this serves as an ID cacher for
  Returntype : Bio::EnsEMBL::DBSQL::BaseAdaptor
  Exceptions : none
  Caller     : BaseAdaptors
  Status     : Beta

=cut


sub adaptor {
  my ($self, $adaptor) = @_;
  if(defined $adaptor) {
    assert_ref($adaptor, 'Bio::EnsEMBL::DBSQL::BaseAdaptor', 'adaptor');
  	$self->{'adaptor'} = $adaptor;
  	weaken($self->{'adaptor'});
  }
  return $self->{'adaptor'};
}

=head2 cache

  Description: Returns back a Hash implementing object and also calls 
               C<build_cache()> for an initialise on demand system
  Returntype : Hash
  Exceptions : none
  Caller     : BaseAdaptors and internal
  Status     : Beta

=cut

sub cache {
  my ($self) = @_;
  if(! defined $self->{cache}) {
    my $cache = $self->build_cache();
    $self->{cache} = $cache;
  }
  return $self->{cache};
}

=head2 delete_cache

  Example    : $cache->delete_cache();
  Description: Deletes the cache. Normally used to trigger a C<build_cache()> 
               call
  Returntype : none
  Exceptions : none
  Caller     : BaseAdaptors
  Status     : Beta

=cut

sub delete_cache {
  my ($self) = @_;
  delete $self->{cache};
  return;
}

=head2 get

  Arg [1]    : String key to retrieve
  Example    : $cache->put(1,'a'); is($cache->get(1), 'a');
  Description: Retrieves the value held in the cache. Can return undef if the
               value could not be found
  Returntype : Scalar value held in the cache or nothing
  Exceptions : If key was undefined
  Caller     : BaseAdaptors
  Status     : Beta

=cut

sub get {
  my ($self, $key) = @_;
  throw "No key given" unless defined $key;
  my $cache = $self->cache();
  if(exists $cache->{$key}) {