database
Class Database

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

Direct Known Subclasses:

HashDB

public abstract class Database

extends Object

implements Resolver

This abstract class provieds high level access to local PKI databases. Classes that implements this interface is free to add whatever extra implementation-dependent methods they want, as well as overload methods as they please.

Concrete implementations of this abstract class will have to register themselves using the class-method registerDatabase(). This allows from the very flexible approach of using database.getInstance() to get whatever database implementation one wants.

The similarity to java.util.Hashtable isn't as coincidental as I'd like. To accomendate (possibly) safer multi-threading, quite a number of methods here have been declared synchronized.

TODO: Define a minimal SQL table? I.e. mandatory rows?

TODO: Add support for iterating over keys (key scan)

Version:

$Id: Database.java,v 1.1.1.2 2002/05/08 22:48:28 tep Exp $

Author:

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

Field Summary

private static Hashtable

_registeredDB_ht

Constructor Summary

Database()

Method Summary

(package private) static void	()
abstract void	close() Close database, after commiting changes.
abstract void	closeNoCommit() Close database, without commiting changes.
abstract void	commit() Explicitly commit changes to stable storage.
abstract Enumeration	enumerate() Returns an enumeration of the keys/values in the database, at the time this method was called.
abstract boolean	exists(Object key) Test to see if an object exists in database.
abstract Result	get(Object key) Retrieve a stored object by key.
abstract Connection	getConnection() If possible, return the java.sql.Connection object representing this database connection.
static Database	getInstance(String db) Request an instance of the named Database class.
abstract Properties	getProperties() Return Database's properties.
abstract boolean	isJDBC() Test to see if the implementing class is JDBC-compliant.
abstract void	open(Object ref) Open database by some reference.
abstract void	put(Object key, Object value) Store object in database.
static void	registerDatabase(Database db) Register a concrete Database class.
abstract void	remove(Object key) Removes an object from the database
abstract Object	search(Object criterium) Search database for data matching a criterium.
abstract void	setProperties(Properties prop) Set Database's properties.
protected void	unRegister() Remove a registered Database class.

Methods inherited from class java.lang.Object

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

Field Detail

_registeredDB_ht

private static final Hashtable _registeredDB_ht

Constructor Detail

Database

public Database()

Method Detail

static void ()

registerDatabase

public static final void registerDatabase(Database db)

Register a concrete Database class. A concrete Database class should call this method to make itself known to the world. The registering class must provide a default constructor with no arguments.

Parameters:

db - concrete Database class to register.

getInstance

public static final Database getInstance(String db)
                                  throws DatabaseException,
                                         InstantiationException,
                                         IllegalAccessException

Request an instance of the named Database class.

Parameters:

db - name of registered Database class to instantiate.

Throws:

DatabaseException - if there were no such registered Database class to be found - probably due to an incomplete class name.

InstantiationException - if there were some errors during instantiation.

IllegalAccessException - if the class or initializer is not accessible.

unRegister

protected final void unRegister()

Remove a registered Database class. Should be called by Database classes that wish to dissappear from the known universe. A fine gun to shoot yourself in the foot with. It is probably a very bad idea to call this method from a finalizer.

getProperties

public abstract Properties getProperties()
                                  throws DatabaseException

Return Database's properties.

Returns:

this database's properties.

Throws:

DatabaseException - if some database-related error occured.

setProperties

public abstract void setProperties(Properties prop)
                            throws DatabaseException

Set Database's properties.

Parameters:

prop - this database's properties.

Returns:

this database's properties

Throws:

DatabaseException - if some database-related error occured.

isJDBC

public abstract boolean isJDBC()

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

Returns:

true if implementing class is JDBC-compliant.

See Also:

getConnection

put

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

Store object in 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 abstract Result get(Object key)
                    throws DatabaseException,
                           NotFoundException

Retrieve a stored object by key.

Specified by:

get in interface Resolver

Parameters:

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

Returns:

the Object associated with the key.

Throws:

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

DatabaseException - if some database-related error occured.

exists

public abstract boolean exists(Object key)
                        throws DatabaseException

Test to see if an object exists in 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 abstract void remove(Object key)
                     throws DatabaseException

Removes an object from the database

Parameters:

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

Throws:

DatabaseException - if some database-related error occured.

open

public abstract void open(Object ref)
                   throws DatabaseException

Open database by some reference.

Parameters:

ref - some Object referring to the database stable storage.

Throws:

DatabaseException - if some database-related error occured.

close

public abstract void close()
                    throws DatabaseException

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

Throws:

DatabaseException - if some database-related error occured.

closeNoCommit

public abstract void closeNoCommit()
                            throws DatabaseException

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

Throws:

DatabaseException - if some database-related error occured.

commit

public abstract void commit()
                     throws DatabaseException

Explicitly commit changes to stable storage.

Throws:

DatabaseException - if some database-related error occured.

enumerate

public abstract 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 object are implementation specific, but it is recommended that they are Object arrays containing key/data elements.

Returns:

Enumeration of all keys in the database.

search

public abstract 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.

It is probably a good idea for implementing classes to provide one or more overloaded versions of this method.

Parameters:

criterium - object to search for.

Returns:

object matching criterium.

Throws:

NotFoundException - if no objects matched criterium.

DatabaseException - if some database-related error occured.

getConnection

public abstract Connection getConnection()

If possible, return the java.sql.Connection object representing this database connection. If this.isJDBC() returns true, then the implementing class may, if it want to, give access to the underlying database through a java.sql.Connection reference. This allows one to get total control over the database, for the purpose of greater flexibility. It also makes a nice gun for shooting yourself in the foot. Be warned.

Returns:

java.sql.Connection of this database, or null, if the implementing class doesn't want to.