# Package 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)

Interface Summary
BlobStoreInterface: A very restricted interface for accessing a blob store.
CellInput
DatabaseConnection.CallBack: Call back interface for events that occur within the connection instance.
DatabaseConstants: Contant static values that determine several parameters of the database operation.
DatabaseProcedure: This interface represents a database procedure that is executed on the server side.
ExpressionPreparer: An interface used to prepare an Expression object.
Function: Represents a function that is part of an expression to be evaluated.
FunctionInfo: Meta information about a function.
FunctionLookup: An interface that resolves and generates a Function objects given a FunctionDef object.
GroupResolver: Similar to VariableResolver, this method is used by grouping Functions to find information about the current group being evaluated (used for evaluating aggregate functions).
IndexSet: A set of list of indexes.
MutableTableDataSource: A mutable data source that allows for the addition and removal of rows.
ProcedureConnection: An interface for accessing a database connection inside a stored procedure.
QueryContext: Facts about a particular query including the root table sources, user name of the controlling context, sequence state, etc.
QueryPlanNode: A node element of a query plan tree.
RawDiagnosticTable: An interface that allows for the inspection and repair of the raw data in a file.
RegexLibrary: An interface that links with a Regex library.
RootTable: Interface that is implemented by all Root tables.
RowEnumeration: This enumeration allows for access to a tables rows.
StatementTreeObject: An complex object that is to be contained within a StatementTree object.
TableDataSource: This interface represents the source of data in a table.
TableQueryDef: An interface to an object that describes characteristics of a table based object in the database.
TransactionModificationListener: A listener that is notified of table modification events made by a transaction, both immediately inside a transaction and when a transaction commits.
TriggerListener: A listener that can listen for high layer trigger events.
VariableResolver: An interface to resolve a variable name to a constant object.

Class Summary
AbstractAggregateFunction: Provides convenience methods for handling aggregate functions (functions that are evaluated over a grouping set).
AbstractDataTable: This is the abstract class implemented by a DataTable like table.
AbstractFunction: An abstract implementation of Function.
AbstractQueryContext: An abstract implementation of QueryContext
Assignment: An assignment from a variable to an expression.
BlindSearch: This is a scheme that performs a blind search of a given set.
Caster: Methods to choose and perform casts from database type to Java types.
CellBufferOutputStream: This is a ByteArrayOutputStream that allows access to the underlying byte array.
CollatedBaseSearch: An implementation of SelectableScheme that is based on some collated set of data.
CompositeTable: A composite of two or more datasets used to implement UNION, INTERSECTION, and DIFFERENCE.
ConnectionTriggerManager: A trigger manager on a DatabaseConnection that maintains a list of all triggers set in the database, and the types of triggers they are.
CorrelatedVariable: A wrapper for a variable in a sub-query that references a column outside of the current query.
Database: The representation of a single database in the system.
DatabaseConnection: An object that represents a connection to a Database.
DatabaseQueryContext: An implementation of a QueryContext based on a DatabaseConnection object.
DatabaseSystem: This class provides information about shared resources available for the entire database system running in this VM.
DataIndexDef: Represents index meta-information on a table.
DataIndexSetDef: Represents the meta-data for a set of indexes of a table.
DataTable: DataTable is a wrapper for a MutableTableDataSource that fits into the query hierarchy level.
DataTableColumnDef: All the information regarding a column in a table.
DataTableDef: A definition of a table.
DataTableFilter: This object sits on top of a DataTable object filtering out certain types of calls.
DefaultDataTable: This represents a default implementation of a DataTable.
Expression: An expression that can be evaluated in a statement.
FilterTable: A table that is a filter for another table.
FixedRecordList: A structure that provides a fast way to read and write fixed sized nodes in a Store object.
FixedSizeDataStore: A file format that allows for the very quick retreival of data that is stored within it.
FunctionDef: A definition of a function including its name and parameters.
FunctionFactory: A factory that generates Function objects given a function name and a set of expression's that represent parameters.
FunctionTable: A table that has a number of columns and as many rows as the refering table.
GrantManager: A class that manages the grants on a database for a given database connection and user.
GTPrivMapDataSource: A GTDataSource that maps a Privs 11-bit set to strings that represent the priv in human understandable string.
GTSQLTypeInfoDataSource: A GTDataSource that models all SQL types that are available.
IndexStore: A class that manages the storage of a set of transactional index lists in a way that is fast to modify.
InsertSearch: This is a SelectableScheme similar in some ways to the binary tree.
JoinedTable: A Table that represents the result of one or more other tables joined together.
JoiningSet: Used in TableSet to describe how we naturally join the tables together.
JoiningSet.JoinPart
Lock: This is a lock on a table in the LockingMechanism class.
LockHandle: This represents a handle for a series of locks that a query has over the tables in a database.
LockingMechanism: This class represents a model for locking the tables in a database during any sequence of concurrent read/write accesses.
NaturallyJoinedTable: A table that is the cartesian product of two tables.
Operator: An operator for an expression.
ParameterSubstitution: An object that represents a constant value that is to be lately binded to a constant value in an Expression.
PatternSearch: This is a static class that performs the operations to do a pattern search on a given column of a table.
Privileges: A set of privileges to grant a user for an object.
ProcedureManager: A DatabaseConnection procedure manager.
ProcedureName: The name of a procedure as understood by a ProcedureManager.
QueryPlan: Various helper methods for constructing a plan tree, and the plan node implementations themselves.
QueryPlan.BranchQueryPlanNode: A QueryPlanNode that is a branch with two child nodes.
QueryPlan.CachePointNode: A cache point node that only evaluates the child if the result can not be found in the cache with the given unique id.
QueryPlan.CompositeNode: A branch node for performing a composite function on two child nodes.
QueryPlan.ConstantSelectNode: The node for evaluating an expression that contains entirely constant values (no variables).
QueryPlan.CreateFunctionsNode: The node for merging the child node with a set of new function columns over the entire result.
QueryPlan.DistinctNode: The node for performing a distinct operation on the given columns of the child node.
QueryPlan.EquiJoinNode: A branch node for equi-joining two tables together given two sets of columns.
QueryPlan.ExhaustiveSelectNode: The node for performing a exhaustive select operation on the child node.
QueryPlan.FetchTableNode: The node for fetching a table from the current transaction.
QueryPlan.FetchViewNode: The node that fetches a view from the current connection.
QueryPlan.FunctionalSelectNode: The node for performing a functional select operation on the child node.
QueryPlan.GroupNode: The node for performing a grouping operation on the columns of the child node.
QueryPlan.JoinNode: A branch node for a non-equi join between two tables.
QueryPlan.LeftOuterJoinNode: A branch node for a left outer join.
QueryPlan.LogicalUnionNode: A branch node for a logical union of two tables of identical types.
QueryPlan.MarkerNode: A marker node that takes the result of a child and marks it as a name that can later be retrieved.
QueryPlan.MultiColumnEquiSelectNode: The node for performing an equi-select on a group of columns of the child node.
QueryPlan.NaturalJoinNode: A branch node for naturally joining two tables together.
QueryPlan.NonCorrelatedAnyAllNode: A branch node for a non-correlated ANY or ALL sub-query evaluation.
QueryPlan.RangeSelectNode: The node for performing a simple indexed query on a single column of the child node.
QueryPlan.SimplePatternSelectNode: The node for evaluating a simple pattern search on a table which includes a single left hand variable or constant, a pattern type (LIKE, NOT LIKE or REGEXP), and a right hand constant (eg.
QueryPlan.SimpleSelectNode: The node for performing a simple select operation on a table.
QueryPlan.SingleQueryPlanNode: A QueryPlanNode with a single child.
QueryPlan.SingleRowTableNode: A node for creating a table with a single row.
QueryPlan.SortNode: The node for performing a sort operation on the given columns of the child node.
QueryPlan.SubsetNode: The node for finding a subset and renaming the columns of the results in the child node.
ReferenceTable: This is an implementation of a Table that references a DataTable as its parent.
RowData: Represents a row of data to be added into a table.
SchemaDef: A definition of a schema.
SelectableRange: An object that represents a range of values to select from a list.
SelectableRangeSet: Represents a complex normalized range of a list.
SelectableScheme: Represents a base class for a mechanism to select ranges from a given set.
SimpleRowEnumeration: A RowEnumeration implementation that represents a sequence of rows that can be referenced in incremental order between 0 and row_count (exclusive).
SimpleTableQuery: A simple convenience interface for querying a MutableTableDataSource instance.
SimpleTransaction: An simple implementation of Transaction that provides various facilities for implementing a Transaction object on a number of MasterTableDataSource tables.
StatementCache: A cache that maintains a serialized set of StatementTree objects that can be deserialized on demand.
StatementTree: A serializable container class for a parsed query language statement.
SubsetColumnTable: This object is a filter that sits atop a Table object.
Table: This is a definition for a table in the database.
TableAccessState: This class provides very limited access to a Table object.
TableCommitModificationEvent: An object that encapsulates all row modification information about a table when a change to the table is about to be committed.
TableDataConglomerate: A conglomerate of data that represents the contents of all tables in a complete database.
TableDescriptions: An object that is a key part of Database.
TableFunctions: A number of functions that are table set functions such as simple select operations, joins, unions, sub-query operations, etc.
TableModificationEvent: The event information of when a table is modified inside a transaction.
TableName: A name of a table and any associated referencing information.
TArrayType: An implementation of TType for an expression array.
TBinaryType: An implementation of TType for a binary block of data.
TBooleanType: An implementation of TType for a boolean value.
TDateType: An implementation of TType for date objects.
TemporaryTable: This class represents a temporary table that is built from data that is not related to any underlying DataTable object from the database.
TJavaObjectType: An implementation of TType for a java object of possibly defined type.
TNullType: An implementation of TType that represents a NULL type.
TNumericType: An implementation of TType for a number.
TObject: A TObject is a strongly typed object in a database engine.
TQueryPlanType: An implementation of TType for a query plan value.
Transaction: An open transaction that manages all data access to the TableDataConglomerate.
Transaction.CheckExpression: Represents a constraint expression to check.
Transaction.ColumnGroup: A group of columns as used by the constraint system.
Transaction.ColumnGroupReference: Represents a reference from a group of columns in one table to a group of columns in another table.
TransactionSystem: A class that provides information and global functions for the transaction layer in the engine.
TriggerEvent: A trigger event represents a high level action that occured in the database.
TStringType: An implementation of TType for a String.
TType: A TType object represents a type in a database engine.
User: Encapsulates the information about a single user logged into the system.
UserManager: A class that manages the list of users connected to the engine.
V1MasterTableDataSource: A MasterTableDataSource that uses IndexStore and VariableSizeDataStore as its backing mechanism for representing the table structure in a file on disk.
V2MasterTableDataSource: A MasterTableDataSource that is backed by a non-shared com.mckoi.store.Store object.
Variable: This represents a column name that may be qualified.
VariableSizeDataStore: Provides a mechanism for storing variable length data in a file which can quickly be indexed via a reference number.
ViewDef: A ViewDef object is a definition of a view stored in the database.
ViewManager: A DatabaseConnection view manager.
VirtualTable: A VirtualTable is a representation of a table whose rows are actually physically stored in another table.

Exception Summary
DatabaseConstraintViolationException: A database exception that represents a constraint violation.
DatabaseException: Exception thrown where various problems occur within the database.
ProcedureException: An exception that is generated from a stored procedure when some erronious condition occurs.
StatementException: An error that is thrown when there is erronious information in a statement.
TransactionException: Thrown when a transaction error happens.
UserAccessException: An exception that is thrown when the user is not permitted to perform a certain action.