com.mckoi.database.package.html Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of mckoisqldb Show documentation
A full SQL database system with JDBC driver that can be embedded in a Java application or operate as a stand-alone server with clients connecting via TCP/IP.
The newest version!


com.mckoi.database - The core database classes for Mckoi



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)