ApTest Manager documentation: API: TestDB

NAME
AUTHOR
COPYRIGHT
SYNOPSIS
DATA STRUCTURE
METHODS

new - open the testDB
initialize - reset the database file.
numTests - accessor for the number of stored tests
path - get/set the path to the cache file
print - print the contents of the testDB
deleted - check if a file is already in $deletedDir
recycled - check if a file is already in the trash
save - save the database
allTests - return the list tests, including deleted ones
tests - return the list of defined tests
test - accessor for test data
testByUUID - accessor for test case name by UUID
delete - delete a test from the database
suiteDB - Accessor for a suiteDB handle.
updateSuiteDB - update the suite database
Unlock - override master Unlock to clear UUID cache

SYNOPSIS

use TestDB;

Open the cache Database for writing
my $db = new TestDB(1);

get a handle to the whole test database
$data = $db->test();

get a handle to a specific test's data
$data = $db->test($testID);

release the database
$db-E<gt>release();

The TestDB object is a generic multi-level data structure storage facility. The data stored in this facility is expected to be keyed by a unique value - probably the ID of the test case.

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 stored test data; {data}->{ID}; {data}->{ID+SESSION}

METHODS

new - open the testDB

$tdb = new TestDB(suite, [read/write [, timeout[, path]]]);

Creates a new test database object, optionally opening a non-default target file and optionally making it writeable.

read/write: boolean set to True if the test database needs to be writeable or False if it can be readOnly.
timeout: the number of seconds to wait for a lock. Defaults to 60 seconds.
path: a path to an alternate database (the default is implementation defined).

returns a reference to the test database object.

initialize - reset the database file.

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

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

numTests - accessor for the number of stored tests

$tdb->numTests();

returns the number of tests in the database.

path - get/set the path to the cache file

returns a path to the cache file.

print - print the contents of the testDB

$tdb->print();
$tdb->print(ID);

returns the string-ified version of the entire database, or just the contents of the test ID.

deleted - check if a file is already in $deletedDir

$res = $tdb->deleted(name) ;

Returns true if the file is in $deletedDir, and false if it is not.

recycled - check if a file is already in the trash

$res = $tdb->recycled(name) ;

Returns true if the file is in the recycle bin, and false if it is not.

save - save the database

returns the path saved into, or undef if the save failed.

allTests - return the list tests, including deleted ones

returns a list of all tests

tests - return the list of defined tests

returns a list of defined tests

test - accessor for test data

$tdb->test();
$tdb->test(ID);
$tdb->test(ID, ref);

With no parameter, retrieves a pointer to the raw test database hash.

With an ID parameter, retrieves the data for a specific ID.

With an ID and a ref, sets the parameters for a test to ref.

returns the pointer to the entire hash, or to the data for a specific test.

testByUUID - accessor for test case name by UUID

Returns the current ID for a test case that matches the UUID. Returns undef if there is no such test case.

delete - delete a test from the database

$tdb->delete($test);

deletes a test if it is defined. Also updates the collection of UUIDs so the test is no longer indexed.

suiteDB - Accessor for a suiteDB handle.

$suiteDb = $tdb->suiteDB();
$suiteDb = $tdb->suiteDB(handle);

handle is the handle to an existing suiteDB object.

Returns the handle to a SuiteDB object. If one is not already associated with the session, acquires one in write mode.

updateSuiteDB - update the suite database

Updates the associated SuiteDB, if there is one, to ensure the last edit time is correct.

Returns undef if there is no SuiteDB associated with this session, 0 if the update failed, and 1 if it succeeded.