Interface DataTableFile

  • All Superinterfaces:
    TableDataSource

    interface DataTableFile
    extends TableDataSource
    This interface handles the abstraction of retreiving information from a database file. It knows the fixed length of the data fields and can deduce the topology of the file and retreive and store information to/ from it.

    The callee of this interface must ensure that all calls to implementations of this interface are sequential and not concurrent. It is not expected that implementations are thread safe.

    See VariableSizeDataTableFile for an implementation of this interface.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      int addRow​(RowData row_data)
      Adds a complete new row into the table.
      void addRowsLock()
      Locks the data in the file to prevent the system overwritting entries that have been marked as removed.
      void create​(DataTableDef def)
      Creates a new file of the given table.
      boolean doMaintenance()
      This is called periodically when this data table file requires some maintenance.
      void drop()
      Deletes the data table file in the file system.
      boolean hasRowsLocked()
      Returns true if the file currently has all of its rows locked.
      boolean isRowValid​(int record_index)
      Returns true if the given row index points to a valid and available row entry.
      void load​(java.lang.String table_name, boolean read_only)
      Loads a previously created table.
      long nextUniqueKey()
      Returns a unique number.
      void removeRow​(int row_index)
      Removes a row from the table at the given index.
      void removeRowsLock()
      Unlocks the data in the file to indicate that the system may safely overwrite removed entries in the file.
      void shutdown()
      Shuts down the table.
      boolean update​(DataTableDef def)
      Updates a file of the given table.
      void updateFile()
      Flushes all information that may be cached in memory to disk.
    • Method Detail

      • create

        void create​(DataTableDef def)
             throws java.io.IOException
        Creates a new file of the given table. The table is initialised and contains 0 row entries. If the table already exists in the database then this will throw an exception.

        On exit, the object will be initialised and loaded with the given table.

        Parameters:
        def - the definition of the table.
        Throws:
        java.io.IOException
      • update

        boolean update​(DataTableDef def)
                throws java.io.IOException
        Updates a file of the given table. If the table does not exist, then it is created. If the table already exists but is different, then the existing table is modified to incorporate the new fields structure.

        The DataTableFile must have previously been 'load(table_name)' before this call.

        Implementations of this method may choose to reorganise information that the relational schemes are dependant on (the row order for example). If this method returns 'true' then we must also reindex the schemes.

        NOTE: If the new format has columns that are not included in the new format then the columns are deleted.

        Parameters:
        def - the definition of the table.
        Returns:
        true if the table topology has changed.
        Throws:
        java.io.IOException
      • doMaintenance

        boolean doMaintenance()
                       throws java.io.IOException
        This is called periodically when this data table file requires some maintenance. It is recommended that this method is called every time the table is initialized (loaded).

        The DataTableFile must have previously been 'load(table_name)' before this call.

        This method may change the topology of the rows (delete rows that are marked as deleted), therefore if the method returns true you need to re-index the schemes.

        Returns:
        true if the table topology was changed.
        Throws:
        java.io.IOException
      • load

        void load​(java.lang.String table_name,
                  boolean read_only)
           throws java.io.IOException
        Loads a previously created table. A table can be loaded in read only mode, in which case any methods that write to the DataTableFile will throw an IOException.
        Parameters:
        table_name - the name of the table.
        read_only - if true then the table file is opened as read-only.
        Throws:
        java.io.IOException
      • shutdown

        void shutdown()
               throws java.io.IOException
        Shuts down the table. This is called when the table is closed and the resources it uses are to be freed back to the system. This is called as part of the database shut down procedure or called when we want to free the resources associated with this table.
        Throws:
        java.io.IOException
      • drop

        void drop()
        Deletes the data table file in the file system. This is used to clear up resources after a table has been dropped. The table must be shut down before this method is called.

        NOTE: Use this with care. All data is lost!

      • updateFile

        void updateFile()
                 throws java.io.IOException
        Flushes all information that may be cached in memory to disk. This includes any relational data, any cached data that hasn't made it to the file system yet. It will write out all persistant information and leave the table in a state where it is fully represented in the file system.
        Throws:
        java.io.IOException
      • addRowsLock

        void addRowsLock()
        Locks the data in the file to prevent the system overwritting entries that have been marked as removed. This is necessary so we may still safely read removed entries from the table while the table is locked.
      • removeRowsLock

        void removeRowsLock()
        Unlocks the data in the file to indicate that the system may safely overwrite removed entries in the file.
      • hasRowsLocked

        boolean hasRowsLocked()
        Returns true if the file currently has all of its rows locked.
      • isRowValid

        boolean isRowValid​(int record_index)
                    throws java.io.IOException
        Returns true if the given row index points to a valid and available row entry. Returns false if the row entry has been marked as removed, or the index goes outside the bounds of the table.
        Throws:
        java.io.IOException
      • addRow

        int addRow​(RowData row_data)
            throws java.io.IOException
        Adds a complete new row into the table. If the table is in a row locked state, then this will always add a new entry to the end of the table. Otherwise, new entries are added where entries were previously removed.

        This will update any column indices that are set.

        Throws:
        java.io.IOException
      • removeRow

        void removeRow​(int row_index)
                throws java.io.IOException
        Removes a row from the table at the given index. This will only mark the entry as removed, and will not actually remove the data. This is because a process is allowed to read the data even after the row has been marked as removed (if the rows have been locked).

        This will update any column indices that are set.

        Parameters:
        row_index - the raw row index of the entry to be marked as removed.
        Throws:
        java.io.IOException
      • nextUniqueKey

        long nextUniqueKey()
                    throws java.io.IOException
        Returns a unique number. This is incremented each time it is accessed.
        Throws:
        java.io.IOException