com.healthmarketscience.jackcess

Class CursorBuilder

java.lang.Object

com.healthmarketscience.jackcess.CursorBuilder

public class CursorBuilder
extends java.lang.Object

Builder style class for constructing a Cursor. By default, a cursor is created at the beginning of the table, and any start/end rows are inclusive.

Simple example traversal:

   for(Row row : table.newCursor().toCursor()) {
     // ... process each row ...
   }
 

Simple example search:

   Row row = CursorBuilder.findRow(table, Collections.singletonMap(col, "foo"));
 

Field Summary

Fields

Modifier and Type	Field and Description
private boolean	_beforeFirst whether to start at beginning or end of cursor
private ColumnMatcher	_columnMatcher ColumnMatcher to be used when matching column values
private java.lang.Object[]	_endRow optional end row for an index cursor
private boolean	_endRowInclusive whether or not end row for an index cursor is inclusive
private IndexImpl	_index optional index to use in traversal
private Cursor.Savepoint	_savepoint optional save point to restore to the cursor
private java.lang.Object[]	_startRow optional start row for an index cursor
private boolean	_startRowInclusive whether or not start row for an index cursor is inclusive
private TableImpl	_table the table which the cursor will traverse

Constructor Summary

Constructors

Constructor and Description
CursorBuilder(Table table)

Method Summary

Modifier and Type	Method and Description
CursorBuilder	afterLast() Sets the cursor so that it will start at the end (unless a savepoint is given).
CursorBuilder	beforeFirst() Sets the cursor so that it will start at the beginning (unless a savepoint is given).
static IndexCursor	createCursor(Index index) Creates an indexed cursor for the given table.
static IndexCursor	createCursor(Index index, java.lang.Object[] startRow, boolean startInclusive, java.lang.Object[] endRow, boolean endInclusive) Creates an indexed cursor for the given table, narrowed to the given range.
static IndexCursor	createCursor(Index index, java.lang.Object[] startRow, java.lang.Object[] endRow) Creates an indexed cursor for the given table, narrowed to the given range.
static Cursor	createCursor(Table table) Creates a normal, un-indexed cursor for the given table.
static IndexCursor	createPrimaryKeyCursor(Table table) Creates an indexed cursor for the primary key cursor of the given table.
static Row	findRow(Index index, java.util.Map<java.lang.String,?> rowPattern) Convenience method for finding a specific row in an indexed table which matches a given row "pattern".
static Row	findRow(Table table, java.util.Map<java.lang.String,?> rowPattern) Convenience method for finding a specific row in a table which matches a given row "pattern".
static Row	findRowByEntry(Index index, java.lang.Object... entryValues) Convenience method for finding a specific row (as defined by the cursor) where the index entries match the given values.
static Row	findRowByPrimaryKey(Table table, java.lang.Object... entryValues) Convenience method for finding a specific row by the primary key of the table.
static java.lang.Object	findValue(Index index, Column column, Column columnPattern, java.lang.Object valuePattern) Convenience method for finding a specific row in a table which matches a given row "pattern".
static java.lang.Object	findValue(Table table, Column column, Column columnPattern, java.lang.Object valuePattern) Convenience method for finding a specific row in a table which matches a given row "pattern".
CursorBuilder	restoreSavepoint(Cursor.Savepoint savepoint) Sets a savepoint to restore for the initial position of the cursor.
CursorBuilder	setColumnMatcher(ColumnMatcher columnMatcher) Sets the ColumnMatcher to use for matching row patterns.
CursorBuilder	setEndEntry(java.lang.Object... endEntry) Sets the ending row for a range based index cursor to the given entry (where the given values correspond to the index's columns).
CursorBuilder	setEndRow(java.lang.Object... endRow) Sets the ending row for a range based index cursor.
CursorBuilder	setEndRowInclusive(boolean inclusive) Sets whether the ending row for a range based index cursor is inclusive or exclusive.
CursorBuilder	setIndex(Index index) Sets an index to use for the cursor.
CursorBuilder	setIndexByColumnNames(java.lang.String... columnNames) Sets an index to use for the cursor by searching the table for an index with exactly the given columns.
CursorBuilder	setIndexByColumns(Column... columns) Sets an index to use for the cursor by searching the table for an index with exactly the given columns.
private CursorBuilder	setIndexByColumns(java.util.List<java.lang.String> searchColumns) Searches for an index with the given column names.
CursorBuilder	setIndexByName(java.lang.String indexName) Sets an index to use for the cursor by searching the table for an index with the given name.
CursorBuilder	setSpecificEntry(java.lang.Object... specificEntry) Sets the starting and ending row for a range based index cursor to the given entry (where the given values correspond to the index's columns).
CursorBuilder	setSpecificRow(java.lang.Object... specificRow) Sets the starting and ending row for a range based index cursor.
CursorBuilder	setStartEntry(java.lang.Object... startEntry) Sets the starting row for a range based index cursor to the given entry (where the given values correspond to the index's columns).
CursorBuilder	setStartRow(java.lang.Object... startRow) Sets the starting row for a range based index cursor.
CursorBuilder	setStartRowInclusive(boolean inclusive) Sets whether the starting row for a range based index cursor is inclusive or exclusive.
Cursor	toCursor() Returns a new cursor for the table, constructed to the given specifications.
IndexCursor	toIndexCursor() Returns a new index cursor for the table, constructed to the given specifications.

Methods inherited from class java.lang.Object

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

Field Detail

_table

private final TableImpl _table

the table which the cursor will traverse

_index

private IndexImpl _index

optional index to use in traversal

_startRow

private java.lang.Object[] _startRow

optional start row for an index cursor

_startRowInclusive

private boolean _startRowInclusive

whether or not start row for an index cursor is inclusive

_endRow

private java.lang.Object[] _endRow

optional end row for an index cursor

_endRowInclusive

private boolean _endRowInclusive

whether or not end row for an index cursor is inclusive

_beforeFirst

private boolean _beforeFirst

whether to start at beginning or end of cursor

_savepoint

private Cursor.Savepoint _savepoint

optional save point to restore to the cursor

_columnMatcher

private ColumnMatcher _columnMatcher

ColumnMatcher to be used when matching column values

Constructor Detail

CursorBuilder

public CursorBuilder(Table table)

Method Detail

beforeFirst

public CursorBuilder beforeFirst()

Sets the cursor so that it will start at the beginning (unless a savepoint is given).

afterLast

public CursorBuilder afterLast()

Sets the cursor so that it will start at the end (unless a savepoint is given).

restoreSavepoint

public CursorBuilder restoreSavepoint(Cursor.Savepoint savepoint)

Sets a savepoint to restore for the initial position of the cursor.

setIndex

public CursorBuilder setIndex(Index index)

Sets an index to use for the cursor.

setIndexByName

public CursorBuilder setIndexByName(java.lang.String indexName)

Sets an index to use for the cursor by searching the table for an index with the given name.

Throws:

java.lang.IllegalArgumentException - if no index can be found on the table with the given name

setIndexByColumnNames

public CursorBuilder setIndexByColumnNames(java.lang.String... columnNames)

Sets an index to use for the cursor by searching the table for an index with exactly the given columns.

Throws:

java.lang.IllegalArgumentException - if no index can be found on the table with the given columns

setIndexByColumns

public CursorBuilder setIndexByColumns(Column... columns)

Sets an index to use for the cursor by searching the table for an index with exactly the given columns.

Throws:

java.lang.IllegalArgumentException - if no index can be found on the table with the given columns

setIndexByColumns

private CursorBuilder setIndexByColumns(java.util.List<java.lang.String> searchColumns)

Searches for an index with the given column names.

setSpecificRow

public CursorBuilder setSpecificRow(java.lang.Object... specificRow)

Sets the starting and ending row for a range based index cursor.

A valid index must be specified before calling this method.

setSpecificEntry

public CursorBuilder setSpecificEntry(java.lang.Object... specificEntry)

Sets the starting and ending row for a range based index cursor to the given entry (where the given values correspond to the index's columns).

A valid index must be specified before calling this method.

setStartRow

public CursorBuilder setStartRow(java.lang.Object... startRow)

Sets the starting row for a range based index cursor.

A valid index must be specified before calling this method.

setStartEntry

public CursorBuilder setStartEntry(java.lang.Object... startEntry)

Sets the starting row for a range based index cursor to the given entry (where the given values correspond to the index's columns).

A valid index must be specified before calling this method.

setStartRowInclusive

public CursorBuilder setStartRowInclusive(boolean inclusive)

Sets whether the starting row for a range based index cursor is inclusive or exclusive.

setEndRow

public CursorBuilder setEndRow(java.lang.Object... endRow)

Sets the ending row for a range based index cursor.

A valid index must be specified before calling this method.

setEndEntry

public CursorBuilder setEndEntry(java.lang.Object... endEntry)

Sets the ending row for a range based index cursor to the given entry (where the given values correspond to the index's columns).

A valid index must be specified before calling this method.

setEndRowInclusive

public CursorBuilder setEndRowInclusive(boolean inclusive)

Sets whether the ending row for a range based index cursor is inclusive or exclusive.

setColumnMatcher

public CursorBuilder setColumnMatcher(ColumnMatcher columnMatcher)

Sets the ColumnMatcher to use for matching row patterns.

toCursor

public Cursor toCursor()
                throws java.io.IOException

Returns a new cursor for the table, constructed to the given specifications.

Throws:

java.io.IOException

toIndexCursor

public IndexCursor toIndexCursor()
                          throws java.io.IOException

Returns a new index cursor for the table, constructed to the given specifications.

Throws:

java.io.IOException

createCursor

public static Cursor createCursor(Table table)
                           throws java.io.IOException

Creates a normal, un-indexed cursor for the given table.

Parameters:

table - the table over which this cursor will traverse

Throws:

java.io.IOException

createCursor

public static IndexCursor createCursor(Index index)
                                throws java.io.IOException

Creates an indexed cursor for the given table.

Note, index based table traversal may not include all rows, as certain types of indexes do not include all entries (namely, some indexes ignore null entries, see Index.shouldIgnoreNulls()).

Parameters:

index - index for the table which will define traversal order as well as enhance certain lookups

Throws:

java.io.IOException

createPrimaryKeyCursor

public static IndexCursor createPrimaryKeyCursor(Table table)
                                          throws java.io.IOException

Creates an indexed cursor for the primary key cursor of the given table.

Parameters:

table - the table over which this cursor will traverse

Throws:

java.io.IOException

createCursor

public static IndexCursor createCursor(Index index,
                                       java.lang.Object[] startRow,
                                       java.lang.Object[] endRow)
                                throws java.io.IOException

Creates an indexed cursor for the given table, narrowed to the given range.

Note, index based table traversal may not include all rows, as certain types of indexes do not include all entries (namely, some indexes ignore null entries, see Index.shouldIgnoreNulls()).

Parameters:

index - index for the table which will define traversal order as well as enhance certain lookups

startRow - the first row of data for the cursor (inclusive), or null for the first entry

endRow - the last row of data for the cursor (inclusive), or null for the last entry

Throws:

java.io.IOException

createCursor

public static IndexCursor createCursor(Index index,
                                       java.lang.Object[] startRow,
                                       boolean startInclusive,
                                       java.lang.Object[] endRow,
                                       boolean endInclusive)
                                throws java.io.IOException

Creates an indexed cursor for the given table, narrowed to the given range.

Note, index based table traversal may not include all rows, as certain types of indexes do not include all entries (namely, some indexes ignore null entries, see Index.shouldIgnoreNulls()).

Parameters:

index - index for the table which will define traversal order as well as enhance certain lookups

startRow - the first row of data for the cursor, or null for the first entry

startInclusive - whether or not startRow is inclusive or exclusive

endRow - the last row of data for the cursor, or null for the last entry

endInclusive - whether or not endRow is inclusive or exclusive

Throws:

java.io.IOException

findRow

public static Row findRow(Table table,
                          java.util.Map<java.lang.String,?> rowPattern)
                   throws java.io.IOException

Convenience method for finding a specific row in a table which matches a given row "pattern". See Cursor.findFirstRow(Map) for details on the rowPattern.

Warning, this method always starts searching from the beginning of the Table (you cannot use it to find successive matches).

Parameters:

table - the table to search

rowPattern - pattern to be used to find the row

Returns:

the matching row or null if a match could not be found.

Throws:

java.io.IOException

findRowByEntry

public static Row findRowByEntry(Index index,
                                 java.lang.Object... entryValues)
                          throws java.io.IOException

Convenience method for finding a specific row (as defined by the cursor) where the index entries match the given values. See IndexCursor.findRowByEntry(Object...) for details on the entryValues.

Parameters:

index - the index to search

entryValues - the column values for the index's columns.

Returns:

the matching row or null if a match could not be found.

Throws:

java.io.IOException

findRowByPrimaryKey

public static Row findRowByPrimaryKey(Table table,
                                      java.lang.Object... entryValues)
                               throws java.io.IOException

Convenience method for finding a specific row by the primary key of the table. See IndexCursor.findRowByEntry(Object...) for details on the entryValues.

Parameters:

table - the table to search

entryValues - the column values for the table's primary key columns.

Returns:

the matching row or null if a match could not be found.

Throws:

java.io.IOException

findValue

public static java.lang.Object findValue(Table table,
                                         Column column,
                                         Column columnPattern,
                                         java.lang.Object valuePattern)
                                  throws java.io.IOException

Convenience method for finding a specific row in a table which matches a given row "pattern". See Cursor.findFirstRow(Column,Object) for details on the pattern.

Note, a null result value is ambiguous in that it could imply no match or a matching row with null for the desired value. If distinguishing this situation is important, you will need to use a Cursor directly instead of this convenience method.

Parameters:

table - the table to search

column - column whose value should be returned

columnPattern - column being matched by the valuePattern

valuePattern - value from the columnPattern which will match the desired row

Returns:

the matching row or null if a match could not be found.

Throws:

java.io.IOException

findRow

public static Row findRow(Index index,
                          java.util.Map<java.lang.String,?> rowPattern)
                   throws java.io.IOException

Convenience method for finding a specific row in an indexed table which matches a given row "pattern". See Cursor.findFirstRow(Map) for details on the rowPattern.

Warning, this method always starts searching from the beginning of the Table (you cannot use it to find successive matches).

Parameters:

index - index to assist the search

rowPattern - pattern to be used to find the row

Returns:

the matching row or null if a match could not be found.

Throws:

java.io.IOException

findValue

public static java.lang.Object findValue(Index index,
                                         Column column,
                                         Column columnPattern,
                                         java.lang.Object valuePattern)
                                  throws java.io.IOException

Convenience method for finding a specific row in a table which matches a given row "pattern". See Cursor.findFirstRow(Column,Object) for details on the pattern.

Note, a null result value is ambiguous in that it could imply no match or a matching row with null for the desired value. If distinguishing this situation is important, you will need to use a Cursor directly instead of this convenience method.

Parameters:

index - index to assist the search

column - column whose value should be returned

columnPattern - column being matched by the valuePattern

valuePattern - value from the columnPattern which will match the desired row

Returns:

the matching row or null if a match could not be found.

Throws:

java.io.IOException