Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD