ApTest Manager documentation: API: CacheDB

NAME
AUTHOR
COPYRIGHT
SYNOPSIS
DATA STRUCTURE
METHODS

new - open the cacheDB
delete - delete a query from the cache
getQuery - retrieve the results for a query
numQueries - accessor for the number of cached queries
path - get the path to the cache file
print - print the contents of the cacheDB
queries - return the list of cached queries
queryName - determine a queryName based upon its selectors.
querySet - determine the base set for a query
selectors - accessor for selectors of a query
setQuery - set a query and its results in the database
suiteDir - accessor for test suite root
initialize - reset the cache file

EXAMPLES

SYNOPSIS

use CacheDB;

# Open the cache Database for writing
my $cache = new CacheDB(1);

# cache some query results
$queryName = $cache->setQuery($selectors, $results);

# derive the name for a query from its selectors
$queryName = $cache->queryName($selectors);

# retrieve the names of all the cached queries
$names = $cache->queries();

# retrieve the selectors of a cached query
$selectors = $cache->selectors($queryName);

# retrieve the results of a cached query
$results = $cache->result($queryName);

# delete a query
$result = $cache->delete($queryName);

# release the database
$cache->release();

The CacheDB object permits access to a database of cached queries and their results. The keys of the Cache Database are an encoded form of the query.

The data structure of this object is optimized to be most efficient when used in conjunction with MLDBM and a single key hashed database. This object CAN use serialized objects as well, but it is MUCH slower. Note that when using MLDBM, the save method doesn't do anything (except possibly for the first time it is called if the database had not yet been converted to MLDBM format).

DATA STRUCTURE

lock: a handle to the lock that is set for the object
writeable: a boolean that indicates whether the session is open read/write
usingDBM: a boolean to indicate if the file is from a DBM source
data->: a hash of cached queries and their results {data}->{name}

METHODS

new - open the cacheDB

$cacheRef = new CacheDB([read/write [, timeout]]);

Creates a new cache object, optionally making it writeable.

read/write: boolean set to True if the cache database needs to be writeable. Defaults to readOnly.
timeout: the number of seconds to wait for a lock. Defaults to 60 seconds.

returns a reference to the cache database object.

delete - delete a query from the cache

$cacheRef->delete($queryName);

deletes a query if it is defined.

getQuery - retrieve the results for a query

$results = $cacheRef->getQuery($queryName);

returns a handle to a hash of cached results, or undef if the query is not already cached.

numQueries - accessor for the number of cached queries

$cacheRef->numQueries();

returns the number of queries in the database.

path - get the path to the cache file

returns a path to the cache file.

print - print the contents of the cacheDB

$cacheRef->print();
$cacheRef->print(queryName);

returns the string-ified version of the entire database, or just the contents of the query queryName.

queries - return the list of cached queries

returns a list of cached query names.

queryName - determine a queryName based upon its selectors.

Determines the query name by sorting the selectors and their values, then creating a unique value based upon that data. The form of this value is: QUERY_field(val1[,val2...]);[field2(val1[,val2...]);...]

Note that in this field, all of the names and values are masked to upper-case, because field names and selector field values are by definition case-insensitive, and because the schema object maintains its hash of field definitions using upper-case keys.

returns the queryName for the defined selectors.

querySet - determine the base set for a query

This method looks for a queries that match as many selectors as possible, performing a best-fit algorithm by selector. The resulting set of IDs is the smallest sub-set that matches the selectors.

Returns a reference to a hash of IDs, or undef if there are no matches.

selectors - accessor for selectors of a query

$cacheRef->selectors(queryName);

returns pointer to selector hash (same structure used by TestSession) for the query queryName.

setQuery - set a query and its results in the database

$cacheRef->setQuery(selectors, results);

Sets the results of a query defined by selectors to the results defined by results. If the query was already defined in the database, its definition is overwritten.

selectors is a hash of arrays.

results is a hash of anything that needs to be stored.

Returns the name of the query (its key in the database).

suiteDir - accessor for test suite root

$cacheRef->suiteDir();
$cacheRef->suiteDir(path);

Gets/sets the path to the test suite data root. This defaults to the root of the test suite/data, and is currently imported from DB::DB.

initialize - reset the cache file

Removes all cached results from the database. Must have a write lock before you can do this.

returns true if it succeeded, false if it did not.

EXAMPLES

# Create a new session:

my $s = new TestSession("user");

$s->selector("Version", "5");
$s->selector("OEM", "Y");
$s->selector("Scope", "wml, wmlplus, wmlscript");
$s->selector("SimRunType", "auto, sim-auto");

my $numTests = $s-E<gt>selectTests();

print "Number of tests selected was $numTests\n";

$s->setVariables(); # brings in the default variables

$s->description("My test session");

# add in any special variables based upon other settings
$s->addVariables(); 

# save in the next available session as a serialized
# object, not a DBM file
my $sessId = $s->save(undef, "new");