NAME

Spamtrak::DB - Database management for the Spamtrak system.

SYNOPSIS

 use Spamtrak::DB;

constructors $db = Open Spamtrak::DB $filename; $db = Create Spamtrak::DB $filename;

methods $value = $db->Get($key); $db->Put($key, $value); $filename = $db->Filename(); $db->Dump(-file => $filename, -verbose => $boolean); $db->Load(-file => $filename, -verbose => $boolean); $newdb = $db->Age(-verbose => $boolean);

DESCRIPTION

The Spamtrak::DB object is the interface to the Spamtrak database. The current implementation is built on the perl DB_File package. Although there are better choices (such as BerkeleyDB), this package is readily available.

The Open Constructor

    $db = Open Spamtrak::DB $filename;

Opens up the named Spamtrak database. If the database does not already exist, it will be created. In the current implementation, the database will be locked from all other processes until closed. If the open fails, a diagnostic is generated and the program terminates.

The Create Constructor

    $db = Create Spamtrak::DB $filename;

Creates a new Spamtrak database. If the database already exists, an error is raised. In the current implementation, the database will be locked from all other processes until closed. In the event of error, a diagnostic is generated and the program terminates.

The Get Method

    $value = $db->Get($key);

Performs a database lookup on the indicated ``$key'' and returns the associated value. If the ``$key'' is not in the database, then returns ``undef.''

The Put Method

    $db->Put($key, $value);

Performs a database insert for indicated ``$key'' and ``$value''. If the ``$key'' already exists in the database, then its value is replaced. The return value is the ``$value''.

The Filename Method

    $filename = $db->Filename();

Returns the filename of the Spamtrak database associated with ``$db''.

The Dump Method

    $db->Dump([ -file => $filename, -verbose => $boolean]);

Generate a flat file dump of the database. If -file is specified, then the dump goes to the indicated $filename. If not, the dump is to stdout. The -verbose flag, when set, enables some status messages.

The Load Method

    $db->Load([-file => $filename, -verbose => $boolean]);

Loads a database from a flat file dump. If -file is specified, the indicated $filename is loaded. If not, the dump read from stdin. The -verbose flag, when set, enables some status messages.

The Age Method

    $newdb = $db->Age(-ndays => $ndays, [-verbose => $boolean]);

The score values are aged $ndays days. A new database is created with the aged values, and a database object is returned. The -verbose flag, when set, enables some status messages.

BUGS

There are some significant drawbacks that result from using DB_File as the underlying database.

First, it does not offer a reliable locking mechanism. Therefore the Open and Create constructors assert an exclusive lock on the database file, that is released only when the object is destroyed. Fortunately, most operations run to completion so quickly, so this shouldn't be a problem.

Second, a sequential scan cannot be used to reliably read-modify-write all elements in the database. Therefore, the Age method saves its results into a new database.

SEE ALSO

spamtrak(1), Spamtrak(3), DB_File(3)

AUTHOR

 Chip Rosenthal
 Unicom Systems Development
 <chip@unicom.com>

 $Id: Spamtrak_DB.pm,v 1.1 2002/07/27 00:29:59 chip Exp $