NAME

Data::Fallback - fallback through an array of levels till you find your data, cacheing where desired

DESCRIPTION

The simplest, good example for Data::Fallback, is cacheing a database to a conf file, then to memory. In general, the user supplies an array ref of hash refs (an object property named list), where each hash ref explains how to get data for that step. Each hash ref needs a package, which currently can be Memory, ConfFile, DBI, or WholeFile. Update acceptance can be set for each level.

Data::Fallback then goes through the array, checking for data, stopping when it finds said data, updates up the array, as requested, and returns the data.

A group can be thought of as a row and an item a column.

INFORMAL EXAMPLE

Start with a table foo.

column       data

------       ----
id           1
name         Chopper

and a file foo.cache. I offer two sets of hits, in a mod_perl of daemon environment, both trying to

SELECT id FROM foo WHERE name = 'Chopper'

Set 1
  Hit 1a
    Check memory    -> data not there
    Check foo.cache -> data not there
    Check db        -> data is there
    Update foo.cache
    Update memory
    Return id = 1

  Hit 1b
    Check memory    -> data is there
    Return id = 1

Set 2, after a restart
  Hit 2a
    Check memory    -> data not there
    Check foo.cache -> data is there
    Update memory
    Return id = 1

  Hit 2b
    Check memory    -> data is there
    Return id = 1

So, even after the restart, the database only gets hit once.

EXAMPLE

#!/usr/bin/perl -w

use strict;
use Data::Fallback;
use Carp qw(confess);

# I use dumper just to show some complex structures
use Data::Dumper;

# here I write out a couple files which I late clean up
# the idea is that the over file, overrides the default file

my $over_file    = "/tmp/data_fallback_over";
my $default_file = "/tmp/data_fallback_default";

open (FILE, ">$over_file") || confess "couldn't open $over_file: $!";
print FILE "key2 over2";
close(FILE);

open (FILE, ">$default_file") || confess "couldn't open $default_file: $!";
print FILE "key1 default1\nkey2 default2";
close(FILE);

my $self = Data::Fallback->new({

# list is an array ref of hash refs to fall through looking for data

  list => [
    {
      # accept_update says to update the conf
      accept_update => 'group',

      # this means to cache everything
      cache_level => 'all',

      # where to get the content
      content => $over_file,
    },
    {
      cache_level => 'all',
      content     => $default_file,
    },
  ],

  # need to name list
  list_name => 'test',

  # object global for package
  package => 'ConfFile',

  zeroth_hash => {
    ttl => '5 seconds',
  },
});
print $self->get('key2') . "\n";
print Dumper $self->{history};
print $self->get('key2') . "\n";
print Dumper $self->{history};
print $self->get('key1') . "\n";
print Dumper $self->{history};
print $self->get('key1') . "\n";
print Dumper $self->{history};
unlink $over_file, $default_file;

APOLOGIES

This perldoc isn't the best, but I plan on continued development for sometime. In other words, a better perldoc is to come. And a better test suite. If you feel so inclined to use Data::Fallback::Daemon, do so realizing that the protocol is sure to change. The TO_DO shows where the poject is headed.

THANKS

Thanks to Rob Brown, Paul Seamons, Allen Bettilyon and Dan Hanks for listening to my babblings and offering feedback. Thanks to Rob Brown for testing my first version. Also, thanks to Paul for Net::Server and helping me set up Data::Fallback::Daemon. Lincoln Stein's AUTHOR INFORMATION was borrowed from heavily.

AUTHOR

Copyright 2001-2002, Earl J. Cahill. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Address bug reports and comments to: cpan@spack.net.

When sending bug reports, please provide the version of Data::Fallback, the version of Perl, and the name and version of the operating system you are using.