com.coyotegulch.jisp

Class 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

Constructor Summary
IndexedObjectDatabase(String filename, boolean is_new)
Opens an existing IndexedObjectDatabase, using a supplied file name.
Method Summary
voidattachIndex(ObjectIndex index)
Attaches an index object to this database.
voidinsert(KeyObject[] key, Serializable obj)
Write a new object to the database, associating it with the provided keys.
Objectread(KeyObject key, ObjectIndex index)
Read the object associated with a given key.
Objectread(IndexIterator iterator)
Read the object associated with a given iterator.
voidremove(KeyObject[] key)
Delete the record associated with a given key.
voidremoveIndex(ObjectIndex index)
Removes the association of an index with this database.
voidwrite(KeyObject[] key, Serializable obj)
Writes an object to the database, associating it with the provided key, replacing an existing object with a new one.

Constructor Detail

IndexedObjectDatabase

public IndexedObjectDatabase(String filename, boolean is_new)
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: 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

insert

public void insert(KeyObject[] key, Serializable obj)
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: IOException when an I/O exception is thrown by an underlying java.io.* class 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 Object read(KeyObject key, ObjectIndex index)
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: IOException when an I/O exception is thrown by an underlying java.io.* class 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 Object read(IndexIterator iterator)
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: IOException when an I/O exception is thrown by an underlying java.io.* class 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)
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: IOException when an I/O exception is thrown by an underlying java.io.* class 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

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

write

public void write(KeyObject[] key, Serializable obj)
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: IOException when an I/O exception is thrown by an underlying java.io.* class 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