database
Class HashDB

java.lang.Object
  |
  +--database.Database
        |
        +--database.HashDB

public class HashDB

extends Database

Concrete Database implementation that uses hashtables at the bottom. This concrete Database implementation is horribly slow on writes, uses incredible amounts of memory if the dataset is large, but has very fast lookups. All in all it is the archtypical bad speed/size tradeoff. Use this on very small datasets, or if there are no JDBC based implementations available.

This class will only handle datums with unique keys.

The database equalivent of bubble-sort (or perhaps bogo-sort?).

As of version 0.2, the data contents of the database is stored as S-Expression lists. The file itself is a list:

(key-value-database <version-string> <entry>*)

Where <version-string< is the storage format (currently "v0.2"), and is defined as

<byte-string>

Where <entry< is defined as

(<key><value>)

Where both <key< and <value> are byte-strings.

TODO: After this.close(), using get/put/etc should be an error.

Version:

$Id: HashDB.java,v 1.3 2002/07/07 17:03:52 tep Exp $

Author:

Per Harald Myrvang <perm@pasta.cs.uit.no>

Field Summary

private static String	__me
private boolean	db_dirty
private File	db_file
private Hashtable	db_ht
private Properties	db_prop
boolean	debug
protected static String	listname_s
private SList	slist
protected static String	version_s

Fields inherited from class database.Database

_registeredDB_ht

Constructor Summary

HashDB()

Method Summary

(package private) static void	()
private void	assertOpen(String method) Check to see if the database is open, and throw an exception if it isn't.
void	close() Close database, after commiting changes.
void	closeNoCommit() Close database, without commiting changes.
void	commit() Explicitly commit changes to stable storage.
Enumeration	enumerate() Returns an enumeration of the keys/values in the database, at the time this method was called.
boolean	exists(Object key) Test to see if an object exists in database.
Result	get(Object key) Retrieve a stored object by key.
Connection	getConnection() If possible, return the java.sql.Connection object representing this database connection.
Properties	getProperties() Return Database's properties.
boolean	isJDBC() Test to see if the implementing class is JDBC-compliant.
void	open(Object ref) Open database by file name.
void	put(Object key, Object value) Store object in database.
void	remove(Object key) Removes an object from the database
Object	search(Object criterium) Search database for data matching a criterium.
Enumeration	search(gnu.regexp.RE regexp) Overloaded method that takes a regular expression as search criterium.
void	setProperties(Properties prop) Set Database's properties.
int	size() Returns the number of entries in the database.
Object[]	toArray() Returns an array of the values in the database.

Methods inherited from class database.Database

getInstance, registerDatabase, unRegister

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait

Field Detail

__me

private static String __me

listname_s

protected static String listname_s

version_s

protected static String version_s

debug

public boolean debug

db_ht

private Hashtable db_ht

db_prop

private Properties db_prop

db_dirty

private boolean db_dirty

db_file

private File db_file

slist

private SList slist

Constructor Detail

HashDB

public HashDB()

Method Detail

static void ()

getProperties

public Properties getProperties()
                         throws DatabaseException

Return Database's properties.

Overrides:

getProperties in class Database

Returns:

this database's properties.

Throws:

DatabaseException - if some database-related error occured.

setProperties

public void setProperties(Properties prop)
                   throws DatabaseException

Set Database's properties.

Overrides:

setProperties in class Database

Parameters:

prop - this database's properties.

Returns:

this database's properties

Throws:

DatabaseException - if some database-related error occured.

isJDBC

public boolean isJDBC()

Test to see if the implementing class is JDBC-compliant.

Overrides:

isJDBC in class Database

Returns:

true if implementing class is JDBC-compliant.

put

public void put(Object key,
                Object value)
         throws DatabaseException

Store object in database. Will overwrite an existing object with the same key.

Overrides:

put in class Database

Parameters:

key - the Object used to reference the stored object by.

value - the Object to store.

Throws:

DatabaseException - if some database-related error occured.

get

public Result get(Object key)
           throws DatabaseException,
                  NotFoundException

Retrieve a stored object by key.

Overrides:

get in class Database

Parameters:

key - the Object used to reference the stored object by.

Returns:

the Object associated with the key, or null if none were found.

Throws:

DatabaseException - if some database-related error occured.

NotFoundException - if there were no objects associated by key. Use the exists() method to elude this exception.

exists

public boolean exists(Object key)
               throws DatabaseException

Test to see if an object exists in database.

Overrides:

exists in class Database

Parameters:

key - the Object used to reference the stored object by.

Returns:

true if there's a object associated with thekey

Throws:

DatabaseException - if some database-related error occured.

remove

public void remove(Object key)
            throws DatabaseException

Removes an object from the database

Overrides:

remove in class Database

Parameters:

key - the Object used to reference the stored object by.

Throws:

DatabaseException - if some database-related error occured.

open

public void open(Object ref)
          throws DatabaseException

Open database by file name. If the file doesn't exists, it is created.

TODO: Read/Write this.db_prop too?

Overrides:

open in class Database

Parameters:

ref - String containing file name of database.

Throws:

DatabaseException - if ref isn't a valid HashDB, or if some other database-related error occured.

close

public void close()
           throws DatabaseException

Close database, after commiting changes. This will in practice call database.commit().

Overrides:

close in class Database

Throws:

DatabaseException - if some database-related error occured.

closeNoCommit

public void closeNoCommit()
                   throws DatabaseException

Close database, without commiting changes. XXX is such a method useful?

Overrides:

closeNoCommit in class Database

Throws:

DatabaseException - if some database-related error occured.

commit

public void commit()
            throws DatabaseException

Explicitly commit changes to stable storage.

TODO: Robustness: It should write to a temporal file first, then rename to the "real" file.

Overrides:

commit in class Database

Throws:

DatabaseException - if some database-related error occured.

enumerate

public Enumeration enumerate()

Returns an enumeration of the keys/values in the database, at the time this method was called. The objects returned by the returned Enumeration will be Object[] containing two byte-array references (key/data). If something went wrong during the creation of the enumeration, the Enumeration's hasMoreElements() will always return false.

Overrides:

enumerate in class Database

Returns:

Enumeration of all keys/values in the database.

toArray

public Object[] toArray()

Returns an array of the values in the database.

Returns:

array of all values in the database.

size

public int size()

Returns the number of entries in the database.

Returns:

integer indicating the number of entries in the database.

search

public Object search(Object criterium)
              throws DatabaseException,
                     NotFoundException

Search database for data matching a criterium. The actual objects used are completly implementation-dependent. A flatfile database may accept a gnu.regexp.RE object, and return a Enumeration object. A JDBC database could take a string containing a SQL SELECT statement, and return a java.sql.ResultSet object.

Overrides:

search in class Database

Parameters:

criterium - object to search for.

Returns:

object matching criterium.

Throws:

NotFoundException - if no objects matched criterium.

DatabaseException - if some database-related error occured.

search

public Enumeration search(gnu.regexp.RE regexp)
                   throws DatabaseException,
                          NotFoundException

Overloaded method that takes a regular expression as search criterium.

Parameters:

criterium - gnu.regexp.RE regular expression object that a stored datum must match exactly.

Returns:

enumeration of matching objects (without keys!)

Throws:

NotFoundException - if no objects matched criterium.

DatabaseException - if some database-related error occured.

assertOpen

private void assertOpen(String method)
                 throws DatabaseException

Check to see if the database is open, and throw an exception if it isn't.

Parameters:

method - String containing name of calling method (for prettyprinting).

Throws:

DatabaseException - if some database-related error occured.

getConnection

public Connection getConnection()

If possible, return the java.sql.Connection object representing this database connection. This method has no meaning for HashDB class, and will always return null.

Overrides:

getConnection in class Database

Returns:

Alwaysi null for HashDB instances.