SearchDB - search settings database class


Shane P. McCarron <>


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


use SearchDB;

# Open the Database for writing
my $sdb = new SearchDB(suite, 1);

# create a new search bucket
my $search = $sdb->newSearch() ;
$search->name($userInfo->username()) ;
$search->update($settings) ;
$search->save() ;

# get the settings for a search
my $search = $sdb->settings($UUID)

# update the settings for a search
$search->update($settings) ;
$search->save() ;

# destroy the settings for a search
$sdb->delete($UUID) ;

# release the database

The SearchDB object is a generic multi-level data structure storage facility. The data stored in this facility is keyed by a UUID that is generated automatically if you call the settings method with no parameters.

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). This DOES NOT MEAN YOU SHOULD NOT CALL SAVE. In the future, if something is changed underneath, calling save() may be required. Always call save() and release() when you are done with an object.



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 searches keyed by UUID. Within each is whatever data is useful to the search subsystem.


new - open the searchDB

$sdb = new SearchDB(suite, [read/write [, timeout[, path]]]);

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


the name of the test suite


boolean set to True if the test database needs to be writeable or False if it can be readOnly.


the number of seconds to wait for a lock. Defaults to 60 seconds.


a path to an alternate database (the default is implementation defined).

returns a reference to the test database object.

byType - return a list of searches associated with a type

@list = $sdb->byType(type, name, includePublic) ;

type is a search type (e.g., test, requirement).

name is a username to check against. If defined, only searches associated with that user or public searches will be included.

includePublic is a boolean. If true, public searches will be included in the list.

returns a list of saved searches sorted alphabetically by name.

newSearch - set up a bucket for a new search.

Returns a reference to the new search object.

numSearches - return the number of searches

$count = $sdb->numSearches() ;

Returns the number of Searches in the file.

release - release the database

$rdb->release() ;

searchByName - get a handle on a search by its name

$search = $sdb->searchByName(name [, type]) ;

name is a name associated with a search.

type is an optional search type: test or requirement

Returns a reference to a search object, or undef if no such search exists.

searchInfo - get a handle on a search object

$search = $sdb->searchInfo($searchID) ;

searchID is the UUID of a saved search.

Returns a reference to a search object, or undef if no such search exists.

path - get/set the path to the cache file

returns a path to the cache file.

print - print the contents of the SearchDB


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

saveAsText - save the database as a serialized object

$status = $rdb->saveAsText();

Returns the output of the database's save method, but forcing the database to write out into a text file instead of a DBM file.

save - save the database

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

searches - return the list of defined searches

@slist = $sdb->searches(user, includePublic) ;

user is an optional username to filter on. If provided, only searches that are owned by that user (or are public, see includePublic below) are listed. If this parameter is not defined, then all search definitions are returned.

includePublic is a boolean that indicate whether public searches should be included in the list. The default value is true.

Returns a list of defined searches

delete - delete a search from the database


deletes a search if it is defined. Returns 1 on success, and 0 if the search did not exist. Returns undef if the database is not writeable.



SearchDB::Search - information datastructure for individual saved search settings


An SearchDB::Search object contains accessors and control functions for search setting information. These objects are always created by the setting method of the SearchDB class. When updating through this object, you must use the save method to ensure that the actual Search information is updated at the end of the transaction. This will call the Search::setting method to update the content, and will also call the Search->save method to ensure it is written to disk.



Each info item has within it some control attributes and a data attribute. The data attribute contains a copy of the data from the associated database, and is committed to that database on a call to the save method.

Data items include:


Reference to the parent SearchDB object (used by the save method).


contains settings related to the report.


new - create a new SearchDB::Search object

$search = new SearchDB::Search( argsRef ) ;

Creates a search object, optionally setting parameters to those defined by the collection in argsRef, a reference to a hash.

parent - get/set the parent object reference for this object

$parent = $search->parent( [ parentRef ] ) ;

Returns the parent.

save - save this search's data

$status = $search->save();

Returns 1 on success, and 0 on failure.

settings - retrieve all the settings

$setH = $search->settings() ;

Returns a hash ref to a settings structure.

update - update with new settings

$search->update(argsRef) ;

argsRef is a reference to search parameters that should be updated.

DESTROY() - tidy up

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