NAME

WebApp::Stored - Base class for all stored objects

VERSION

  Time-stamp: <2006-04-25 14:11:49 mailto:attila@stalphonsos.com>
  $Id: Stored.pm,v 1.19 2006/04/26 03:52:03 attila Exp $

SYNOPSIS

  use WebApp::Stored;
  blah;

DESCRIPTION

This class is not instantiateed directly. It is an abstract superclass used by classes that represent objects stored in a database, et al. It knows how to manage objects that are backed by a RDBMS, using a special hashref called $MAP in the subclass package. This hashref defines the structure of the table that represents object of this kind, and the code in this module knows how to store, retrieve, update and delete such things in the database, and enforces a simple convention on objects for which this is done.

WebApp::Stored->ConfigureCache $cache_type, options...

If $cache_type is a CGI::SpeedyCGI object, we pick the best type of cache available; we will try to use Cache::SharedMemoryCache first, and then fall back on Cache::MemoryCache, but that almost certainly won't be right, so it's best to specify. You can pass a $cache_type of shm as a shorthand for SharedMemoryCache, but any other kind of cache must be explicitly spelled out (omitting the Cache:: prefix). In this case, we also register a shutdown handler with SpeedyCGI upon successful creation of our cache.

Any other arguments are options to the cache constructor; see the POD for Cache::Cache for more details.

If we succeed in creating a cache, all database objects that we create will get thrown into it, indexed by their class name and primary key. The defaults we use for cache options are:

• default_expires_in: 5 minutes

Five minutes seems like plenty by default

• auto_purge_interval: 5 minutes

Again, seems reasonable. For a really busy server, you might want to crank this down a bit.

See the CacheStats class method for how to get information on how well the cache is working.

$string = WebApp::Stored->CacheStats()

%stats = WebApp::Stored->CacheStats();

In a scalar context, we return a string suitable for human consumption that reports cache usage statistics. In an array context, we return the raw statistics as a hash. The keys in the hash are:

• hits

Number of cache hits.

• misses

Number of cache misses

• loads

Number of objects that have been loaded into the cache.

• errors

Number of times a cache load failed due to some kind of error (could not figure out the key to use for some reason).

DETAILED DOCUMENTATION

This class exports the following interface:

delete

Delete the row or rows in the database that we represent. For single-row objects, this is the obvious thing. For multi-row objects, we can be told to tweak our criteria via arguments.

For instance, supposing we have the following table structure:

  create table thing ( owner varchar(32),
                       name varchar(32),
                       primary key(owner,name) );

So, a single owner can have multiple things. Assuming you had a class named Thing that inherited from WebApp::Stored in the usual way, then to load all of Jim's things:

  my $stuff = Thing->new(-dbh => $dbh, owner => 'Jim');

If we wanted to delete all of Jim's things, then

  $stuff->delete();

will do the trick. However, if we only wanted to delete his hotdog:

  $stuff->delete(name => 'hotdog');

By default, string equality is the test used to determine if a row matches the deletion criteria, but you can override that:

  $stuff->delete(-test => '~', name => '[Hh]ot[Dd]og');

The allowable values are ~ (regexp match), !~ (opposite of ~), eq, and ne. If more than one column is specified, then all of them must match.

Once you delete one of the rows, you should reload the object.

has_changed

flush

new [args=>vals]

as_string

AUTHOR

Sean Levy <mailto:snl@cluefactory.com>

COPYRIGHT AND LICENSE

(C) 2002-2006 by Sean Levy <mailto:snl@cluefactory.com>. all rights reserved.

This code is released under a BSD license. Please see the LICENSE file that came with the source distribution or visit http://cluefactory.com/oss/WebApp/license.html