com.coyotegulch.jisp
Class IndexedObjectDatabase

java.lang.Object
  extended bycom.coyotegulch.jisp.ObjectDatabaseFile
      extended bycom.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.
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