NAME

ReportDB - report settings database class

AUTHOR

Shane P. McCarron <shane@aptest.com>

COPYRIGHT

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

SYNOPSIS

use ReportDB;

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

    # create a new report bucket
    my $report = $rdb->newReport() ;
    $report->CREATOR($userInfo->username()) ;
    $report->update($settings) ;
    $report->save() ;

    # get the settings for a report
    my $report = $rdb->settings($UUID)

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

    # destroy the settings for a report
    $rdb->delete($UUID) ;

    # release the database
    $rdb->release();

The ReportDB 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.

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

METHODS

new - open the reportDB

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

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

suite

the name of the test suite

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.

byTemplate - return a list of reports associated with a template

@list = $rdb->byTemplate(template, name, includePublic) ;

template is a template name

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

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

returns a list of saved reports sorted alphabetically by name.

newReport - set up a bucket for a new report.

Returns a reference to the new report object.

numReports - return the number of reports

$count = $rdb->numReports() ;

Returns the number of reports in the file.

release - release the database

$rdb->release() ;

reportInfo - get a handle on a report object

$report = $rdb->reportInfo($reportID) ;

reportID is the UUID of a report.

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

path - get/set the path to the cache file

returns a path to the cache file.

print - print the contents of the ReportDB

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

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.

reports - return the list of defined reports

@rlist = $rdb->reports(user, includePublic) ;

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

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

Returns a list of defined reports

delete - delete a report from the database

$rdb->delete($report);

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

ReportDB::Report

NAME

ReportDB::Report - information datastructure for individual report settings

DESCRIPTION

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

SYNOPSIS

DATA STRUCTURE

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:

_PARENT

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

data

contains settings related to the report.

METHODS

new - create a new ReportDB::Report object

$report = new ReportDB::Report( argsRef ) ;

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

Returns the parent.

save - save this agent's data

$status = $report->save();

Returns 1 on success, and 0 on failure.

sessionList - determine the list of sessions for a report

my @sessList = $report->sessionList( [filterRef] ) ;

Returns a list of sessions that match a report's filters or, optionally, a set of passed in filters. If a report has no defined filters, returns an empty list.

settings - retrieve all the settings

$setH = $report->settings() ;

Returns a hash ref to a settings structure.

update - update with new settings

$report->update(argsRef) ;

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

DESTROY() - tidy up

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