com.healthmarketscience.jackcess
Class Table

java.lang.Object
  com.healthmarketscience.jackcess.Table

All Implemented Interfaces:

java.lang.Iterable<java.util.Map<java.lang.String,java.lang.Object>>

public class Table
extends java.lang.Object
implements java.lang.Iterable<java.util.Map<java.lang.String,java.lang.Object>>

A single database table

Is not thread-safe.

Nested Class Summary

static class	Table.ColumnOrder enum which controls the ordering of the columns in a table.
class	Table.RowState Maintains the state of reading a row of data.

Field Summary

static byte	TYPE_SYSTEM Table type code for system tables
static byte	TYPE_USER Table type code for user tables

Constructor Summary

protected

Table(Database database, java.nio.ByteBuffer tableBuffer, int pageNumber, java.lang.String name, int flags, boolean useBigIndex)

Method Summary

static int	addDataPageRow(java.nio.ByteBuffer dataPage, int rowSize, JetFormat format, int rowFlags) Updates free space and row info for a new row of the given size in the given data page.
void	addRow(java.lang.Object... row) Add a single row to this table and write it to disk Note, if this table has an auto-number column, the value written will be put back into the given row array.
void	addRows(java.util.List<? extends java.lang.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.
java.lang.Object[]	asRow(java.util.Map<java.lang.String,?> rowMap) Converts a map of columnName -> columnValue to an array of row values appropriate for a call to addRow(Object...).
java.lang.Object[]	asUpdateRow(java.util.Map<java.lang.String,?> rowMap) Converts a map of columnName -> columnValue to an array of row values appropriate for a call to updateCurrentRow(Object...).
static short	cleanRowStart(short rowStart)
Table.RowState	createRowState()
void	deleteCurrentRow() Delete the current row (retrieved by a call to getNextRow()).
void	deleteRow(Table.RowState rowState, RowId rowId) Delete the row on which the given rowState is currently positioned.
java.lang.String	display()
java.lang.String	display(long limit)
boolean	doUseBigIndex()
static short	findRowEnd(java.nio.ByteBuffer buffer, int rowNum, JetFormat format)
static short	findRowStart(java.nio.ByteBuffer buffer, int rowNum, JetFormat format)
int	getApproximateOwnedPageCount() Returns the approximate number of database pages owned by this table and all related indexes (this number does not take into account pages used for large OLE/MEMO fields).
static java.util.List<Column>	getAutoNumberColumns(java.util.Collection<Column> columns)
Column	getColumn(java.lang.String name)
int	getColumnCount()
java.util.List<Column>	getColumns()
Database	getDatabase()
ErrorHandler	getErrorHandler() Gets the currently configured ErrorHandler (always non-null).
Index	getForeignKeyIndex(Table otherTable)
JetFormat	getFormat()
Index	getIndex(java.lang.String name)
java.util.List<Index>	getIndexes()
protected TempPageHolder	getLongValueBuffer()
int	getMaxColumnCount()
java.lang.String	getName()
java.util.Map<java.lang.String,java.lang.Object>	getNextRow()
java.util.Map<java.lang.String,java.lang.Object>	getNextRow(java.util.Collection<java.lang.String> columnNames)
protected UsageMap.PageCursor	getOwnedPagesCursor()
PageChannel	getPageChannel()
Index	getPrimaryKeyIndex()
PropertyMap	getProperties()
protected PropertyMaps	getPropertyMaps()
java.util.Map<java.lang.String,java.lang.Object>	getRow(Table.RowState rowState, RowId rowId, java.util.Collection<java.lang.String> columnNames) Reads some columns from the given row.
int	getRowCount()
static int	getRowEndOffset(int rowNum, JetFormat format)
static int	getRowSpaceUsage(int rowSize, JetFormat format)
static int	getRowStartOffset(int rowNum, JetFormat format)
java.lang.Object	getRowValue(Table.RowState rowState, RowId rowId, Column column) Reads a single column from the given row.
int	getTableDefPageNumber()
static boolean	isDeletedRow(short rowStart)
boolean	isHidden() Whether or not this table has been marked as hidden.
static boolean	isOverflowRow(short rowStart)
java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>>	iterator() Calls reset on this table and returns a modifiable Iterator which will iterate through all the rows of this table.
java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>>	iterator(java.util.Collection<java.lang.String> columnNames) Calls reset on this table and returns a modifiable Iterator which will iterate through all the rows of this table, returning only the given columns.
static java.nio.ByteBuffer	positionAtRowData(Table.RowState rowState, RowId rowId) Sets the position and limit in a new buffer using the given rowState according to the given row number and row end, following overflow row pointers as necessary.
static java.nio.ByteBuffer	positionAtRowHeader(Table.RowState rowState, RowId rowId) Sets a new buffer to the correct row header page using the given rowState according to the given rowId.
void	reset() After calling this method, getNextRow will return the first row in the table, see Cursor.reset().
static boolean	rowFitsOnDataPage(int rowLength, java.nio.ByteBuffer dataPage, JetFormat format) Returns true if a row of the given size will fit on the given data page, false otherwise.
void	setErrorHandler(ErrorHandler newErrorHandler) Sets a new ErrorHandler.
java.lang.String	toString()
void	updateCurrentRow(java.lang.Object... row) Updates the current row to the new values.
void	updateRow(Table.RowState rowState, RowId rowId, java.lang.Object... row) Update the row on which the given rowState is currently positioned.
protected static void	writeTableDefinition(com.healthmarketscience.jackcess.TableCreator creator) Writes a new table defined by the given TableCreator to the database.

Methods inherited from class java.lang.Object

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

Field Detail

TYPE_SYSTEM

public static final byte TYPE_SYSTEM

Table type code for system tables

See Also:

Constant Field Values

TYPE_USER

public static final byte TYPE_USER

Table type code for user tables

See Also:

Constant Field Values

Constructor Detail

Table

protected Table(Database database,
                java.nio.ByteBuffer tableBuffer,
                int pageNumber,
                java.lang.String name,
                int flags,
                boolean useBigIndex)
         throws java.io.IOException

Parameters:

database - database which owns this table

tableBuffer - Buffer to read the table with

pageNumber - Page number of the table definition

name - Table name

useBigIndex - whether or not "big index support" should be enabled for the table

Throws:

java.io.IOException

Method Detail

getName

public java.lang.String getName()

Returns:

The name of the table

isHidden

public boolean isHidden()

Whether or not this table has been marked as hidden.

doUseBigIndex

public boolean doUseBigIndex()

getMaxColumnCount

public int getMaxColumnCount()

getColumnCount

public int getColumnCount()

getDatabase

public Database getDatabase()

getFormat

public JetFormat getFormat()

getPageChannel

public PageChannel getPageChannel()

getErrorHandler

public ErrorHandler getErrorHandler()

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

setErrorHandler

public void setErrorHandler(ErrorHandler newErrorHandler)

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

getTableDefPageNumber

public int getTableDefPageNumber()

createRowState

public Table.RowState createRowState()

getOwnedPagesCursor

protected UsageMap.PageCursor getOwnedPagesCursor()

getApproximateOwnedPageCount

public int getApproximateOwnedPageCount()

Returns the approximate number of database pages owned by this table and all related indexes (this number does not take into account pages used for large OLE/MEMO fields).

To calculate the approximate number of bytes owned by a table: int approxTableBytes = (table.getApproximateOwnedPageCount() * table.getFormat().PAGE_SIZE);

getLongValueBuffer

protected TempPageHolder getLongValueBuffer()

getColumns

public java.util.List<Column> getColumns()

Returns:

All of the columns in this table (unmodifiable List)

getColumn

public Column getColumn(java.lang.String name)

Returns:

the column with the given name

getProperties

public PropertyMap getProperties()
                          throws java.io.IOException

Returns:

the properties for this table

Throws:

java.io.IOException

getPropertyMaps

protected PropertyMaps getPropertyMaps()
                                throws java.io.IOException

Returns:

all PropertyMaps for this table (and columns)

Throws:

java.io.IOException

getIndexes

public java.util.List<Index> getIndexes()

Returns:

All of the Indexes on this table (unmodifiable List)

getIndex

public Index getIndex(java.lang.String name)

Returns:

the index with the given name

Throws:

java.lang.IllegalArgumentException - if there is no index with the given name

getPrimaryKeyIndex

public Index getPrimaryKeyIndex()

Returns:

the primary key index for this table

Throws:

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

getForeignKeyIndex

public Index getForeignKeyIndex(Table otherTable)

Returns:

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

Throws:

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

reset

public void reset()

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

deleteCurrentRow

public void deleteCurrentRow()
                      throws java.io.IOException

Delete the current row (retrieved by a call to getNextRow()).

Throws:

java.io.IOException

deleteRow

public void deleteRow(Table.RowState rowState,
                      RowId rowId)
               throws java.io.IOException

Delete the row on which the given rowState is currently positioned.

Note, this method is not generally meant to be used directly. You should use the deleteCurrentRow() method or use the Cursor class, which allows for more complex table interactions.

Throws:

java.io.IOException

getNextRow

public java.util.Map<java.lang.String,java.lang.Object> getNextRow()
                                                            throws java.io.IOException

Returns:

The next row in this table (Column name -> Column value)

Throws:

java.io.IOException

getNextRow

public java.util.Map<java.lang.String,java.lang.Object> getNextRow(java.util.Collection<java.lang.String> columnNames)
                                                            throws java.io.IOException

Parameters:

columnNames - Only column names in this collection will be returned

Returns:

The next row in this table (Column name -> Column value)

Throws:

java.io.IOException

getRowValue

public java.lang.Object getRowValue(Table.RowState rowState,
                                    RowId rowId,
                                    Column column)
                             throws java.io.IOException

Reads a single column from the given row.

Note, this method is not generally meant to be used directly. Instead use the Cursor class, which allows for more complex table interactions, e.g. Cursor.getCurrentRowValue(com.healthmarketscience.jackcess.Column).

Throws:

java.io.IOException

getRow

public java.util.Map<java.lang.String,java.lang.Object> getRow(Table.RowState rowState,
                                                               RowId rowId,
                                                               java.util.Collection<java.lang.String> columnNames)
                                                        throws java.io.IOException

Reads some columns from the given row.

Parameters:

columnNames - Only column names in this collection will be returned

Throws:

java.io.IOException

positionAtRowHeader

public static java.nio.ByteBuffer positionAtRowHeader(Table.RowState rowState,
                                                      RowId rowId)
                                               throws java.io.IOException

Sets a new buffer to the correct row header page using the given rowState according to the given rowId. Deleted state is determined, but overflow row pointers are not followed.

Returns:

a ByteBuffer of the relevant page, or null if row was invalid

Throws:

java.io.IOException

positionAtRowData

public static java.nio.ByteBuffer positionAtRowData(Table.RowState rowState,
                                                    RowId rowId)
                                             throws java.io.IOException

Sets the position and limit in a new buffer using the given rowState according to the given row number and row end, following overflow row pointers as necessary.

Returns:

a ByteBuffer narrowed to the actual row data, or null if row was invalid or deleted

Throws:

java.io.IOException

iterator

public java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>> 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.

Specified by:

iterator in interface java.lang.Iterable<java.util.Map<java.lang.String,java.lang.Object>>

Throws:

java.lang.IllegalStateException - if an IOException is thrown by one of the operations, the actual exception will be contained within

iterator

public java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>> iterator(java.util.Collection<java.lang.String> columnNames)

Calls reset on this table and returns a modifiable Iterator which will iterate through all the rows of this table, returning only the given columns. Use of the Iterator follows the same restrictions as a call to getNextRow.

Throws:

java.lang.IllegalStateException - if an IOException is thrown by one of the operations, the actual exception will be contained within

writeTableDefinition

protected static void writeTableDefinition(com.healthmarketscience.jackcess.TableCreator creator)
                                    throws java.io.IOException

Writes a new table defined by the given TableCreator to the database.

Throws:

java.io.IOException

asRow

public java.lang.Object[] asRow(java.util.Map<java.lang.String,?> rowMap)

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

asUpdateRow

public java.lang.Object[] asUpdateRow(java.util.Map<java.lang.String,?> rowMap)

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

addRow

public void addRow(java.lang.Object... row)
            throws java.io.IOException

Add a single row to this table and write it to disk

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

Parameters:

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

Throws:

java.io.IOException

addRows

public void addRows(java.util.List<? extends java.lang.Object[]> rows)
             throws java.io.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 multiple times.

Note, if this table has an auto-number column, the values written will be put back into the given row arrays.

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.

Throws:

java.io.IOException

updateCurrentRow

public void updateCurrentRow(java.lang.Object... row)
                      throws java.io.IOException

Updates the current row to the new values.

Note, if this table has an auto-number column(s), the existing value(s) will be maintained, unchanged.

Parameters:

row - new row values for the current row.

Throws:

java.io.IOException

updateRow

public void updateRow(Table.RowState rowState,
                      RowId rowId,
                      java.lang.Object... row)
               throws java.io.IOException

Update the row on which the given rowState is currently positioned.

Note, this method is not generally meant to be used directly. You should use the updateCurrentRow(java.lang.Object...) method or use the Cursor class, which allows for more complex table interactions, e.g. Cursor.setCurrentRowValue(com.healthmarketscience.jackcess.Column, java.lang.Object) and Cursor.updateCurrentRow(java.lang.Object...).

Throws:

java.io.IOException

getRowCount

public int getRowCount()

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

display

public java.lang.String display()
                         throws java.io.IOException

Returns:

A simple String representation of the entire table in tab-delimited format

Throws:

java.io.IOException

display

public java.lang.String display(long limit)
                         throws java.io.IOException

Parameters:

limit - Maximum number of rows to display

Returns:

A simple String representation of the entire table in tab-delimited format

Throws:

java.io.IOException

addDataPageRow

public static int addDataPageRow(java.nio.ByteBuffer dataPage,
                                 int rowSize,
                                 JetFormat format,
                                 int rowFlags)

Updates free space and row info for a new row of the given size in the given data page. Positions the page for writing the row data.

Returns:

the row number of the new row

isDeletedRow

public static boolean isDeletedRow(short rowStart)

isOverflowRow

public static boolean isOverflowRow(short rowStart)

cleanRowStart

public static short cleanRowStart(short rowStart)

findRowStart

public static short findRowStart(java.nio.ByteBuffer buffer,
                                 int rowNum,
                                 JetFormat format)

getRowStartOffset

public static int getRowStartOffset(int rowNum,
                                    JetFormat format)

findRowEnd

public static short findRowEnd(java.nio.ByteBuffer buffer,
                               int rowNum,
                               JetFormat format)

getRowEndOffset

public static int getRowEndOffset(int rowNum,
                                  JetFormat format)

getRowSpaceUsage

public static int getRowSpaceUsage(int rowSize,
                                   JetFormat format)

getAutoNumberColumns

public static java.util.List<Column> getAutoNumberColumns(java.util.Collection<Column> columns)

Returns:

the "AutoNumber" columns in the given collection of columns.

rowFitsOnDataPage

public static boolean rowFitsOnDataPage(int rowLength,
                                        java.nio.ByteBuffer dataPage,
                                        JetFormat format)
                                 throws java.io.IOException

Returns true if a row of the given size will fit on the given data page, false otherwise.

Throws:

java.io.IOException