com.coyotegulch.jisp
Class IndexedObjectDatabase

java.lang.Object
  com.coyotegulch.jisp.ObjectDatabaseFile
      com.coyotegulch.jisp.IndexedObjectDatabase

public class IndexedObjectDatabase
extends ObjectDatabaseFile

The IndexedObjectDatabase class provides a mechanism for using a key value to an object serialized to a file.

A IndexedObjectDatabase object encapsulates access to a ObjectDatabaseFile via a set of ObjectIndexs. When an object is stored, it is associated with a key value by storing the key and an object reference in each attached ObjectIndex. Objects may then be retrieved either by providing a key and index pair, or through an iterator created for an index associated with the database.

Rationale: The Java Database Connection (JDBC) is often overkill for many applications. Sun designed JDBC to access enterprise-level database systems, such as DB2, SQL Server, and Oracle. Those systems, while very flexible and expansive, come with a high price tag, both in terms of system requirements and database overhead. BTreeDatabase provides a simpler tool for associating "key" information with data in external storage.

See Also:

BTreeIndex, DatabaseException, KeyObject, ObjectIndex

Field Summary

Fields inherited from class com.coyotegulch.jisp.ObjectDatabaseFile

DEL_LIST_END, IS_ACTIVE, IS_DELETED, m_dataFile, m_fileName, m_filter, m_firstDeleted

Constructor Summary

IndexedObjectDatabase(java.lang.String filename, boolean is_new)
Opens an existing IndexedObjectDatabase, using a supplied file name.

Method Summary

void	attachIndex(ObjectIndex index) Attaches an index object to this database.
void	insert(KeyObject[] key, java.io.Serializable obj) Write a new object to the database, associating it with the provided keys.
java.lang.Object	read(IndexIterator iterator) Read the object associated with a given iterator.
java.lang.Object	read(KeyObject key, ObjectIndex index) Read the object associated with a given key.
void	remove(KeyObject[] key) Delete the record associated with a given key.
void	removeIndex(ObjectIndex index) Removes the association of an index with this database.
void	write(KeyObject[] key, java.io.Serializable obj) Writes an object to the database, associating it with the provided key, replacing an existing object with a new one.

Methods inherited from class com.coyotegulch.jisp.ObjectDatabaseFile

assignFilter, close, compact, createObjectInputStream, createObjectOutputStream, delete, getFD, getFilePointer, length, readObject, rewind, rewriteObject, seek, skip, writeObject

Methods inherited from class java.lang.Object

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

Constructor Detail

IndexedObjectDatabase

public IndexedObjectDatabase(java.lang.String filename,
                             boolean is_new)
                      throws java.io.IOException

Opens an existing IndexedObjectDatabase, using a supplied file name.

Parameters:

filename - The name of an external database file containing serialized objects. If filename exists, it is opened; otherwise, the constructor creates the file and initializes it.

Throws:

java.io.IOException - when an I/O exception is thrown by an underlying java.io.* class

Method Detail

attachIndex

public void attachIndex(ObjectIndex index)

Attaches an index object to this database. This index will be updated for every object recorded in the database.

Parameters:

index - An ObjectIndex to be associated with this database.

See Also:

ObjectIndex

removeIndex

public void removeIndex(ObjectIndex index)

Removes the association of an index with this database. The index will no longer be updated for objects recorded in the database.

Parameters:

index - An ObjectIndex that should no longer be associated with this database.

See Also:

ObjectIndex

insert

public void insert(KeyObject[] key,
                   java.io.Serializable obj)
            throws java.io.IOException,
                   java.lang.ClassNotFoundException

Write a new object to the database, associating it with the provided keys.

Parameters:

key - The key values associated with obj. There must be one key for each attached index; the keys are associated with the indexes in order of attachment; in other words, the first key is associated with the first index attached, etc.

obj - The object to be stored in the database.

Throws:

java.io.IOException - when an I/O exception is thrown by an underlying java.io.* class

java.lang.ClassNotFoundException - for a casting error, usually when a persistent object or index does match the expected type

DatabaseException - when an error occurs during database processing

See Also:

DatabaseException, KeyObject

write

public void write(KeyObject[] key,
                  java.io.Serializable obj)
           throws java.io.IOException,
                  java.lang.ClassNotFoundException

Writes an object to the database, associating it with the provided key, replacing an existing object with a new one.

Parameters:

key - key values associated with obj. There must be one key for each attached index; the keys are associated with the indexes in order of attachment; in other words, the first key is associated with the first index attached, etc.

obj - record object to be stored in the database.

Throws:

java.io.IOException - when an I/O exception is thrown by an underlying java.io.* class

java.lang.ClassNotFoundException - for a casting error, usually when a persistent object or index does match the expected type

DatabaseException - when an error occurs during database processing

See Also:

DatabaseException, KeyObject

read

public java.lang.Object read(KeyObject key,
                             ObjectIndex index)
                      throws java.io.IOException,
                             java.lang.ClassNotFoundException

Read the object associated with a given key.

Parameters:

key - key identifying the record to be read

index - index used to retrieve the object by key.

Returns:

The record object associated with key, or null if no such object could be found.

Throws:

java.io.IOException - when an I/O exception is thrown by an underlying java.io.* class

java.lang.ClassNotFoundException - for a casting error, usually when a persistent object or index does match the expected type

DatabaseException - when an error occurs during database processing

See Also:

DatabaseException, KeyObject

read

public java.lang.Object read(IndexIterator iterator)
                      throws java.io.IOException,
                             java.lang.ClassNotFoundException

Read the object associated with a given iterator.

Parameters:

iterator - a BTreeIterator pointing to the requested record

Returns:

The record object associated with iterator, or null if the iterator was invalid or no such record could be found.

Throws:

java.io.IOException - when an I/O exception is thrown by an underlying java.io.* class

java.lang.ClassNotFoundException - for a casting error, usually when a persistent object or index does match the expected type

DatabaseException - when an error occurs during database processing

See Also:

DatabaseException, BTreeIterator, KeyObject

remove

public void remove(KeyObject[] key)
            throws java.io.IOException,
                   DatabaseException,
                   java.lang.ClassNotFoundException

Delete the record associated with a given key.

Parameters:

key - array of keys identifying the record to be deleted.

index - index used to retrive the object by key.

Throws:

java.io.IOException - when an I/O exception is thrown by an underlying java.io.* class

java.lang.ClassNotFoundException - for a casting error, usually when a persistent object or index does match the expected type

DatabaseException - when an error occurs during database processing

See Also:

DatabaseException, KeyObject