Package com.mckoi.database

## Class DataTable

- java.lang.Object
- - com.mckoi.database.Table
  - - com.mckoi.database.AbstractDataTable
    - - com.mckoi.database.DefaultDataTable
      - - com.mckoi.database.DataTable

All Implemented Interfaces:
  `RootTable`, `TableDataSource`

    public final class DataTable
    extends DefaultDataTable

DataTable is a wrapper for a MutableTableDataSource that fits into the query hierarchy level. A DataTable represents a table within a transaction. Adding, removing rows to a DataTable will change the contents only with the context of the transaction the table was created in.

Author:
  Tobias Downer

### Field Summary

### Fields inherited from class com.mckoi.database.DefaultDataTable

`row_count`

### Fields inherited from class com.mckoi.database.Table

`DEBUG_QUERY`

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `add​(RowData row_data)` Adds a given 'RowData' object to the table.
`void` `add​(RowData[] row_data_arr)` Adds an array of 'RowData' objects to the table.
`void` `addDataTableListener​(com.mckoi.database.DataTableListener listener)` Adds a DataTableListener to the DataTable objects at the root of this table tree hierarchy.
`protected void` `blankSelectableSchemes​(int type)` Overwritten from DefaultDataTable to do nothing.
`RowData` `createRowDataObject​(QueryContext context)` Generates an empty RowData object for 'addRow'ing into the Table.
`DebugLogger` `Debug()` Convenience - used to log debug messages.
`ReferenceTable` `declareAs​(TableName new_name)` We can declare a DataTable as a new type.
`int` `delete​(Table table)`
`int` `delete​(Table table, int limit)` This is the public method for removing a given result set from this table.
`int` `findFieldName​(Variable v)` Given a fully qualified variable field name, ie.
`TObject` `getCellContents​(int column, int row)` Returns an object that represents the information in the given cell in the table.
`int` `getColumnCount()` Returns the number of columns in the table.
`DataTableDef` `getDataTableDef()` Returns the DataTableDef object for this table.
`Variable` `getResolvedVariable​(int column)` Returns a fully qualified Variable object that represents the name of the column at the given index.
`protected SelectableScheme` `getRootColumnScheme​(int column)` Returns the SelectableScheme for the given column.
`int` `getRowCount()` Returns the current row count.
`java.lang.String` `getSchema()` Returns the schema that this table is within.
`boolean` `hasRootsLocked()` Returns true if the table has its row roots locked (via the lockRoot(int) method.
`void` `lockRoot​(int lock_key)` Locks the root table(s) of this table so that it is impossible to overwrite the underlying rows that may appear in this table.
`void` `removeDataTableListener​(com.mckoi.database.DataTableListener listener)` Removes a DataTableListener from the DataTable objects at the root of this table tree hierarchy.
`RowEnumeration` `rowEnumeration()` Returns an Enumeration of the rows in this table.
`void` `unlockRoot​(int lock_key)` Unlocks the root tables so that the underlying rows may once again be used if they are not locked and have been removed.
`int` `update​(QueryContext context, Table table, Assignment[] assign_list, int limit)` Updates the table by applying the assignment operations over each row that is found in the input 'table' set.

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

`blankSelectableSchemes, clearColumnScheme, getDatabase`

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

`getTableName, toString, typeEquals`

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

`all, allColumnMatchesValue, any, columnContainsCell, columnContainsValue, columnMatchesValue, columnMerge, compareCells, distinct, distinct, dumpTo, emptySelect, exhaustiveSelect, fastFindFieldName, getColumnDefAt, getColumnScheme, getFirstCellContent, getFirstCellContent, getLastCellContent, getLastCellContent, getSingleCellContent, getSingleCellContent, getSystem, getTableAccessState, getTTypeForColumn, getTTypeForColumn, join, orderByColumn, orderByColumn, orderByColumn, orderByColumns, orderedRowList, outside, printGraph, rangeSelect, selectAll, selectAll, selectFirst, selectLast, selectRange, selectRest, simpleJoin, simpleSelect, singleRowSelect, toMap, union`

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

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

### Method Detail

#### Debug

    public final DebugLogger Debug()

Convenience - used to log debug messages.

Overrides:
  `Debug` in class `Table`

#### blankSelectableSchemes

    protected void blankSelectableSchemes​(int type)

Overwritten from DefaultDataTable to do nothing. All selectable schemes are handled within the DataTableManager now.

Overrides:
  `blankSelectableSchemes` in class `DefaultDataTable`

#### getRootColumnScheme

    protected SelectableScheme getRootColumnScheme​(int column)

Returns the SelectableScheme for the given column. (Overridden from DefaultDataTable). If the schemes are not in memory then they are loaded now. This will synchronize over the 'table_manager' which will effectively block this table at the lowest layer until the indices are loaded into memory.

Overrides:
  `getRootColumnScheme` in class `DefaultDataTable`

#### declareAs

    public ReferenceTable declareAs​(TableName new_name)

We can declare a DataTable as a new type. This means, instead of referencing a column as 'Customer.CustomerID' we can change the 'Customer' part to anything we wish such as 'C1'.

#### createRowDataObject

    public final RowData createRowDataObject​(QueryContext context)

Generates an empty RowData object for 'addRow'ing into the Table. We must first call this method to retrieve a blank RowData object, fill it in with the required information, and then call 'addRow'

#### getRowCount

    public int getRowCount()

Returns the current row count. This queries the DataTableManager for the real value.

Specified by:
  `getRowCount` in interface `TableDataSource`
Overrides:
  `getRowCount` in class `DefaultDataTable`

#### add

    public final void add​(RowData row_data)
                   throws DatabaseException

Adds a given 'RowData' object to the table. This should be used for any rows added to the table. The order that rows are added into a table is not important.

This method performs some checking of the cells in the table. It first checks that all columns declared as 'not null' have a value that is not null. It then checks that a the added row will not cause any duplicates in a column declared as unique.

It then uses the low level io manager to store the data.

SYNCHRONIZATION ISSUE: We are assuming this is running in a synchronized environment that is unable to add or alter rows in this object within the lifetime of this method.

Throws:
  `DatabaseException`

#### add

    public final void add​(RowData[] row_data_arr)
                   throws DatabaseException

Adds an array of 'RowData' objects to the table. This should be used for adding a group of rows to the table. The order that rows are added into a table is not important.

This method performs some checking of the cells in the table. It first checks that all columns declared as 'not null' have a value that is not null. It then checks that a the added row will not cause any duplicates in a column declared as unique.

It then uses the low level io manager to store the data.

SYNCHRONIZATION ISSUE: We are assuming this is running in a synchronized environment that is unable to add or alter rows in this object within the lifetime of this method.

Throws:
  `DatabaseException`

#### delete

    public int delete​(Table table,
                      int limit)
               throws DatabaseException

This is the public method for removing a given result set from this table. Given a Table object, this will remove from this table any row that are in the given table. The given Table must have this object as its distant ancestor. If it does not then it will throw an exception. Examples: table.delete(table) -- delete the entire table. table.delete(table.select( < some condition > )); It returns the number of rows that were deleted.

INTERNAL NOTE: The 'table' parameter may be the result of joins. This may cause the same row in this table to be referenced more than once. We must make sure that we delete any given row only once by using the 'distinct' function.

'limit' dictates how many rows will be deleted. If 'limit' is less than 0 then this indicates there is no limit. Keep in mind that rows are picked out from top to bottom in the 'table' object. Normally the input table will be the result of an un-ordered 'where' clause so using a limit does not permit deletes in a deterministic manner.

ASSUMPTION: There are no duplicate rows in the input set.

Throws:
  `DatabaseException`

#### delete

    public int delete​(Table table)
               throws DatabaseException

Throws:
  `DatabaseException`

#### update

    public final int update​(QueryContext context,
                            Table table,
                            Assignment[] assign_list,
                            int limit)
                     throws DatabaseException

Updates the table by applying the assignment operations over each row that is found in the input 'table' set. The input table must be a direct child of this DataTable.

This operation assumes that there is a WRITE lock on this table. A WRITE lock means no other thread may access this table while the operation is being performed. (However, a result set may still be downloading from this table).

'limit' dictates how many rows will be updated. If 'limit' is less than 0 then this indicates there is no limit. Keep in mind that rows are picked out from top to bottom in the 'table' object. Normally the input table will be the result of an un-ordered 'where' clause so using a limit does not permit updates in a deterministic manner.

Returns the number of rows updated in this table.

NOTE: We assume there are no duplicate rows to the root set from the given 'table'.

Throws:
  `DatabaseException`

#### getDataTableDef

    public DataTableDef getDataTableDef()

Returns the DataTableDef object for this table. This object describes how the table is made up.

NOTE: Do not keep references to this object. The DataTableDef is invalidated when a table is closed.

Specified by:
  `getDataTableDef` in interface `TableDataSource`
Specified by:
  `getDataTableDef` in class `Table`

#### getSchema

    public java.lang.String getSchema()

Returns the schema that this table is within.

#### addDataTableListener

    public void addDataTableListener​(com.mckoi.database.DataTableListener listener)

Adds a DataTableListener to the DataTable objects at the root of this table tree hierarchy. If this table represents the join of a number of tables then the DataTableListener is added to all the DataTable objects at the root.

A DataTableListener is notified of all modifications to the raw entries of the table. This listener can be used for detecting changes in VIEWs, for triggers or for caching of common queries.

#### removeDataTableListener

    public void removeDataTableListener​(com.mckoi.database.DataTableListener listener)

Removes a DataTableListener from the DataTable objects at the root of this table tree hierarchy. If this table represents the join of a number of tables, then the DataTableListener is removed from all the DataTable objects at the root.

#### getCellContents

    public TObject getCellContents​(int column,
                                   int row)

Returns an object that represents the information in the given cell in the table. This can be used to obtain information about the given table cells.

Specified by:
  `getCellContents` in interface `TableDataSource`
Specified by:
  `getCellContents` in class `Table`

#### rowEnumeration

    public RowEnumeration rowEnumeration()

Returns an Enumeration of the rows in this table. Each call to 'nextRowIndex' returns the next valid row index in the table.

Specified by:
  `rowEnumeration` in interface `TableDataSource`
Specified by:
  `rowEnumeration` in class `Table`

#### lockRoot

    public void lockRoot​(int lock_key)

Locks the root table(s) of this table so that it is impossible to overwrite the underlying rows that may appear in this table. This is used when cells in the table need to be accessed 'outside' the lock. So we may have late access to cells in the table. 'lock_key' is a given key that will also unlock the root table(s).

NOTE: This is nothing to do with the 'LockingMechanism' object.

Specified by:
  `lockRoot` in class `Table`

#### unlockRoot

    public void unlockRoot​(int lock_key)

Unlocks the root tables so that the underlying rows may once again be used if they are not locked and have been removed. This should be called some time after the rows have been locked.

Specified by:
  `unlockRoot` in class `Table`

#### hasRootsLocked

    public boolean hasRootsLocked()

Returns true if the table has its row roots locked (via the lockRoot(int) method.

Specified by:
  `hasRootsLocked` in class `Table`

#### getColumnCount

    public int getColumnCount()

Description copied from class: `DefaultDataTable`
Returns the number of columns in the table.

Overrides:
  `getColumnCount` in class `DefaultDataTable`

#### getResolvedVariable

    public Variable getResolvedVariable​(int column)

Description copied from class: `DefaultDataTable`
Returns a fully qualified Variable object that represents the name of the column at the given index. For example, new Variable(new TableName("APP", "CUSTOMER"), "ID")

Overrides:
  `getResolvedVariable` in class `DefaultDataTable`

#### findFieldName

    public int findFieldName​(Variable v)

Description copied from class: `DefaultDataTable`
Given a fully qualified variable field name, ie. 'APP.CUSTOMER.CUSTOMERID' this will return the column number the field is at. Returns -1 if the field does not exist in the table.

Overrides:
  `findFieldName` in class `DefaultDataTable`