Class FSDB::Database
In: lib/fsdb/database.rb
lib/fsdb/util.rb
Parent: Object
Module: FSDB

A thread-safe, process-safe object database class which uses the native file system as its back end and allows multiple file formats.

Methods
abort    abort    absolute    browse    clear_cache    clear_entry    default_browse    default_edit    default_fetch    delete    dump    edit    fetch    find_format    formats    formats=    get_file_id    identify_file_type    insert    inspect    link    load    make_file_id    new    object_missing    replace    subdb    symlink   
Attributes
:dir  [R] 

The root directory of the db, to which paths are relative.

Classes and Modules
Class FSDB::Database::AbortedTransaction
Class FSDB::Database::CreateFileError
Class FSDB::Database::MissingFileError
Class FSDB::Database::MissingObjectError
Included modules
Formats PathUtilities DirectoryIterators
Public Class methods
new(dir)

Create a new database object that accesses dir. Makes sure that the directory exists on disk, but doesn't create or open any other files.

abort()
Public Instance methods
subdb(path)

Create a new database object that accesses path relative to the database directory. A process can have any number of dbs accessing overlapping dirs. The cost of creating an additional db is very low; its state is just the dir. Caching is done in structures owned by the Database class itself.

inspect()
absolute(path)

Convert a relative path (relative to the db dir) to an absolute path.

get_file_id(abs_path)

Convert an absolute path to a unique key for the cache, raising MissingFileError if the file does not exist.

make_file_id(abs_path)

Convert an absolute path to a unique key for the cache, creating the file if it does not exist. Raises CreateFileError if it can't be created.

clear_entry(file_id)

For housekeeping, so that stale entries don't result in unused, but uncollectable, CacheEntry objects.

clear_cache()

Can be called occasionally to reduce memory footprint, esp. if cached objects are large and infrequently used.

abort()

Abort the current transaction (browse, edit, replace, or delete, roll back the state of the object, and return nil from the transaction.

In the browse case, the only effect is to end the transaction.

Note that any exception that breaks out of the transaction will also abort the transaction, and be re-raised.

default_browse(path) {|x};| ...}

Called when browse doesn't find anything at the path. The original caller's block is available to be yielded to.

default_edit(path) {|x};| ...}

Called when edit doesn't find anything at the path. The original caller's block is available to be yielded to.

object_missing(path)

The default behavior of both default_edit and default_browse. Raises MissingObjectError by default, but it can yield to the original block.

default_fetch(path)

Called when fetch doesn't find anything at the path. Default definition just returns nil.

browse(path = "/") {|object| ...}

Browse the object. Yields the object to the caller's block, and returns the value of the block. Changes to the object are not persistent, but should be avoided (they will be seen by other threads, but only in the current process, and only until the cache is cleared).

edit(path = "/") {|object| ...}

Edit the object in place. Changes to the yielded object made within the caller's block become persistent. Returns the value of the block. Note that assigning to the block argument variable does not change the state of the object. Use destructive methods on the object.

replace(path) {|old_object| ...}

Replace the yielded object (or nil) with the return value of the block. Returns the object that was replaced. Use replace instead of edit when accessing db over a drb connection. Use replace instead of insert if the path needs to be protected while the object is prepared for insertion. Note that (unlike edit) destructive methods on the object do not persistently change the state of the object, unless the object is the return value of the block.

insert(path, object)

Insert the object, replacing anything at the path. Returns the object. (The object remains a local copy, distinct from the one which will be given out when accessing the path through database transactions.)

delete(path) {|object| ...}

Delete the object from the db. If a block is given, yields the object (or nil if none) before deleting it from the db (but before releasing the lock on the path), and returns the value of the block. Otherwise, just returns the object (or nil).

fetch(path = "/")

Fetch a copy of the object at the path for private use by the current thread/process. (The copy is a deep copy.)

load(f)

Returns object read from f (must be open for reading).

dump(object, f)

Writes object to f (must be open for writing).

formats()
formats=(fmts)
identify_file_type(f, path)
find_format(path)
link(old_name, new_name)

Create a hard link, using File.link. The names are relative to the database's path.

symlink(old_name, new_name)

Create a symbolic link, using File.symlink. The names are relative to the database's path.