com.healthmarketscience.jackcess

Interface Table

All Superinterfaces:

Iterable<Row>, TableDefinition

All Known Implementing Classes:

TableDefinitionImpl, TableImpl

public interface Table
extends Iterable<Row>, TableDefinition

A single database table. A Table instance is retrieved from a Database instance. The Table instance provides access to the table metadata as well as the table data. There are basic data operations on the Table interface (i.e. iterator() addRow(java.lang.Object...), updateRow(com.healthmarketscience.jackcess.Row) and deleteRow(com.healthmarketscience.jackcess.Row)), but for advanced search and data manipulation a Cursor instance should be used. New Tables can be created using a TableBuilder. The Joiner utility can be used to traverse table relationships (e.g. find rows in another table based on a foreign-key relationship).

A Table instance is not thread-safe (see Database for more thread-safety details).

Author:

James Ahlborn

Usage:

General: This class is general use.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Table.ColumnOrder enum which controls the ordering of the columns in a table.

Method Summary

Modifier and Type	Method and Description
Object[]	addRow(Object... row) Adds a single row to this table and writes it to disk.
<M extends Map<String,Object>> M	addRowFromMap(M row) Calls asRow(java.util.Map<java.lang.String, ?>) on the given row map and passes the result to addRow(java.lang.Object...).
List<? extends Object[]>	addRows(List<? extends Object[]> rows) Add multiple rows to this table, only writing to disk after all rows have been written, and every time a data page is filled.
<M extends Map<String,Object>> List<M>	addRowsFromMaps(List<M> rows) Calls asRow(java.util.Map<java.lang.String, ?>) on the given row maps and passes the results to addRows(java.util.List<? extends java.lang.Object[]>).
Object[]	asRow(Map<String,?> rowMap) Converts a map of columnName -> columnValue to an array of row values appropriate for a call to addRow(Object...).
Object[]	asUpdateRow(Map<String,?> rowMap) Converts a map of columnName -> columnValue to an array of row values appropriate for a call to Cursor.updateCurrentRow(Object...).
Row	deleteRow(Row row) Delete the given row.
Column	getColumn(String name)
int	getColumnCount()
List<? extends Column>	getColumns()
LocalDateTime	getCreatedDate()
Database	getDatabase()
Cursor	getDefaultCursor()
ErrorHandler	getErrorHandler() Gets the currently configured ErrorHandler (always non-null).
Index	getForeignKeyIndex(Table otherTable)
Index	getIndex(String name)
List<? extends Index>	getIndexes()
String	getName()
Row	getNextRow()
Index	getPrimaryKeyIndex()
PropertyMap	getProperties()
int	getRowCount()
LocalDateTime	getUpdatedDate() Note: jackcess does not automatically update the modified date of a Table.
boolean	isAllowAutoNumberInsert() Gets the currently configured auto number insert policy.
boolean	isHidden() Whether or not this table has been marked as hidden.
boolean	isSystem() Whether or not this table is a system (internal) table.
Iterator<Row>	iterator() Calls reset() on this table and returns a modifiable Iterator which will iterate through all the rows of this table.
default OleBlob.Builder	newBlob() Convenience method for constructing a new OleBlob.Builder.
CursorBuilder	newCursor() Convenience method for constructing a new CursorBuilder for this Table.
void	reset() After calling this method, getNextRow() will return the first row in the table, see Cursor.reset() (uses the default cursor).
void	setAllowAutoNumberInsert(Boolean allowAutoNumInsert) Sets the new auto number insert policy for the Table.
void	setErrorHandler(ErrorHandler newErrorHandler) Sets a new ErrorHandler.
default Stream<Row>	stream()
Row	updateRow(Row row) Update the given row.

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

getName

String getName()

Specified by:

getName in interface TableDefinition

Returns:

The name of the table

Usage:

General: This method is general use.

isHidden

boolean isHidden()

Whether or not this table has been marked as hidden.

Specified by:

isHidden in interface TableDefinition

Usage:

General: This method is general use.

isSystem

boolean isSystem()

Whether or not this table is a system (internal) table.

Specified by:

isSystem in interface TableDefinition

Usage:

General: This method is general use.

getColumnCount

int getColumnCount()

Specified by:

getColumnCount in interface TableDefinition

Usage:

General: This method is general use.

getDatabase

Database getDatabase()

Specified by:

getDatabase in interface TableDefinition

Usage:

General: This method is general use.

getErrorHandler

ErrorHandler getErrorHandler()

Gets the currently configured ErrorHandler (always non-null). This will be used to handle all errors unless overridden at the Cursor level.

Usage:

Intermediate: This method requires moderate API knowledge.

setErrorHandler

void setErrorHandler(ErrorHandler newErrorHandler)

Sets a new ErrorHandler. If null, resets to using the ErrorHandler configured at the Database level.

Usage:

Intermediate: This method requires moderate API knowledge.

isAllowAutoNumberInsert

boolean isAllowAutoNumberInsert()

Gets the currently configured auto number insert policy.

See Also:

Database.isAllowAutoNumberInsert()

Usage:

Intermediate: This method requires moderate API knowledge.

setAllowAutoNumberInsert

void setAllowAutoNumberInsert(Boolean allowAutoNumInsert)

Sets the new auto number insert policy for the Table. If null, resets to using the policy configured at the Database level.

Usage:

Intermediate: This method requires moderate API knowledge.

getColumns

List<? extends Column> getColumns()

Specified by:

getColumns in interface TableDefinition

Returns:

All of the columns in this table (unmodifiable List)

Usage:

General: This method is general use.

getColumn

Column getColumn(String name)

Specified by:

getColumn in interface TableDefinition

Returns:

the column with the given name

Usage:

General: This method is general use.

getProperties

PropertyMap getProperties()
                   throws IOException

Specified by:

getProperties in interface TableDefinition

Returns:

the properties for this table

Throws:

IOException

Usage:

General: This method is general use.

getCreatedDate

LocalDateTime getCreatedDate()
                      throws IOException

Specified by:

getCreatedDate in interface TableDefinition

Returns:

the created date for this table if available

Throws:

IOException

Usage:

General: This method is general use.

getUpdatedDate

LocalDateTime getUpdatedDate()
                      throws IOException

Note: jackcess does not automatically update the modified date of a Table.

Specified by:

getUpdatedDate in interface TableDefinition

Returns:

the last updated date for this table if available

Throws:

IOException

Usage:

General: This method is general use.

getIndexes

List<? extends Index> getIndexes()

Specified by:

getIndexes in interface TableDefinition

Returns:

All of the Indexes on this table (unmodifiable List)

Usage:

Intermediate: This method requires moderate API knowledge.

getIndex

Index getIndex(String name)

Specified by:

getIndex in interface TableDefinition

Returns:

the index with the given name

Throws:

IllegalArgumentException - if there is no index with the given name

Usage:

Intermediate: This method requires moderate API knowledge.

getPrimaryKeyIndex

Index getPrimaryKeyIndex()

Specified by:

getPrimaryKeyIndex in interface TableDefinition

Returns:

the primary key index for this table

Throws:

IllegalArgumentException - if there is no primary key index on this table

Usage:

Intermediate: This method requires moderate API knowledge.

getForeignKeyIndex

Index getForeignKeyIndex(Table otherTable)

Specified by:

getForeignKeyIndex in interface TableDefinition

Returns:

the foreign key index joining this table to the given other table

Throws:

IllegalArgumentException - if there is no relationship between this table and the given table

Usage:

Intermediate: This method requires moderate API knowledge.

asRow

Object[] asRow(Map<String,?> rowMap)

Converts a map of columnName -> columnValue to an array of row values appropriate for a call to addRow(Object...).

Usage:

General: This method is general use.

asUpdateRow

Object[] asUpdateRow(Map<String,?> rowMap)

Converts a map of columnName -> columnValue to an array of row values appropriate for a call to Cursor.updateCurrentRow(Object...).

Usage:

General: This method is general use.

getRowCount

int getRowCount()

Usage:

General: This method is general use.

addRow

Object[] addRow(Object... row)
         throws IOException

Adds a single row to this table and writes it to disk. The values are expected to be given in the order that the Columns are listed by the getColumns() method. This is by default the storage order of the Columns in the database, however this order can be influenced by setting the ColumnOrder via Database.setColumnOrder(com.healthmarketscience.jackcess.Table.ColumnOrder) prior to opening the Table. The asRow(java.util.Map<java.lang.String, ?>) method can be used to easily convert a row Map into the appropriate row array for this Table.

Note, if this table has an auto-number column, the value generated will be put back into the given row array (assuming the given row array is at least as long as the number of Columns in this Table).

Parameters:

row - row values for a single row. the given row array will be modified if this table contains an auto-number column, otherwise it will not be modified.

Returns:

the given row values if long enough, otherwise a new array. the returned array will contain any autonumbers generated

Throws:

IOException

Usage:

General: This method is general use.

addRowFromMap

<M extends Map<String,Object>> M addRowFromMap(M row)
                                        throws IOException

Calls asRow(java.util.Map<java.lang.String, ?>) on the given row map and passes the result to addRow(java.lang.Object...).

Note, if this table has an auto-number column, the value generated will be put back into the given row map.

Returns:

the given row map, which will contain any autonumbers generated

Throws:

IOException

Usage:

General: This method is general use.

addRows

List<? extends Object[]> addRows(List<? extends Object[]> rows)
                          throws IOException

Add multiple rows to this table, only writing to disk after all rows have been written, and every time a data page is filled. This is much more efficient than calling addRow(java.lang.Object...) multiple times.

Note, if this table has an auto-number column, the values written will be put back into the given row arrays (assuming the given row array is at least as long as the number of Columns in this Table).

Most exceptions thrown from this method will be wrapped with a BatchUpdateException which gives useful information in the case of a partially successful write.

Parameters:

rows - List of Object[] row values. the rows will be modified if this table contains an auto-number column, otherwise they will not be modified.

Returns:

the given row values list (unless row values were to small), with appropriately sized row values (the ones passed in if long enough). the returned arrays will contain any autonumbers generated

Throws:

IOException

See Also:

for more details on row arrays

Usage:

General: This method is general use.

addRowsFromMaps

<M extends Map<String,Object>> List<M> addRowsFromMaps(List<M> rows)
                                                throws IOException

Calls asRow(java.util.Map<java.lang.String, ?>) on the given row maps and passes the results to addRows(java.util.List<? extends java.lang.Object[]>).

Note, if this table has an auto-number column, the values generated will be put back into the appropriate row maps.

Most exceptions thrown from this method will be wrapped with a BatchUpdateException which gives useful information in the case of a partially successful write.

Returns:

the given row map list, where the row maps will contain any autonumbers generated

Throws:

IOException

Usage:

General: This method is general use.

updateRow

Row updateRow(Row row)
       throws IOException

Update the given row. Provided Row must have previously been returned from this Table.

Returns:

the given row, updated with the current row values

Throws:

IllegalStateException - if the given row is not valid, or deleted.

IOException

deleteRow

Row deleteRow(Row row)
       throws IOException

Delete the given row. Provided Row must have previously been returned from this Table.

Returns:

the given row

Throws:

IllegalStateException - if the given row is not valid

IOException

iterator

Iterator<Row> iterator()

Calls reset() on this table and returns a modifiable Iterator which will iterate through all the rows of this table. Use of the Iterator follows the same restrictions as a call to getNextRow().

For more advanced iteration, use the default cursor directly.

Specified by:

iterator in interface Iterable<Row>

Throws:

RuntimeIOException - if an IOException is thrown by one of the operations, the actual exception will be contained within

Usage:

General: This method is general use.

stream

default Stream<Row> stream()

Returns:

a Stream using the default Iterator.

reset

void reset()

After calling this method, getNextRow() will return the first row in the table, see Cursor.reset() (uses the default cursor).

Usage:

General: This method is general use.

getNextRow

Row getNextRow()
        throws IOException

Returns:

The next row in this table (Column name -> Column value) (uses the default cursor)

Throws:

IOException

Usage:

General: This method is general use.

getDefaultCursor

Cursor getDefaultCursor()

Returns:

a simple Cursor, initialized on demand and held by this table. This cursor backs the row traversal methods available on the Table interface. For advanced Table traversal and manipulation, use the Cursor directly.

newCursor

CursorBuilder newCursor()

Convenience method for constructing a new CursorBuilder for this Table.

newBlob

default OleBlob.Builder newBlob()

Convenience method for constructing a new OleBlob.Builder.