com.mckoi.database

The core database classes for Mckoi.

Data Representation

A database is represented by a single TableDataConglomerate, which contains a collection of MasterTableDataSource objects, each of which represents a single table, including both committed and uncommitted rows.

Access to a table is usually through the TableDataSource interface, or its subclass MutableTableDataSource The MasterTableDataSource objects wrap themselves in an instance of the private class MasterTableDataSource.MMutableTableDataSource, which implements MutableTableDataSource.

The format of a table is defined by DataTableDef, which is returned by TableDataSource.getDataTableDef, and which does not change during the lifetime of the table; if the table format is changed, a new MasterTableDataSource is created within the Transaction with the new format, and the data and unchanged columns from the old table are copied to the new one. The format of a column is defined by DataTableColumnDef.

Modifications to a row of a table are handled by a RowData, which carries a reference to the TableDataSource which it modified, and from which data is retrieved. Each column within the row is represented by a DataCell, which is either retrieved from the table or created by DataCellFactory.

Transactions

A database can be associated with one or more simultaneous Transaction objects. All changes to the data in the database are done through Transactions. The current set of open Transaction objects is managed by an OpenTransactionList object, which is pointed to by both the TableDataConglomerate and all of the MasterTableDataSource objects.

Changes to a row are handled by creating a new row in the MasterTableDataSource containing the changed data plus any old data which is unchanged. The data for the modified row are kept in a RowData, which references a QueryContext, which references a DatabaseConnection, which references a Transaction, which is the Transaction under which that change was made. Each field of the row is represented by a DataCell.

When an application issues an SQL request to update the database, it eventually makes it down to Statement.evaluate, for example in Insert. That evaluate method uses its DatabaseConnection to get a DataTable for a table name, which is a wrapper around the MutableTableDataSource returned by the DatabaseConnection's Transaction for the table of that name. The MutableTableDataSource (created by Transaction.getTable) is in turn a wrapper around a MasterTableDataSource created using the private class MasterTableDataSource.MMutableTableDataSource. The Statement uses its DataTable to create a RowData, then passes it to its DataTable, which passes it to the MutableTableDataSource, which passes it to the MasterTableDataSource, which actually makes the change.

The Transaction maintains a TransactionJournal, in which are listed all of the tables which have been changed by the Transaction.

Eventually the Transaction is closed (committed or rolled back), which is handled by the TableDataConglomerate ( processCommit or processRollback), which, for each MasterTableDataSource, gets a MasterTableJournal for it from the TransactionJournal specifying what changes have been made in that table from this Transaction, and tells that MasterTableDataSource to commit or roll back the changes in that MasterTableJournal.

Locking

Locking is used to control concurrent access by two requests in the same Transaction. This is handled during query execution in JDBCDatabaseInterface.execQuery

Each DatabaseConnection has associated with it a single LockingMechanism object, which is used to lock and unlock the DatabaseConnection's Transaction as a whole. The active lock is represented by a LockHandle, which is returned by LockingMechanism.lockTables, and which is passed back to LockingMechanism.unlockTables to drop the lock.

A lock on an individual table is represented by a Lock, which is kept in a LockingQueue, which maintains the link to the locked table.

Update Sequence

When a change is made to the database (insert, update, or delete), the following list shows the sequence in which various steps are taken:

• Check to see if user has privileges to make the change (Insert.evaluate, UpdateTable.evaluate, Delete.evaluate)
• Check to see if the table is read-only ( MasterTableDataSource.MMutableTableDataSource.addRow, updateRow, removeRow)
• Mark the old row for removal ( MasterTableDataSource.MMutableTableDataSource.updateRow, removeRow)
• Add the new data and write the changes out to disk ( MasterTableDataSource.addRow)
• Check table constraints for removal of old data (MasterTableDataSource.MMutableTableDataSource calls TableDataConglomerate.checkRemoveConstraintViolations)
• Check field constraints on the new data (MasterTableDataSource.MMutableTableDataSource calls TableDataConglomerate.checkFieldConstraintViolations)
• Check table constraints on the new data (MasterTableDataSource.MMutableTableDataSource calls TableDataConglomerate.checkAddConstraintViolations)

NOTE: This is not designed to be a long kept object.

NOTE: This is not designed to be a long kept object.

NOTE: This is not designed to be a long kept object.

NOTE: This is not designed to be a long kept object.

NOTE: This is not designed to be a long kept object.

NOTE: This is not designed to be a long kept object.

NOTE: This is not designed to be a long kept object.

Every table in the database has an 'access_queue' that is generated the first time the table is accessed.

A given element in the set is specified through a 'row' integer whose contents can be obtained through the 'table.getCellContents(column, row)'. Every scheme is given a table and column number that the set refers to. While a given set element is refered to as a 'row', the integer is really only a pointer into the set list which can be de-referenced with a call to table.getCellContents(row).

This interface is an abstraction of the database persistence layer.

This object also serves as a storage for session state information.