Example Source for A Fancier Database Class

The class symbDB and related methods described here provide an implementation of S user-defined database classes, somewhat more sophisticated and user-friendly than the dumpDataBase class. That class simply wrote objects to files with the same name, which inherently restricts the names of the objects. In this implementation the database software maintains a separate file for the vector of current object names. This file produces a hash table (in the form of a string vector) used to maintain a parallel table of the contents of the database. The position of a name in the string vector is encoded as the file name. To make this work easily over removals of objects, empty strings are kept where objects are removed. The name for a first-time assignment replaces an empty string or goes on the end of the string vector. In directory databases, mostly from old tradition, S uses object names as file names when these are legal and otherwise constructs a table of maps to true file names. In fact the strategy used here would work fine for directory databases as well.

The symbDB class is a slightly more typical example than its simpler counterpart, in that the code must worry a little about the consistency of the explicit table in the string object and the database dictionary kept by the evaluator manager. Suppose an error takes place in writing a file, for example: what happens to the two tables? The implementation shown here does only a minimal amount of bullet-proofing against such problems.

Class Definition

Defines the class to extend the virtual class "database" and to contain one slot, for the string path name of the corresponding directory.
    setClass("symbDB",
        representation("database", path = "character"))

Generator Function for the Class

Takes as argument a character string for the directory's path and, optionally, a flag to say whether to create the directory if it does not exist.
"symbDB" =
  ## make an object of class `"symbDB"' corresponding to the directory
  ## `path'.  The flag `create' allows or suppresses creating the directory if it
  ## does not exist (by default, the user is asked, if S is in interactive mode).
  function(path,
           create = identical(dialog(paste("Directory \"", path,
             "\"for database does not exist; create?", sep=""), c("y", "n"), 2),1))
{
  path = as(path, "character")
  if(length(path)!=1) stop("needed a single character string for path")
  if(!isDirectory(path)) {
    if(create) {
      shell(paste("mkdir", path), mustWork=T)
      file = paste(path, "objects", sep="/")
      cat("", file=file, sep="")
    }
    else
      warning("Directory \"", path, "\"for database does not exist; path validity not checked")
  }
  if(isDirectory(path))
    ## get a fully-qualified path
    path = shell(paste("cd", path, "; pwd"))
  new("symbDB", path = path)
}

Method for dbobjects: Listing the Object Names

This method returns a character vector of the current object names in the directory. It is normally only called when the database is being attached. From then on, the S evaluation manager maintains its own table of the contents of the database. As with ordinary directory databases, this means that multiple processes using the same database simultaneously are not automatically co-ordinated.

For this particular database class, the sdbObjects utility function actually accesses the information about current database contents, and returns the appropriate character vector.

setMethod("dbobjects", "symbDB", 
function(database)
{
  ans = sdbObjects(database)
  ## may be empty strings corresponding to deleted objects
  sort(ans[nchar(ans) > 0])
}
)

Method for dbread: Read an Object

Given the database and the name of an object guaranteed to be in the datbase, this method reads it in. It uses the sdbNameToFile utility in this package to get the name of the file containing the object. Since all objects are written in the standard S symbolic dump format by dataPut, this method just calls dataGet to do the reading.
setMethod("dbread", "symbDB", 
function(database, name)
{
  path = sdbNameToFile(database, name)
  if(nchar(path)==0)
    stop("object \"", name, "\" not in database")
  dataGet(path)
}
)
The check on path is not needed in normal usage, but it is possible for dataGet to fail, for example if some other process is concurrently using the same directory and removes the object.

Method for dbwrite: Write an Object

This method takes the database, an object to write out, and the name the object should have when assigned in the database. The local utility sdbNameToFile is called to get the path for the corresponding file, and is told to create a new path if one does not exist. Once this is done, all that remains is to call the dataPut function to write the object in standard symbolic dump format to the corresponding file.
setMethod("dbwrite", "symbDB", 
function(database, name, object) {
  path = sdbNameToFile(database, name, T)
  dataPut(object, path)
}
)

Method for dbremove: Remove an Object

This method removes the name from the list of names in the database, and removes the corresponding file containing the object as dumped out. The name is erased from the character vector supplied by sdbObjects; an empty string is stored in its place, to allow the file name to be reused for a later assignment. The utility setSdbObjects stores the revised vector of names both in the session and externally in the directory. The file identified by sdbNameToFile is also removed. Notice that we have to get the file name before modifying the session's view of what objects exist in the database.
setMethod("dbremove", "symbDB",
          ## removes the name from the list of objects, saves the updated list of objects,
          ## and then removes the corresponding file from the directory.
function(database, name) {
  objects = sdbObjects(database)
  i = match(name, objects)
  if(is.na(i))
    stop("bad call to dbremove method: \"",
         name, "\" is not in this database")
  file = sdbNameToFile(database, name)
  if(i == length(objects))
    length(objects) = i-1
  else el(objects, i) = ""
  sdbSetObjects(database, objects)
  shell(paste("rm", file))
}
)

Some Utility Functions

These functions use and manipulate the internal session object that defines the contents of the database. This object has a constructed name equivalent to path and stored in the session database.
John Chambers<jmc@research.bell-labs.com>
Last modified: Fri Oct 2 16:53:34 EDT 1998