SuiteDB - suite metadata class
Shane P. McCarron <email@example.com>
Copyright 2004-2011 Applied Testing and Technology, Inc. All Rights Reserved.
use SuiteDB; # open the suite Database for writing my $db = new SuiteDB(1); # who is the creator of this suite? my $name = $db->creator() # and what is the description my $desc = $db->description() ; # release the database $db->release();
The SuiteDB 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 - usually a value prefixed by the module that wanted to store it. The purpose of this data store is to act as a general use storage facility for meta information related to items in a Test Suite (e.g., test session summary information).
The data structure of this object is optimized to be most efficient when used in conjunction with MLDBM and a single key hashed database (with short key names). 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).
a handle to the lock that is set for the object
a boolean that indicates whether the session is open read/write
a boolean to indicate if the file is from a DBM source
a hash of stored test data
numtests - the number of tests
locked - whether the set is locked or not
mtime - the last modification time of the set (really the last modification time of any session in the set).
summary - the summary of the set
sessions - the sessions that are in this set
assignedto - the list of assignees
description - the description
numtests - the number of tests
numUntested - the number still untested
isActive - whether the session is active or not
locked - whether the session is locked or not
mtime - the last modification time of the session
summary - the summary of the session
testset - the name of the associated test set
user - the name of the user who last changed the set
variable - the hash of session variables
sessHash - a hash of test sessions
the result of running the test.
The time when the test was run.
$suiteDb = new SuiteDB(name, [read/write [, timeout[, path]]]);
Creates a new suite database object, optionally opening a non-default target file and optionally making it writeable.
returns a reference to the suite database object.
Removes everything from the database.
returns true if it succeeded, false if it did not.
returns a path to the file.
returns the string-ified version of the entire database.
profName = $sdb->profName( [ name ] ) ;
Returns the name of the profile associated with this object. This ONLY happens if we are working in profile management mode.
returns the path saved into, or undef if the save failed.
deletes a session if it is defined.
deletes a set if it is defined.
@mlists = $suiteDB->multiLists() ;
$suiteDb->session(ID); $suiteDb->session(ID, ref);
With an ID parameter, retrieves the data for a specific session.
With an ID and a ref, sets the parameters for a session to ref.
returns the pointer a SuiteDB::Session object that represents the specific session.
The session meta data that is stored in this database includes:
to whom this session is assigned (comma separated list).
The session description.
The number of tests.
The number of tests still not tested.
Whether the session is currently active or not.
Is the session locked?
The last modification time of the session.
The summary of the session.
The test set to which this session is attached.
The last user to modify the session.
A hash of all variables defined for the session.
@sessionList = $suiteH->sessionList() ; @sessionList = $suiteH->sessionList(set) ; # get the list of sessions that have no test set @sessionList = $suiteH->sessionList(undef, 1) ;
$setHash = $suiteDb->set(ID); $setHash = $suiteDb->set(ID, ref);
With an ID parameter, retrieves the data for a specific set.
With an ID and a ref, sets the parameters for a set to ref.
Adds a lastChangeTime key to the dataset when updating a test set. Returns the pointer to the data for a specific set.
Returns a reference to an object that has test set meta data, including:
@setList = $suiteDb->setList( [ setGroup [, children ] ] ) ;
setGroup is an optional testset group name. If provided, only sets within that group are returned. If set to "", then only sets in NO group will be returned.
if the optional children parameter is true, then sets in the setGroup and all child set groups will be returned.
$suiteDb->testMap(UUID); $suiteDb->testMap(UUID, ref);
With an UUID parameter, retrieves the data for a specific testcase.
With an UUID and a ref, sets the parameters for a testcase map to ref.
returns the pointer a SuiteDB::TestMap object that represents the specific test case.
The test case meta data that is stored in this database includes:
$time = $suiteDb->lastEditUpdate() ;
$time = $suiteDb->lastFolderUpdate() ;
$time = $suiteDb->lastReqEditUpdate() ;
$time = $suiteDb->lastReqFolderUpdate() ;
$time = $suiteDb->lastRunUpdate() ; $time = $suiteDb->lastRunUpdate(setName) ;
$time = $suiteDb->lastUserPermUpdate() ; $time = $suiteDb->lastUserPermUpdate( timeStamp) ;
Returns the timestamp of the last time the user permission table for this suite was updated. If the table does not exist, returns 0.
$tests = $suiteDb->numReqs() ;
$sessCount = $suiteDb->numSessions( [num] ) ;
$setCount = $suiteDb->numSets( [num] ) ;
$tests = $suiteDb->numTests() ;
$val = $suiteDb->dirtyFlag( [ state ] ) ;
If state is supplied, it is a value to set. When state is 0, the data is NOT dirty. When state is 1, the associated "Run" data was updated, and the data is dirty. When state is 2, the associated "Edit" data was updated and the data is dirty.
Returns undef if the database is not writeable. Otherwise returns the current value of the dirtyFlag state;
$rRef = $suiteDb->results( [ $rRef ] ) ;
$rRef is an optional reference to a results object. If provided, that object is put into the suiteDB cache. Otherwise, the object currently in the cache is returned.
$permRef = $suiteDb->userPerms( [ $data ] ) ;
If the optional $data parameter is provided, the data is updated to that hash ref.
Returns a reference to a hash that maps userids to access level numbers.
$vRef = $suiteDb->variables( [ $vRef ] ) ;
$vRef is an optional reference to a VariableSet object. If provided, that object is put into the suiteDB cache. Otherwise, the object currently in the cache is returned.
$rRef = $suiteDb->rfields( [ $rRef ] ) ;
$rRef is an optional reference to a requirements field object. If provided, that object is put into the suiteDB cache. Otherwise, the object currently in the cache is returned.
Note that ReqFields uses the Parent base class, so we need to be certain to NOT attempt to serialize that part of the object.
($fieldRef, $orderRef) = $suiteDb->rundata( [ $runRef, $orderRef ] ) ;
$runRef is an optional reference to a testFields hash from TestSession. If provided, that object is put into the suiteDB cache. Otherwise, the object currently in the cache is returned.
$orderRef is an optional reference to a list of defined rundata fields in order. If provided, that object is put into the suiteDB cache. Otherwise, the object currently in the cache is returned.
Note that unlike other suiteDB caching objects, this one will NOT automatically acquire the data if it is not in the cache.
$sRef = $suiteDb->schema( [ $sRef [, update ] ] ) ;
$sRef is an optional reference to a schema object. If provided, that object is put into the suiteDB cache. Otherwise, the object currently in the cache is returned.
$update is a flag. If true, then the cached image is updated even if an sRef is not passed in.
$vset = $suiteDb->dirtyFlag( [ curSet ] ) ;
If curSet is supplied, it is used as a handle to a variable set object for the suiteDB. Otherwise, one is initialized.
Returns a handle to a variable set.
Ensures the caches and this database are locked.
Ensures the caches and this database are unlocked.
$fref = $sdb->field( columnName )
columnName is the name of a SQL table column.
Returns a reference to an object that supports (at least) the isDate method.
my $tname = $sdb->SQL_tname;
Returns the name of the table for this object.
$sdb->SQL_updateTestSession(sessNum, hash) ;
sessNum is the ID of the test session to update.
hash is the data to populate the test session record with.
SQL_insertMulti(sessNum, sdata, fname );
sessNum is the session number we are updating.
sdata is a reference to the session meta data hash.
fname is the name of the field to populate.
@cols = $suiteDB->SQL_tableDef( tname ) ;
tname is the name of a SQL table
Returns a list item per column, formatted for use in a CREATE statement.
@cols = $suiteDB->SQL_tableFields( tname ) ;
tname is the name of a SQL table.
Returns a list of fields that are used in the table.
my @tlist = $sdb->SQL_tlist();
Returns a list of all tables this object will operate upon.
$sqltype = $sdb->SQL_type(fref)
fref is a reference to a session variable definition.
This is just a thin veneer over the base ApTest::DBI type method, which will interrogate the underlying database and pick the best type. This function ascertains the base ATM type and passes that to the parent method, since Schema fields use a combination of type and style to define the actual "type".
Returns the most likely SQL type to use for the field.
$val = $sdb->SQL_value(fref, value) ;
fref is a reference to a Variable object.
value is the value to use.
Returns a suitable quoted value.
SuiteDB::TestMap - class for manipulating a mapping from tests to sessions.
$tmap = new SuiteDB::TestMap(UUID) ;
Creates a TestMap object. Returns a reference to the created object.
my $entry = $tmap->entry(sessnum) ;
sessnum is a session number - note that these are NOT stored with leading zeroes.
Returns a reference to the hash entry for this entry, or undef if there is no entry for the session.
$num = $tmap->numEntries() ;
Returns the number of result entries ;
my @list = $tmap->sortedList( direction )
direction is a boolean - false means descending, true means ascending
Returns a list of hash entries sorted in the described order
$tmap->update( $session, $href ) ;
session is the session number to update.
href is a reference to a hash that contains at least a 'result' and a 'when' entry.
SuiteDB::Session - class for manipulating session metadata
$session = new SuiteDB::Session(sessnum) ;
Creates a session object. Returns a reference to the created object.
$value = $session->defaultVariable() ;
Returns the value of the variable from the session, or the default value if the session has no setting for the variable.
the name of the variable.
returns the value of variable in a scalar context.
my $refreshable = $session->refreshable();
Returns true if refreshable, false if not. Defaults to true.
my $count = $session->resCounter( resultName ) ;
Returns the number of times that result is currently set for this session.
$dname = $session->displaySetName() ;
my $bool = $sess->checkSession( filtRef ) ;
filtRef is a reference to a hash of filters. filter settings are:
sesslist - list of sessions (rarely used) sessnumLow - low end of range of session numbers sessnumHigh - high end of range of session numbers users - list of modifying users assignees - list of assigned users testsets - list of test sets to match schedule - schedule settings locked - locked or unlocked date - the last mod date if it is interesting; also startdate and enddate for range run - types of "run" VAR_* - session variable selections
Returns true of the session passes the filters, false if it does not.