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.-
Methods inherited from interface com.mckoi.database.TableDataSource
getCellContents, getColumnScheme, getDataTableDef, getRowCount, getSystem, rowEnumeration
-
-
-
-
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
-
-