com.coyotegulch.jisp

Class ObjectDatabaseFile

public class ObjectDatabaseFile extends Object

The ObjectDatabaseFile provides a random-access file that serializes objects to variable length records in a random-access file. An ObjectDatabaseFile allows the deletion of records and automatically uses such space for new records.

For the purposes of an ObjectDatabaseFile, consider record and object to be synonyms. In traditional database terms, an ObjectDatabaseFile is a table, each object is a row, and each field in an object is a column. Unlike a full-featured database, an ObjectDatabaseFile can contain a set of heterogenous records -- in other words, different objects can be stored together in one ObjectDatabaseFile. This class is the foundation of the Jisp package, providing the fundamental file structures for both indexes and data files.

You can store any serializable object in an ObjectDatabaseFile. Records in an ObjectDatabaseFile can have varying lengths based on the serialization requirements of objects. To handle variable-length records, a ObjectDatabaseFile records the size of each record. When a record is deleted, the space it occupied is marked as empty; the files maintains a linked list of deleted record locations and thier sizes.

Inserting a new record involves a traverse of the deleted list, looking for an empty record that is large enough to contain the new information. If the deleted list is empty, or the new record is too large to fit into any open slots, the new object record is appended to the file.

Reusing deleted record space has a drawback: it leaves dead space in the file when a newly-inserted record is smaller than the "deleted" space it overwrites. Deleted records also use space in the file until a new record is written into their location. Periodically, it makes sense to compact the file, removing the wasted space and eliminating deleted records. ObjectDatabaseFile recovers "waste space" by re-writing the file, record by record, using exact record lengths, ignoring deleted records, and calling a user-provided method so that indexes can be simultaneously regenerated.

See Also: IndexedObjectDatabase PageDatabaseFile

Field Summary
protected static longDEL_LIST_END
Marks the end of the list of deleted records
protected static byteIS_ACTIVE
Marks a given record as containing live data
protected static byteIS_DELETED
Marks a given record as deleted
protected RandomAccessFilem_dataFile
Physical file containing serialized objects
protected Stringm_fileName
Name of the underlying physical file
protected RecordFilterm_filter
Filter to be applied to each object read or written
protected longm_firstDeleted
File position of the first delete record
Constructor Summary
ObjectDatabaseFile(String name, boolean is_new)
Creates or opens a file that stores objects in variable-length records.
ObjectDatabaseFile(File file, boolean is_new)
Creates or opens a file that stores objects in variable-length records.
Method Summary
voidassignFilter(RecordFilter filter)
Assigns a filter object to translated, encrypt, compress, or otherwise manipulate objects as they are written and read.
voidclose()
voidcompact(ObjectDatabaseCallback callback)
Compacts a database file by copying it to a new file and deleting the old one.
protected ObjectInputStreamcreateObjectInputStream(InputStream in)
protected ObjectOutputStreamcreateObjectOutputStream(OutputStream out)
voiddelete()
Deletes the record in the current file position.
FileDescriptorgetFD()
longgetFilePointer()
longlength()
ObjectreadObject()
voidrewind()
Sets the current file pointer to the first byte beyond the file header.
voidrewriteObject(Serializable obj)
Re-writes a serializable object to the file, at the current file position.
voidseek(long pos)
voidskip()
Skips the record at the current file position, moving to the next record in sequence.
longwriteObject(Serializable obj)
Writes a serializable object to the file.

Field Detail

DEL_LIST_END

protected static final long DEL_LIST_END
Marks the end of the list of deleted records

IS_ACTIVE

protected static final byte IS_ACTIVE
Marks a given record as containing live data

IS_DELETED

protected static final byte IS_DELETED
Marks a given record as deleted

m_dataFile

protected RandomAccessFile m_dataFile
Physical file containing serialized objects

m_fileName

protected String m_fileName
Name of the underlying physical file

m_filter

protected RecordFilter m_filter
Filter to be applied to each object read or written

m_firstDeleted

protected long m_firstDeleted
File position of the first delete record

Constructor Detail

ObjectDatabaseFile

public ObjectDatabaseFile(String name, boolean is_new)
Creates or opens a file that stores objects in variable-length records.

Parameters: name name of the file to be created is_new true when a new file should be created, overwriting any existing file with the same name; false when opening and using an existing file

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

ObjectDatabaseFile

public ObjectDatabaseFile(File file, boolean is_new)
Creates or opens a file that stores objects in variable-length records.

Parameters: file indentity of the file to be created is_new true when a new file should be created, overwriting any existing file with the same identity; false when opening and using an existing file

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

Method Detail

assignFilter

public void assignFilter(RecordFilter filter)
Assigns a filter object to translated, encrypt, compress, or otherwise manipulate objects as they are written and read.

Parameters: filter assigned filter

close

public void close()

compact

public void compact(ObjectDatabaseCallback callback)
Compacts a database file by copying it to a new file and deleting the old one. The records will be copied in sequence, and the callback function is called for each record as it is rewritten. The callback function is responsible for rebuilding any indexes or other referneces to the records, which will have new file positions after compaction.

Parameters: callback called for each record rewritten to the compacted file

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

createObjectInputStream

protected ObjectInputStream createObjectInputStream(InputStream in)

createObjectOutputStream

protected ObjectOutputStream createObjectOutputStream(OutputStream out)

delete

public void delete()
Deletes the record in the current file position.

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

getFD

public final FileDescriptor getFD()

getFilePointer

public long getFilePointer()

length

public long length()

readObject

public Object readObject()

rewind

public void rewind()
Sets the current file pointer to the first byte beyond the file header.

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

rewriteObject

public void rewriteObject(Serializable obj)
Re-writes a serializable object to the file, at the current file position.

Parameters: obj serializable object to be written as a record

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

seek

public void seek(long pos)

skip

public void skip()
Skips the record at the current file position, moving to the next record in sequence.

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

writeObject

public long writeObject(Serializable obj)
Writes a serializable object to the file. writeObject stores the new record in the first "deleted" location of sufficient size, or it appends the new record if suitable deleted space is not available.

Parameters: obj serializable object to be written as a record

Returns: file position of the newly-written record

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