Package com.mckoi.database

## Interface MutableTableDataSource

All Superinterfaces:
  `TableDataSource`

All Known Implementing Classes:
  `GTPrivMapDataSource`, `GTSQLTypeInfoDataSource`

    public interface MutableTableDataSource
    extends TableDataSource

A mutable data source that allows for the addition and removal of rows.

Author:
  Tobias Downer

### Method Summary

All Methods Instance Methods Abstract Methods
`void` `addRootLock()` Puts this source under a 'root lock'.
`int` `addRow​(RowData row_data)` Adds a row to the source.
`void` `constraintIntegrityCheck()` Performs all constraint integrity checks and actions to any modifications based on any changes that happened to the table since that last call to this method.
`void` `dispose()` Disposes this table data source.
`void` `flushIndexChanges()` Flushes all changes made on this MutableTableDataSource to the backing index scheme (IndexSet).
`com.mckoi.database.MasterTableJournal` `getJournal()` Returns a journal that details the changes to this data source since it was created.
`void` `removeRootLock()` Removes a root lock from this source.
`void` `removeRow​(int row_index)` Completely removes a row from the source.
`int` `updateRow​(int row_index, RowData row_data)` Updates a row in the source.

### Methods inherited from interface com.mckoi.database.TableDataSource

`getCellContents, getColumnScheme, getDataTableDef, getRowCount, getSystem, rowEnumeration`

### Method Detail

#### addRow

    int addRow​(RowData row_data)

Adds a row to the source. This will add a permanent record into the the underlying data structure. It will also update the indexing schemes as appropriate, and also add the row into the set returned by the 'rowEnumeration' iterator.

It returns a row index that is used to reference this data in future queries. Throws an exception if the row additional was not possible because of IO reasons.

#### removeRow

    void removeRow​(int row_index)

Completely removes a row from the source. This will permanently remove the record from the underlying data structure. It also updates the indexing schemes and removes the row index from the set returned by the 'rowEnumeration' iterator.

Throws an exception if the row index does not reference a valid row within the context of this data source.

#### updateRow

    int updateRow​(int row_index,
                  RowData row_data)

Updates a row in the source. This will make a permanent change to the underlying data structure. It will update the indexing schemes as appropriate, and also add the row into the set returned by the 'rowEnumeration' iterator.

It returns a row index for the new updated records. Throws an exception if the row update was not possible because of IO reasons or the row index not being a valid reference to a record in this data source.

#### flushIndexChanges

    void flushIndexChanges()

Flushes all changes made on this MutableTableDataSource to the backing index scheme (IndexSet). This is used during the commit phase of this objects lifetime. The transaction control mechanism has found that there are no clashes and now we need to commit the current table view to the conglomerate. Because this object may not update index information immediately, we call this to flush all the changes to the table to the backing index set.

When this method returns, the backing IndexSet of this view will be completely up to date.

#### constraintIntegrityCheck

    void constraintIntegrityCheck()

Performs all constraint integrity checks and actions to any modifications based on any changes that happened to the table since that last call to this method. It is important that is called after any call to 'addRow', 'removeRow' or 'updateRow'.

Any constraints that are marked as INITIALLY_IMMEDIATE are checked when this is called, otherwise the constraint is checked at commit time.

Any referential actions are performed when this method is called. If a referential action causes a modification to another table, this method is recursively called on the table modified.

If a referential integrity constraint is violated and a referential action is unable to maintain the integrity of the database, any changes made to the table are reverted.

#### getJournal

    com.mckoi.database.MasterTableJournal getJournal()

Returns a journal that details the changes to this data source since it was created. This method may return a 'null' object to denote that no logging is being done. If this returns a MasterTableJournal, then all 'addRow' and 'removeRow' method calls and their relative order will be described in this journal.

#### dispose

    void dispose()

Disposes this table data source. After this method is called, most use of this object is undefined, except for the 'getCellContent' and 'compareCellContent' methods which are valid provided the source is under a root lock.

#### addRootLock

    void addRootLock()

Puts this source under a 'root lock'. A root lock means the root row structure of this object must not change. A root lock is obtained on a table when a ResultSet keeps hold of an object outside the life of the transaction that created the table. It is important that the order of the rows stays constant (committed deleted rows are not really deleted and reused, etc) while a table holds at least 1 root lock.

#### removeRootLock

    void removeRootLock()

Removes a root lock from this source.