NAME

DataFile - master class for managing data files

AUTHOR

Shane P. McCarron <shane@aptest.com>

COPYRIGHT

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

SYNOPSIS

use DataFile;

    # create a new DataFile object
    my $file = new DataFile(path, readwrite, timeout);

    # update an object
    $status = $file->save();

    # release the object, unlocking it
    $status = $file->release();

The DataFile class is a template class that manages accessing files composed of arbitrary data. The files can be in either serialized object format or in DBM file format. The methods in this class are expected to be extended in sub-classes that manage the data in the "data" attribute, and also manage any specialized attributes outside of the "data" attribute.

The data structure of this object is optimized to be most efficient when used in conjunction with MLDBM and a single key hashed database. 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).

DATA STRUCTURE

lock

a handle to the locked "lockfile" that is set for the object.

writeable

a boolean that indicates whether the datafile is open read/write

usingDBM

a boolean to indicate if the file is from a DBM source

DBMhandle

a handle to the active, TIEd DBM file. This can be used by sub-classes to flush out the file, for example. NOTE: classes that use this class as a basis should either either use this handle directly to ensure that the data is flushed at obvious points in their implementation, or should call the save() method to ensure that it gets flushed.

data->

The contents of the data attribute are up to the user, but it must be a pointer to a hash, and the keys of that hash should be sensibly structured.

METHODS

new - Create a new, unpopulated datafile

$file = new DataFile(path, readWrite, timeout);

Creates a new DataFile object:

path

the name of the file to access.

readWrite

boolean set to True if the existing session needs to be writeable. Defaults to readOnly.

timeout

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

returns a reference to the DataFile object.

release - release the tied hash

$file->release();

This method undefines the data structures associated with the session and releases the lock on the session.

flush - flush the data base cache to disk

Returns nothing.

initialize - reset the database file.

 $dataFile->initialize() ;

Removes all entries from the database. Asserts a lock locally, but you should ensure that you have a lock before you call this, since you are likely doing more than just clearing the database.

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

isLocked - check to see if we are Locked

Returns 1 if we are actively Locked, 0 if not. Only meaningful under MLDBM::Sync.

Lock - explicitly lock when using MLDBM::Sync

Lock uses the class' writeable flag to determine whether a read or a write lock is needed.

Note that this method attempts to use a pessimistic locking strategy - write locks set a write pending flag before trying to get the lock. Read locks look for such a flag and pause if it is there so that other reads have a change to finish and writes can get in.

Returns 1 on success, 0 on failure.

Relock - release and reacquire a lock if needed.

$ref->Relock() ;

Returns nothing.

Unlock - explicitly unlock when using MLDBM::Sync

Returns 1 on success, 0 on failure.

writeable - check if the database is updateable

$state = $self->writeable() ;

Returns true if the database can be written to, and false if it cannot.

path - get/set the path to the object

Returns the path to the object.

save - write out the object $file->save();

returns undef if the save failed. Returns the path saved into if the save succeeded.

cache - establish memory cache for items

$file->cache(size) ;

size is the number of bytes to set aside as a cache.

Sets up a database cache for items so that they are automatically kept resident to speed access on subsequent calls.

Returns nothing.

dirtyFlag - accessor for the flag indicating if data has changed..

$file->dirtyFlag();
    $file->dirtyFlag( 1 | 0 );

Calling this method with no arguments will return whether or not any data has changed since the ojbect was originally created.

When ever you DO change part of the object (most notably "data") you should call this method with the true value.

useSync - accessor for useSync flag

_flock - get a lock on a file

$lock = _flock($path, $readWrite, $timeout, $bailout, $suffix);

path is the path to lock.

readWrite is a boolean indicating whether the lock should be shared (a read lock), or exclusive (a write lock). Default is readOnly.

timeout is a timeout to try for the lock in seconds (default is 60).

bailout is a boolean - if true, then if timeout expires without the lock being set, the system bailOut method will be called, effectively aborting the operation. This boolean defaults to true.

suffix is an optional suffix to add to the lock name. The default is to use no suffix.

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