NAME

ReqDB - requirements database class

AUTHOR

Shane P. McCarron <shane@aptest.com>

COPYRIGHT

Copyright 2002-2011 Applied Testing and Technology, Inc. All Rights Reserved.

SYNOPSIS

use ReqDB;

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

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

    get a handle to a specific requirement's data
    $data = $db->req($reqID);

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

The ReqDB object is a generic multi-level data structure storage facility. The data stored in this facility is keyed by the pathname associated with each requirement.

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 requirement data

{data}->{ID}

METHODS

new - open the requirementDB

$rdb = new ReqDB(suite, [read/write [, timeout[, path]]]);

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

read/write

boolean set to True if the 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 requirements database object.

displayID - get the display ID for a requirement

$id = $rdb->displayID( name, noPath, asText ) ;
    ($id, $noPathId) = $rdb->displayID( name, undef, asText ) ;

name is the name of a requirement.

noPath is an optional boolean flag that indicates whether to include the path in the ID. It defaults to false. In an array context, this flag is ignored since it returns both forms.

asText is an optional boolean flag that indicates whether the content should be emitted as test only, or if it is intended for markup use. It defaults to false (markup use).

Returns the displayID, including the outline number if appropriate. In an array context, returns (id, noPathId).

displayIDByUUID - get the display ID for a requirement by UUID

$id = $rdb->displayIDByUUID( uuid, noPath, asText ) ;

noPath is an optional boolean flag that indicates whether to include the path in the ID. It defaults to false.

asText is an optional boolean flag that indicates whether the content should be emitted as test only, or if it is intended for markup use. It defaults to false (markup use).

Returns the displayID, including the outline number if appropriate.

field - get a reference to a test case field

$fref = $rdb->field( fname ) ;

fname is the name of a requirements field.

Returns a reference to the field definition, or undef if the field does not exist. This is a convenience function - short cut to rfields->field.

filesPath - return a path to the REQUIREMENTS tree

$path = $rdb->filesPath( [ $directory ] ) ;

directory is an optional folder within the requirements tree.

Returns the full filesystem path to directory within the tree.

fileSuffix - return the suffix for requirements files.

$suffix = $rdb->fileSuffix() ;

Returns '.req".

idField - return a reference to the field of type ID

$ref = $rdb->idField() ;

Returns a reference to a field object of type ID.

initialize - reset the database file.

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

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

makeName - create a requirement/folder name in a folder

$newName = $rdb->makeName($folder, $pattern, $asFolder);

folder is a folder in which the requirement will be created. Note that this string should contain the '.dir' suffixes, and should be relative to the suite. As with all directory names, it should NOT end in a slash.

pattern is a string on which the name will be based.

asFolder is a flag that indicates whether to create the name as a folder instead of a test case.

Returns a new name that is unique in the folder, and is based upon pattern. If there was an error, returns undef.

numReqs - accessor for the number of stored requirements

$rdb->numReqs();

returns the number of requirements in the database.

outlinePrefix - get/set the outline number prefix

$pfx = $rdb->outlinePrefix( [ prefix ] ) ;

If prefix is supplied, sets the outlinePrefix for this test suite to that value.

Returns the previous prefix value .

path - get/set the path to the cache file

returns a path to the cache file.

print - print the contents of the database

$rdb->print();
    $rdb->print(UUID);

returns the string-ified version of the entire database, or just the contents of the requirement UUID.

deleted - check if a file is already in $deletedDir

$res = $rdb->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 = $rdb->recycled(name) ;

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

release - release the database

$rdb->release() ;

save - save the database

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

reqList - return the list of defined requirements

@list = $rdb->reqList( [includeRecycled [, includeDeleted ] ] ) ;

includeRecycled is a boolean. If true, items in the recycle bin are included as well. Defaults to false.

returns a list of defined requirements

byName - accessor for requirement data by pathname

$rdb->byName();
    $rdb->byName(name);
    $rdb->byName(name, ref);

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

With a name parameter, retrieves the data for a specific requirement.

With an name and a ref, sets the parameters for a requirement to ref.

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

byUUID - retrieve a requirement by UUID

$reqH = $reqDB->byUUID(uuid [, data] )

uuid is a uuid for a requirement.

data is an optional reference to updated data for the requirement. If provided, the requirement will be updated with the data.

Returns a handle to the requirements data in the database, or undef if the requirement does not exist.

getNameByUUID - get a requirement name by UUID

Returns the current pathname for a requirement that matches the UUID. Returns undef if there is no such requirement. If called with no UUID parameter, returns a reference to the entire hash table.

getUUIDByName - return the UUID associated with a name

Returns the UUID associated with a requirement named name. If no such requirement is in the database, returns undef.

testsByUUID - accessor to find tests that address requirement UUID

hashRef = $rdb->testsByUUID( uuid [, ref] ) ;

uuid is a uuid of a requirement.

ref is an optional reference to a list of tests.

Returns a reference to a hash of test uuids that purport to address requirement UUID.

delete - delete a req from the database

$rdb->delete($name);

deletes a requirement if it is defined. Removes it from the UUID hash and from the testHash.

suiteDB - Accessor for a suiteDB handle.

$suiteDb = $rdb->suiteDB();

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

unnumbered - return a list of requirements whose IDs are not numeric

@list = $reqDB->unnumbered() ;

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, or 1 when it succeeds.

Lock - override the lock method

$rdb->Lock() ;

Ensures the caches and this database are locked.

Unlock - override the unlock method

$tdb->Unlock() ;

Ensures the caches and this database are unlocked.

SQL_deleteRequirement - remove a requirement altogether

$rdb->SQL_deleteRequirement(UUID) ;

Returns nothing.

SQL_tableDef - return a list of table column definitions

@cols = $testDB->SQL_tableDef( tname ) ;

tname is the name of a SQL table

Returns a list item per column, formatted for use in a CREATE statement.

SQL_tableFields - return the fields that make up a table

@tfields = $rdb->SQL_tableFields( tableName ) ;

tableName is the name of the SQL field. We can derive the ATM field from this easily.

Returns a list of column names for the table.

SQL_tlist - return a list of all tables user by this object

my @tlist = $rdb->SQL_tlist();

Returns a list of all tables this object will operate upon.

SQL_tname - return the table name

my $5name = $rdb->SQL_tname;

Returns the name of the table for this object.

SQL_updateRequirement - update requirement data in a SQL store

$rdb->SQL_updateRequirement(UUID, hash) ;

UUID is the ID of the requirement to update.

hash is the data to populate the record with.

Returns nothing.

SQL_insertMulti - put entries for a multi-select list in the table

SQL_insertMulti(tdata, fname [, tname, trow, values] ) ;

tdata is a reference to the test case data hash.

fname is the name of the field to populate.

tname is an optional ATM table name that this field is within.

trow is an optional table row number for this field in an optional ATM table.

values are the values set in that row of the table for this field.

Returns nothing.

SQL_insertTabledata - put entries for an ATM table in the SQL table

SQL_insertTabledata(tdata, tableName )

tdata is a reference to the test case data hash.

tableName is the name of the table to populate.

Returns nothing.

SQL_createIndices - create the indices

$rdb->SQL_createIndices( );

Creates all of the requirements indices.

Returns nothing.

SQL_createTable - create the table(s)

$rdb->SQL_createTable( );

The primary table associated with requirements in a test suite will only have a single record per test case. This will contain all fields that are NOT multi-select lists and NOT in a table. Each table referenced in an ATM test suite will have its own SQL table. Each multi-select list will also have its own SQL table.

Returns nothing.

SQL_type - determine the best SQL type for an ATM type

$sqltype = $rdb->SQL_type(fref)

fref is a reference to a req fields field 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.

SQL_value - determine the best SQL value

$val = $rdb->SQL_value(fref, value) ;

fref is a reference to a SchemaField object.

value is the value to use.

Returns a suitable quoted value.

Copyright © 2000-2013 Applied Testing and Technology, Inc. All rights reserved.