Class ObjectDatabaseFile

  • Direct Known Subclasses:
    IndexedObjectDatabase

    public class ObjectDatabaseFile
    extends java.lang.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

      Fields 
      Modifier and Type Field Description
      protected static long DEL_LIST_END
      Marks the end of the list of deleted records
      protected static byte IS_ACTIVE
      Marks a given record as containing live data
      protected static byte IS_DELETED
      Marks a given record as deleted
      protected java.io.RandomAccessFile m_dataFile
      Physical file containing serialized objects
      protected java.lang.String m_fileName
      Name of the underlying physical file
      protected RecordFilter m_filter
      Filter to be applied to each object read or written
      protected long m_firstDeleted
      File position of the first delete record
    • Constructor Summary

      Constructors 
      Constructor Description
      ObjectDatabaseFile​(java.io.File file, boolean is_new)
      Creates or opens a file that stores objects in variable-length records.
      ObjectDatabaseFile​(java.lang.String name, boolean is_new)
      Creates or opens a file that stores objects in variable-length records.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void assignFilter​(RecordFilter filter)
      Assigns a filter object to translated, encrypt, compress, or otherwise manipulate objects as they are written and read.
      void close()  
      void compact​(ObjectDatabaseCallback callback)
      Compacts a database file by copying it to a new file and deleting the old one.
      protected java.io.ObjectInputStream createObjectInputStream​(java.io.InputStream in)  
      protected java.io.ObjectOutputStream createObjectOutputStream​(java.io.OutputStream out)  
      void delete()
      Deletes the record in the current file position.
      java.io.FileDescriptor getFD()  
      long getFilePointer()  
      long length()  
      java.lang.Object readObject()  
      void rewind()
      Sets the current file pointer to the first byte beyond the file header.
      void rewriteObject​(java.io.Serializable obj)
      Re-writes a serializable object to the file, at the current file position.
      void seek​(long pos)  
      void skip()
      Skips the record at the current file position, moving to the next record in sequence.
      long writeObject​(java.io.Serializable obj)
      Writes a serializable object to the file.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • DEL_LIST_END

        protected static final long DEL_LIST_END
        Marks the end of the list of deleted records
        See Also:
        Constant Field Values
      • IS_DELETED

        protected static final byte IS_DELETED
        Marks a given record as deleted
        See Also:
        Constant Field Values
      • IS_ACTIVE

        protected static final byte IS_ACTIVE
        Marks a given record as containing live data
        See Also:
        Constant Field Values
      • m_dataFile

        protected java.io.RandomAccessFile m_dataFile
        Physical file containing serialized objects
      • m_fileName

        protected java.lang.String m_fileName
        Name of the underlying physical file
      • m_firstDeleted

        protected long m_firstDeleted
        File position of the first delete record
      • m_filter

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

      • ObjectDatabaseFile

        public ObjectDatabaseFile​(java.lang.String name,
                                  boolean is_new)
                           throws java.io.IOException
        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:
        java.io.IOException - when an I/O exception is thrown by an underlying java.io.* class
      • ObjectDatabaseFile

        public ObjectDatabaseFile​(java.io.File file,
                                  boolean is_new)
                           throws java.io.IOException
        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:
        java.io.IOException - when an I/O exception is thrown by an underlying java.io.* class
    • Method Detail

      • writeObject

        public long writeObject​(java.io.Serializable obj)
                         throws java.io.IOException
        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:
        java.io.IOException - when an I/O exception is thrown by an underlying java.io.* class
      • rewriteObject

        public void rewriteObject​(java.io.Serializable obj)
                           throws java.io.IOException
        Re-writes a serializable object to the file, at the current file position.
        Parameters:
        obj - serializable object to be written as a record
        Throws:
        java.io.IOException - when an I/O exception is thrown by an underlying java.io.* class
      • readObject

        public java.lang.Object readObject()
                                    throws java.io.IOException,
                                           java.lang.ClassNotFoundException
        Throws:
        java.io.IOException
        java.lang.ClassNotFoundException
      • delete

        public void delete()
                    throws java.io.IOException
        Deletes the record in the current file position.
        Throws:
        java.io.IOException - when an I/O exception is thrown by an underlying java.io.* class
      • rewind

        public void rewind()
                    throws java.io.IOException
        Sets the current file pointer to the first byte beyond the file header.
        Throws:
        java.io.IOException - when an I/O exception is thrown by an underlying java.io.* class
      • skip

        public void skip()
                  throws java.io.IOException
        Skips the record at the current file position, moving to the next record in sequence.
        Throws:
        java.io.IOException - when an I/O exception is thrown by an underlying java.io.* class
      • compact

        public void compact​(ObjectDatabaseCallback callback)
                     throws java.io.IOException,
                            java.lang.ClassNotFoundException
        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:
        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
      • 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
      • getFD

        public final java.io.FileDescriptor getFD()
                                           throws java.io.IOException
        Throws:
        java.io.IOException
      • getFilePointer

        public long getFilePointer()
                            throws java.io.IOException
        Throws:
        java.io.IOException
      • seek

        public void seek​(long pos)
                  throws java.io.IOException
        Throws:
        java.io.IOException
      • length

        public long length()
                    throws java.io.IOException
        Throws:
        java.io.IOException
      • close

        public void close()
                   throws java.io.IOException
        Throws:
        java.io.IOException
      • createObjectInputStream

        protected java.io.ObjectInputStream createObjectInputStream​(java.io.InputStream in)
                                                             throws java.io.IOException
        Throws:
        java.io.IOException
      • createObjectOutputStream

        protected java.io.ObjectOutputStream createObjectOutputStream​(java.io.OutputStream out)
                                                               throws java.io.IOException
        Throws:
        java.io.IOException