FilterDB - filter settings database class


Shane P. McCarron <>


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


use FilterDB;

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

    # create a new filter bucket
    my $filter = $fdb->newFilter() ;
    $filter->owner($userInfo->username()) ;
    $filter->update($settings) ;
    $filter->save() ;

    # get the settings for a filter
    my $filter = $fdb->settings($UUID)

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

    # destroy the settings for a filter
    $fdb->delete($UUID) ;

    # release the database

The FilterDB 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 filters keyed by UUID. Within each is whatever data is useful to the session filter subsystem.


new - open the filterDB

$fdb = new FilterDB(suite, [read/write [, timeout[, path]]]);

Creates a new filter 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.

list - return a list of session filters

@list = $fdb->list(name, includePublic) ;

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

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

returns a list of saved filters sorted alphabetically by name.

newFilter - set up a bucket for a new filter.

Returns a reference to the new filter object.

numFilters - return the number of filters

$count = $fdb->numFilters() ;

Returns the number of Filters in the file.

release - release the database

$rdb->release() ;

filterByName - get a handle on a filter by its name

$filter = $fdb->filterByName(name) ;

name is a name associated with a filter.

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

filterInfo - get a handle on a filter object

$filter = $fdb->filterInfo($filterID) ;

filterID is the UUID of a saved filter.

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

parseFilter - parse an arguments has for filter settings

my $ref = $fdb->parseFilter( $argsRef ) ;

argsRef is a reference to the arguments hash.

Returns a reference to a structure with each filter setting populated from the arguments hash.

path - get/set the path to the cache file

returns a path to the cache file.

print - print the contents of the FilterDB


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.

filters - return the list of defined filters

@flist = $fdb->filters(user, includePublic) ;

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

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

Returns a list of defined filters

delete - delete a filter from the database


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



FilterDB::Filter - information datastructure for individual saved filter settings


A FilterDB::Filter object contains accessors and control functions for filter setting information. These objects are always created by the setting method of the FilterDB class. When updating through this object, you must use the save method to ensure that the actual Filter information is updated at the end of the transaction. This will call the Filter::setting method to update the content, and will also call the Filter->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 FilterDB object (used by the save method).


contains settings related to the report.


new - create a new FilterDB::Filter object

$filter = new FilterDB::Filter( argsRef ) ;

Creates a filter 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 = $filter->parent( [ parentRef ] ) ;

Returns the parent.

save - save this filter's data

$status = $filter->save();

Returns 1 on success, and 0 on failure.

settings - retrieve all the settings

$setH = $filter->settings() ;

Returns a hash ref to a settings structure.

update - update with new settings

$filter->update(argsRef) ;

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

DESTROY() - tidy up

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