Package com.mckoi.database

## Class Transaction

- java.lang.Object
- - com.mckoi.database.SimpleTransaction
  - - com.mckoi.database.Transaction

    public class Transaction
    extends SimpleTransaction

An open transaction that manages all data access to the TableDataConglomerate. A transaction sees a view of the data as it was when the transaction was created. It also sees any modifications that were made within the context of this transaction. It does not see modifications made by other open transactions.

A transaction ends when it is committed or rollbacked. All operations on this transaction object only occur within the context of this transaction and are not permanent changes to the database structure. Only when the transaction is committed are changes reflected in the master data.

Author:
  Tobias Downer

### Nested Class Summary

Nested Classes
`static class` `Transaction.CheckExpression` Represents a constraint expression to check.
`static class` `Transaction.ColumnGroup` A group of columns as used by the constraint system.
`static class` `Transaction.ColumnGroupReference` Represents a reference from a group of columns in one table to a group of columns in another table.

### Field Summary

Fields
`static java.lang.String` `CASCADE`
`static short` `INITIALLY_DEFERRED` The type of deferrance.
`static short` `INITIALLY_IMMEDIATE`
`static java.lang.String` `NO_ACTION` Foreign key referential trigger actions.
`static short` `NOT_DEFERRABLE`
`static java.lang.String` `SET_DEFAULT`
`static java.lang.String` `SET_NULL`

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`void` `addCheckConstraint​(TableName table_name, Expression expression, short deferred, java.lang.String constraint_name)` Adds a check expression that becomes perminent when the transaction is committed.
`void` `addForeignKeyConstraint​(TableName table, java.lang.String[] cols, TableName ref_table, java.lang.String[] ref_cols, java.lang.String delete_rule, java.lang.String update_rule, short deferred, java.lang.String constraint_name)` Adds a foreign key constraint to the database which becomes perminent when the transaction is committed.
`void` `addPrimaryKeyConstraint​(TableName table_name, java.lang.String[] cols, short deferred, java.lang.String constraint_name)` Adds a primary key constraint that becomes perminent when the transaction is committed.
`void` `addSelectedFromTable​(TableName table_name)` Called by the query evaluation layer when information is selected from this table as part of this transaction.
`void` `addUniqueConstraint​(TableName table_name, java.lang.String[] cols, short deferred, java.lang.String constraint_name)` Adds a unique constraint to the database which becomes perminant when the transaction is committed.
`void` `alterCreateTable​(DataTableDef table_def, int data_sector_size, int index_sector_size)` Given a DataTableDef, if the table exists then it is updated otherwise if it doesn't exist then it is created.
`void` `alterTable​(TableName table_name, DataTableDef table_def)` Alters the table with the given name within this transaction to the specified table definition.
`void` `alterTable​(TableName table_name, DataTableDef table_def, int data_sector_size, int index_sector_size)` Alter the table with the given name to the new definition and give the copied table a new data sector size.
`void` `checkAllConstraints​(TableName table_name)` Checks all the rows in the table for immediate constraint violations and when the transaction is next committed check for all deferred constraint violations.
`void` `closeAndCommit()` Closes and marks a transaction as committed.
`void` `closeAndRollback()` Closes and rolls back a transaction as if the commands the transaction ran never happened.
`void` `compactTable​(TableName table_name)` Compacts the table with the given name within this transaction.
`void` `copyTable​(com.mckoi.database.MasterTableDataSource src_master_table, IndexSet index_set)` Generates an exact copy of the table within this transaction.
`MutableTableDataSource` `createMutableTableDataSourceAtCommit​(com.mckoi.database.MasterTableDataSource master)` Overwritten from SimpleTransaction.
`void` `createSchema​(java.lang.String name, java.lang.String type)` Create a new schema in this transaction.
`void` `createSequenceGenerator​(TableName name, long start_value, long increment_by, long min_value, long max_value, long cache, boolean cycle)` Creates a new sequence generator with the given TableName and initializes it with the given details.
`void` `createTable​(DataTableDef table_def)` Creates a new table within this transaction.
`void` `createTable​(DataTableDef table_def, int data_sector_size, int index_sector_size)` Creates a new table within this transaction with the given sector size.
`void` `dropAllConstraintsForTable​(TableName table_name)` Drops all the constraints defined for the given table.
`boolean` `dropCheckConstraintForTable​(TableName table, java.lang.String constraint_name)` Drops a single named check constraint from the given table.
`boolean` `dropForeignKeyReferenceConstraintForTable​(TableName table, java.lang.String constraint_name)` Drops a single named foreign key reference from the given table.
`int` `dropNamedConstraint​(TableName table_name, java.lang.String constraint_name)` Drops the named constraint from the transaction.
`boolean` `dropPrimaryKeyConstraintForTable​(TableName table_name, java.lang.String constraint_name)` Drops the primary key constraint for the given table.
`void` `dropSchema​(java.lang.String name)` Drops a schema from this transaction.
`void` `dropSequenceGenerator​(TableName name)` Drops an existing sequence generator with the given name.
`void` `dropTable​(TableName table_name)` Drops a table within this transaction.
`boolean` `dropUniqueConstraintForTable​(TableName table, java.lang.String constraint_name)` Drops a single named unique constraint from the given table.
`void` `finalize()` Finalize, we should close the transaction.
`protected DataTableDef` `getDynamicDataTableDef​(TableName table_name)` Returns the DataTableDef for the given internal table.
`protected MutableTableDataSource` `getDynamicTable​(TableName table_name)` Returns an instance of MutableDataTableSource that represents the contents of the internal table with the given name.
`protected TableName[]` `getDynamicTableList()` Returns a list of all dynamic table names.
`java.lang.String` `getDynamicTableType​(TableName table_name)` Returns a string type describing the type of the dynamic table.
`java.lang.String` `getPersistantVar​(java.lang.String variable)` Returns the value of the persistent variable with the given name or null if it doesn't exist.
`SchemaDef[]` `getSchemaList()` Returns an array of SchemaDef objects for each schema currently setup in the database.
`protected boolean` `isDynamicTable​(TableName table_name)` Returns true if the given table name represents a dynamically generated system table.
`static Transaction.CheckExpression[]` `queryTableCheckExpressions​(SimpleTransaction transaction, TableName table_name)` Returns a set of check expressions that are constrained over all new columns added to the given table in this transaction.
`static Transaction.ColumnGroupReference[]` `queryTableForeignKeyReferences​(SimpleTransaction transaction, TableName table_name)` Returns an array of column references in the given table that represent foreign key references.
`static Transaction.ColumnGroupReference[]` `queryTableImportedForeignKeyReferences​(SimpleTransaction transaction, TableName ref_table_name)` Returns an array of column references in the given table that represent foreign key references that reference columns in the given table.
`static Transaction.ColumnGroup` `queryTablePrimaryKeyGroup​(SimpleTransaction transaction, TableName table_name)` Returns a set of primary key groups that are constrained to be unique for the given table in this transaction (there can be only 1 primary key defined for a table).
`static TableName[]` `queryTablesRelationallyLinkedTo​(SimpleTransaction transaction, TableName table)` Returns the list of tables (as a TableName array) that are dependant on the data in the given table to maintain referential consistancy.
`static Transaction.ColumnGroup[]` `queryTableUniqueGroups​(SimpleTransaction transaction, TableName table_name)` Returns a set of unique groups that are constrained to be unique for the given table in this transaction.
`SchemaDef` `resolveSchemaCase​(java.lang.String name, boolean ignore_case)` Resolves the case of the given schema name if the database is performing case insensitive identifier matching.
`boolean` `schemaExists​(java.lang.String name)` Returns true if the schema exists within this transaction.
`void` `setPersistentVar​(java.lang.String variable, java.lang.String value)` Sets a persistent variable of the database that becomes a committed change once this transaction is committed.

### Methods inherited from class com.mckoi.database.SimpleTransaction

`currentUniqueID, Debug, disposeAllIndices, findVisibleTable, flushTableCache, getDataTableDef, getSystem, getTable, getTableDataSource, getTableList, getTableType, getVisibleTable, getVisibleTableCount, getVisibleTables, isReadOnly, lastSequenceValue, nextSequenceValue, nextUniqueID, resolveToTableName, setIndexSetForTable, setReadOnly, setSequenceValue, setUniqueID, tableExists, tryResolveCase`

### Methods inherited from class java.lang.Object

`clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### INITIALLY_DEFERRED

    public static final short INITIALLY_DEFERRED

The type of deferrance.

See Also:
  Constant Field Values

#### INITIALLY_IMMEDIATE

    public static final short INITIALLY_IMMEDIATE

See Also:
  Constant Field Values

#### NOT_DEFERRABLE

    public static final short NOT_DEFERRABLE

See Also:
  Constant Field Values

#### NO_ACTION

    public static final java.lang.String NO_ACTION

Foreign key referential trigger actions.

See Also:
  Constant Field Values

#### CASCADE

    public static final java.lang.String CASCADE

See Also:
  Constant Field Values

#### SET_NULL

    public static final java.lang.String SET_NULL

See Also:
  Constant Field Values

#### SET_DEFAULT

    public static final java.lang.String SET_DEFAULT

See Also:
  Constant Field Values

### Method Detail

#### createMutableTableDataSourceAtCommit

    public MutableTableDataSource createMutableTableDataSourceAtCommit​(com.mckoi.database.MasterTableDataSource master)

Overwritten from SimpleTransaction. Returns a new MutableTableDataSource for the view of the MasterTableDataSource at the start of this transaction. Note that this is only ever called once per table accessed in this transaction.

#### addSelectedFromTable

    public void addSelectedFromTable​(TableName table_name)

Called by the query evaluation layer when information is selected from this table as part of this transaction. When there is a select query on a table, when the transaction is committed we should look for any concurrently committed changes to the table. If there are any, then any selects on the table should be considered incorrect and cause a commit failure.

#### isDynamicTable

    protected boolean isDynamicTable​(TableName table_name)

Returns true if the given table name represents a dynamically generated system table.

Overrides:
  `isDynamicTable` in class `SimpleTransaction`

#### getDynamicTableList

    protected TableName[] getDynamicTableList()

Returns a list of all dynamic table names. This method returns a reference to a static, make sure you don't change the contents of the array!

Overrides:
  `getDynamicTableList` in class `SimpleTransaction`

#### getDynamicDataTableDef

    protected DataTableDef getDynamicDataTableDef​(TableName table_name)

Returns the DataTableDef for the given internal table.

Overrides:
  `getDynamicDataTableDef` in class `SimpleTransaction`

#### getDynamicTable

    protected MutableTableDataSource getDynamicTable​(TableName table_name)

Returns an instance of MutableDataTableSource that represents the contents of the internal table with the given name.

Overrides:
  `getDynamicTable` in class `SimpleTransaction`

#### getDynamicTableType

    public java.lang.String getDynamicTableType​(TableName table_name)

Returns a string type describing the type of the dynamic table.

Overrides:
  `getDynamicTableType` in class `SimpleTransaction`

#### createTable

    public void createTable​(DataTableDef table_def,
                            int data_sector_size,
                            int index_sector_size)

Creates a new table within this transaction with the given sector size. If the table already exists then an exception is thrown.

This should only be called under an exclusive lock on the connection.

#### createTable

    public void createTable​(DataTableDef table_def)

Creates a new table within this transaction. If the table already exists then an exception is thrown.

This should only be called under an exclusive lock on the connection.

#### alterCreateTable

    public void alterCreateTable​(DataTableDef table_def,
                                 int data_sector_size,
                                 int index_sector_size)

Given a DataTableDef, if the table exists then it is updated otherwise if it doesn't exist then it is created.

This should only be used as very fine grain optimization for creating/ altering tables. If in the future the underlying table model is changed so that the given 'sector_size' value is unapplicable, then the value will be ignored.

#### dropTable

    public void dropTable​(TableName table_name)

Drops a table within this transaction. If the table does not exist then an exception is thrown.

This should only be called under an exclusive lock on the connection.

#### copyTable

    public void copyTable​(com.mckoi.database.MasterTableDataSource src_master_table,
                          IndexSet index_set)

Generates an exact copy of the table within this transaction. It is recommended that the table is dropped before the copy is made. The purpose of this method is to generate a temporary table that can be modified without fear of another transaction changing the contents in another transaction. This also provides a convenient way to compact a table because any spare space is removed when the table is copied. It also allows us to make a copy of MasterTableDataSource into a foreign conglomerate which allows us to implement a backup procedure.

This method does NOT assume the given MasterTableDataSource is contained, or has once been contained within this conglomerate.

#### alterTable

    public void alterTable​(TableName table_name,
                           DataTableDef table_def,
                           int data_sector_size,
                           int index_sector_size)

Alter the table with the given name to the new definition and give the copied table a new data sector size. If the table does not exist then an exception is thrown.

This copies all columns that were in the original table to the new altered table if the name is the same. Any names that don't exist are set to the default value.

This should only be called under an exclusive lock on the connection.

#### alterTable

    public void alterTable​(TableName table_name,
                           DataTableDef table_def)

Alters the table with the given name within this transaction to the specified table definition. If the table does not exist then an exception is thrown.

This should only be called under an exclusive lock on the connection.

#### checkAllConstraints

    public void checkAllConstraints​(TableName table_name)

Checks all the rows in the table for immediate constraint violations and when the transaction is next committed check for all deferred constraint violations. This method is used when the constraints on a table changes and we need to determine if any constraint violations occurred. To the constraint checking system, this is like adding all the rows to the given table.

#### compactTable

    public void compactTable​(TableName table_name)

Compacts the table with the given name within this transaction. If the table doesn't exist then an exception is thrown.

#### createSchema

    public void createSchema​(java.lang.String name,
                             java.lang.String type)

Create a new schema in this transaction. When the transaction is committed the schema will become globally accessable. Note that any security checks must be performed before this method is called.

NOTE: We must guarentee that the transaction be in exclusive mode before this method is called.

#### dropSchema

    public void dropSchema​(java.lang.String name)

Drops a schema from this transaction. When the transaction is committed the schema will be dropped perminently. Note that any security checks must be performed before this method is called.

NOTE: We must guarentee that the transaction be in exclusive mode before this method is called.

#### schemaExists

    public boolean schemaExists​(java.lang.String name)

Returns true if the schema exists within this transaction.

#### resolveSchemaCase

    public SchemaDef resolveSchemaCase​(java.lang.String name,
                                       boolean ignore_case)

Resolves the case of the given schema name if the database is performing case insensitive identifier matching. Returns a SchemaDef object that identifiers the schema. Returns null if the schema name could not be resolved.

#### getSchemaList

    public SchemaDef[] getSchemaList()

Returns an array of SchemaDef objects for each schema currently setup in the database.

#### setPersistentVar

    public void setPersistentVar​(java.lang.String variable,
                                 java.lang.String value)

Sets a persistent variable of the database that becomes a committed change once this transaction is committed. The variable can later be retrieved with a call to the 'getPersistantVar' method. A persistant var is created if it doesn't exist in the DatabaseVars table otherwise it is overwritten.

#### getPersistantVar

    public java.lang.String getPersistantVar​(java.lang.String variable)

Returns the value of the persistent variable with the given name or null if it doesn't exist.

#### createSequenceGenerator

    public void createSequenceGenerator​(TableName name,
                                        long start_value,
                                        long increment_by,
                                        long min_value,
                                        long max_value,
                                        long cache,
                                        boolean cycle)

Creates a new sequence generator with the given TableName and initializes it with the given details. This does NOT check if the given name clashes with an existing database object.

#### dropSequenceGenerator

    public void dropSequenceGenerator​(TableName name)

Drops an existing sequence generator with the given name.

#### addUniqueConstraint

    public void addUniqueConstraint​(TableName table_name,
                                    java.lang.String[] cols,
                                    short deferred,
                                    java.lang.String constraint_name)

Adds a unique constraint to the database which becomes perminant when the transaction is committed. Columns in a table that are defined as unique are prevented from being duplicated by the engine.

NOTE: Security checks for adding constraints must be checked for at a higher layer.

NOTE: We must guarentee that the transaction be in exclusive mode before this method is called.

#### addForeignKeyConstraint

    public void addForeignKeyConstraint​(TableName table,
                                        java.lang.String[] cols,
                                        TableName ref_table,
                                        java.lang.String[] ref_cols,
                                        java.lang.String delete_rule,
                                        java.lang.String update_rule,
                                        short deferred,
                                        java.lang.String constraint_name)

Adds a foreign key constraint to the database which becomes perminent when the transaction is committed. A foreign key represents a referential link from one table to another (may be the same table). The 'table_name', 'cols' args represents the object to link from. The 'ref_table', 'ref_cols' args represents the object to link to. The update rules are for specifying cascading delete/update rules. The deferred arg is for IMMEDIATE/DEFERRED checking.

NOTE: Security checks for adding constraints must be checked for at a higher layer.

NOTE: We must guarentee that the transaction be in exclusive mode before this method is called.

#### addPrimaryKeyConstraint

    public void addPrimaryKeyConstraint​(TableName table_name,
                                        java.lang.String[] cols,
                                        short deferred,
                                        java.lang.String constraint_name)

Adds a primary key constraint that becomes perminent when the transaction is committed. A primary key represents a set of columns in a table that are constrained to be unique and can not be null. If the constraint name parameter is 'null' a primary key constraint is created with a unique constraint name.

NOTE: Security checks for adding constraints must be checked for at a higher layer.

NOTE: We must guarentee that the transaction be in exclusive mode before this method is called.

#### addCheckConstraint

    public void addCheckConstraint​(TableName table_name,
                                   Expression expression,
                                   short deferred,
                                   java.lang.String constraint_name)

Adds a check expression that becomes perminent when the transaction is committed. A check expression is an expression that must evaluate to true for all records added/updated in the database.

NOTE: Security checks for adding constraints must be checked for at a higher layer.

NOTE: We must guarentee that the transaction be in exclusive mode before this method is called.

#### dropAllConstraintsForTable

    public void dropAllConstraintsForTable​(TableName table_name)

Drops all the constraints defined for the given table. This is a useful function when dropping a table from the database.

NOTE: Security checks that the user can drop constraints must be checke at a higher layer.

NOTE: We must guarentee that the transaction be in exclusive mode before this method is called.

#### dropNamedConstraint

    public int dropNamedConstraint​(TableName table_name,
                                   java.lang.String constraint_name)

Drops the named constraint from the transaction. Used when altering table schema. Returns the number of constraints that were removed from the system. If this method returns 0 then it indicates there is no constraint with the given name in the table.

NOTE: Security checks that the user can drop constraints must be checke at a higher layer.

NOTE: We must guarentee that the transaction be in exclusive mode before this method is called.

#### dropPrimaryKeyConstraintForTable

    public boolean dropPrimaryKeyConstraintForTable​(TableName table_name,
                                                    java.lang.String constraint_name)

Drops the primary key constraint for the given table. Used when altering table schema. If 'constraint_name' is null this method will search for the primary key of the table name. Returns true if the primary key constraint was dropped (the constraint existed).

NOTE: Security checks that the user can drop constraints must be checke at a higher layer.

NOTE: We must guarentee that the transaction be in exclusive mode before this method is called.

#### dropUniqueConstraintForTable

    public boolean dropUniqueConstraintForTable​(TableName table,
                                                java.lang.String constraint_name)

Drops a single named unique constraint from the given table. Returns true if the unique constraint was dropped (the constraint existed).

NOTE: Security checks that the user can drop constraints must be checke at a higher layer.

NOTE: We must guarentee that the transaction be in exclusive mode before this method is called.

#### dropCheckConstraintForTable

    public boolean dropCheckConstraintForTable​(TableName table,
                                               java.lang.String constraint_name)

Drops a single named check constraint from the given table. Returns true if the check constraint was dropped (the constraint existed).

NOTE: Security checks that the user can drop constraints must be checke at a higher layer.

NOTE: We must guarentee that the transaction be in exclusive mode before this method is called.

#### dropForeignKeyReferenceConstraintForTable

    public boolean dropForeignKeyReferenceConstraintForTable​(TableName table,
                                                             java.lang.String constraint_name)

Drops a single named foreign key reference from the given table. Returns true if the foreign key reference constraint was dropped (the constraint existed).

NOTE: Security checks that the user can drop constraints must be checke at a higher layer.

NOTE: We must guarentee that the transaction be in exclusive mode before this method is called.

#### queryTablesRelationallyLinkedTo

    public static TableName[] queryTablesRelationallyLinkedTo​(SimpleTransaction transaction,
                                                              TableName table)

Returns the list of tables (as a TableName array) that are dependant on the data in the given table to maintain referential consistancy. The list includes the tables referenced as foreign keys, and the tables that reference the table as a foreign key.

This is a useful query for determining ahead of time the tables that require a read lock when inserting/updating a table. A table will require a read lock if the operation needs to query it for potential referential integrity violations.

#### queryTableUniqueGroups

    public static Transaction.ColumnGroup[] queryTableUniqueGroups​(SimpleTransaction transaction,
                                                                   TableName table_name)

Returns a set of unique groups that are constrained to be unique for the given table in this transaction. For example, if columns ('name') and ('number', 'document_rev') are defined as unique, this will return an array of two groups that represent unique columns in the given table.

#### queryTablePrimaryKeyGroup

    public static Transaction.ColumnGroup queryTablePrimaryKeyGroup​(SimpleTransaction transaction,
                                                                    TableName table_name)

Returns a set of primary key groups that are constrained to be unique for the given table in this transaction (there can be only 1 primary key defined for a table). Returns null if there is no primary key defined for the table.

#### queryTableCheckExpressions

    public static Transaction.CheckExpression[] queryTableCheckExpressions​(SimpleTransaction transaction,
                                                                           TableName table_name)

Returns a set of check expressions that are constrained over all new columns added to the given table in this transaction. For example, we may want a column called 'serial_number' to be constrained as CHECK serial_number LIKE '___-________-___'.

#### queryTableForeignKeyReferences

    public static Transaction.ColumnGroupReference[] queryTableForeignKeyReferences​(SimpleTransaction transaction,
                                                                                    TableName table_name)

Returns an array of column references in the given table that represent foreign key references. For example, say a foreign reference has been set up in the given table as follows;

       FOREIGN KEY (customer_id) REFERENCES Customer (id)

This method will return the column group reference Order(customer_id) -> Customer(id).

This method is used to check that a foreign key reference actually points to a valid record in the referenced table as expected.

#### queryTableImportedForeignKeyReferences

    public static Transaction.ColumnGroupReference[] queryTableImportedForeignKeyReferences​(SimpleTransaction transaction,
                                                                                            TableName ref_table_name)

Returns an array of column references in the given table that represent foreign key references that reference columns in the given table. This is a reverse mapping of the 'queryTableForeignKeyReferences' method. For example, say a foreign reference has been set up in any table as follows;

       [ In table Order ]
       FOREIGN KEY (customer_id) REFERENCE Customer (id)

And the table name we are querying is 'Customer' then this method will return the column group reference Order(customer_id) -> Customer(id).

This method is used to check that a reference isn't broken when we remove a record (for example, removing a Customer that has references to it will break integrity).

#### closeAndCommit

    public void closeAndCommit()
                        throws TransactionException

Closes and marks a transaction as committed. Any changes made by this transaction are seen by all transactions created after this method returns.

This method will fail under the following circumstances:

1. There are any rows deleted in this transaction that were deleted by another successfully committed transaction.
2. There were rows added in another committed transaction that would change the result of the search clauses committed by this transaction.

The first check is not too difficult to check for. The second is very difficult however we need it to ensure TRANSACTION_SERIALIZABLE isolation is enforced. We may have to simplify this by throwing a transaction exception if the table has had any changes made to it during this transaction.

This should only be called under an exclusive lock on the connection.

Throws:
  `TransactionException`

#### closeAndRollback

    public void closeAndRollback()

Closes and rolls back a transaction as if the commands the transaction ran never happened. This will not throw a transaction exception.

This should only be called under an exclusive lock on the connection.

#### finalize

    public void finalize()
                  throws java.lang.Throwable

Finalize, we should close the transaction.

Overrides:
  `finalize` in class `java.lang.Object`
Throws:
  `java.lang.Throwable`