com.healthmarketscience.jackcess
Class IndexCursor

java.lang.Object
  com.healthmarketscience.jackcess.Cursor
      com.healthmarketscience.jackcess.IndexCursor

All Implemented Interfaces:

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

public class IndexCursor
extends Cursor

Cursor backed by an index with extended traversal options.

Nested Class Summary

Nested classes/interfaces inherited from class com.healthmarketscience.jackcess.Cursor

Cursor.BaseIterator, Cursor.DirHandler, Cursor.Id, Cursor.Position, Cursor.Savepoint

Field Summary

Fields inherited from class com.healthmarketscience.jackcess.Cursor

_columnMatcher, _curPos, _prevPos, MOVE_FORWARD, MOVE_REVERSE

Method Summary

static IndexCursor	createCursor(Table table, Index index) Creates an indexed cursor for the given table.
static IndexCursor	createCursor(Table table, 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(Table table, Index index, java.lang.Object[] startRow, java.lang.Object[] endRow) Creates an indexed cursor for the given table, narrowed to the given range.
boolean	currentRowMatchesEntry(java.lang.Object... entryValues) Returns true if the current row matches the given index entries.
java.lang.Iterable<java.util.Map<java.lang.String,java.lang.Object>>	entryIterable(java.util.Collection<java.lang.String> columnNames, java.lang.Object... entryValues) Returns an Iterable whose iterator() method returns the result of a call to entryIterator(Collection,Object...)
java.lang.Iterable<java.util.Map<java.lang.String,java.lang.Object>>	entryIterable(java.lang.Object... entryValues) Returns an Iterable whose iterator() method returns the result of a call to entryIterator(Object...)
java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>>	entryIterator(java.util.Collection<java.lang.String> columnNames, java.lang.Object... entryValues) Returns a modifiable Iterator which will iterate through all the rows of this table which match the given index entries, returning only the given columns.
java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>>	entryIterator(java.lang.Object... entryValues) Returns a modifiable Iterator which will iterate through all the rows of this table which match the given index entries.
protected Cursor.Position	findAnotherPosition(Table.RowState rowState, Cursor.Position curPos, boolean moveForward) Finds the next non-deleted row after the given row (as defined by this cursor) and returns the id of the row, where "next" may be backwards if moveForward is false.
void	findClosestRowByEntry(java.lang.Object... entryValues) Moves to the first row (as defined by the cursor) where the index entries are >= the given values.
boolean	findFirstRowByEntry(java.lang.Object... entryValues) Moves to the first row (as defined by the cursor) where the index entries match the given values.
protected boolean	findFirstRowByEntryImpl(java.lang.Object[] rowValues, boolean requireMatch) Moves to the first row (as defined by the cursor) where the index entries match the given values.
protected boolean	findNextRowImpl(Column columnPattern, java.lang.Object valuePattern) Moves to the next row (as defined by the cursor) where the given column has the given value.
protected boolean	findNextRowImpl(java.util.Map<java.lang.String,?> rowPattern) Moves to the next row (as defined by the cursor) where the given columns have the given values.
boolean	findRowByEntry(java.lang.Object... entryValues) Deprecated. renamed to findFirstRowByEntry(Object...) to be more clear
protected ColumnMatcher	getDefaultColumnMatcher() Returns the default ColumnMatcher for this Cursor.
protected com.healthmarketscience.jackcess.IndexCursor.IndexDirHandler	getDirHandler(boolean moveForward) Returns the DirHandler for the given movement direction.
Index	getIndex()
protected boolean	isUpToDate() Returns true if this cursor is up-to-date with respect to the relevant table and related table objects, false otherwise.
protected void	reset(boolean moveForward) Resets this cursor for traversing the given direction.
protected void	restorePositionImpl(Cursor.Position curPos, Cursor.Position prevPos) Restores a current and previous position for the cursor.

Methods inherited from class com.healthmarketscience.jackcess.Cursor

afterLast, beforeFirst, columnMatchIterable, columnMatchIterable, columnMatchIterator, columnMatchIterator, createCursor, createIndexCursor, createIndexCursor, createIndexCursor, currentRowMatches, currentRowMatches, deleteCurrentRow, findFirstRow, findFirstRow, findNextRow, findNextRow, findRow, findRow, findRow, findRow, findValue, findValue, getColumnMatcher, getCurrentRow, getCurrentRow, getCurrentRowValue, getErrorHandler, getFirstPosition, getFormat, getId, getLastPosition, getNextRow, getNextRow, getPageChannel, getPreviousRow, getPreviousRow, getSavepoint, getTable, isAfterLast, isBeforeFirst, isCurrentRowDeleted, iterable, iterator, iterator, moveNextRows, movePreviousRows, moveToNextRow, moveToPreviousRow, reset, restorePosition, restorePosition, restoreSavepoint, reverseIterable, reverseIterable, rowMatchIterable, rowMatchIterable, rowMatchIterator, rowMatchIterator, setColumnMatcher, setCurrentRowValue, setErrorHandler, toString, updateCurrentRow

Methods inherited from class java.lang.Object

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

Method Detail

createCursor

public static IndexCursor createCursor(Table table,
                                       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:

table - the table over which this cursor will traverse

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

Throws:

java.io.IOException

createCursor

public static IndexCursor createCursor(Table table,
                                       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:

table - the table over which this cursor will traverse

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(Table table,
                                       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:

table - the table over which this cursor will traverse

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

getIndex

public Index getIndex()

findRowByEntry

@Deprecated
public boolean findRowByEntry(java.lang.Object... entryValues)
                       throws java.io.IOException

Deprecated. renamed to findFirstRowByEntry(Object...) to be more clear

Throws:

java.io.IOException

findFirstRowByEntry

public boolean findFirstRowByEntry(java.lang.Object... entryValues)
                            throws java.io.IOException

Moves to the first row (as defined by the cursor) where the index entries match the given values. If a match is not found (or an exception is thrown), the cursor is restored to its previous state.

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

Parameters:

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

Returns:

true if a valid row was found with the given values, false if no row was found

Throws:

java.io.IOException

findClosestRowByEntry

public void findClosestRowByEntry(java.lang.Object... entryValues)
                           throws java.io.IOException

Moves to the first row (as defined by the cursor) where the index entries are >= the given values. If a an exception is thrown, the cursor is restored to its previous state.

Parameters:

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

Throws:

java.io.IOException

currentRowMatchesEntry

public boolean currentRowMatchesEntry(java.lang.Object... entryValues)
                               throws java.io.IOException

Returns true if the current row matches the given index entries.

Parameters:

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

Throws:

java.io.IOException

entryIterator

public java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>> entryIterator(java.lang.Object... entryValues)

Returns a modifiable Iterator which will iterate through all the rows of this table which match the given index entries.

Throws:

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

entryIterator

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

Returns a modifiable Iterator which will iterate through all the rows of this table which match the given index entries, returning only the given columns.

Throws:

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

entryIterable

public java.lang.Iterable<java.util.Map<java.lang.String,java.lang.Object>> entryIterable(java.lang.Object... entryValues)

Returns an Iterable whose iterator() method returns the result of a call to entryIterator(Object...)

Throws:

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

entryIterable

public java.lang.Iterable<java.util.Map<java.lang.String,java.lang.Object>> entryIterable(java.util.Collection<java.lang.String> columnNames,
                                                                                          java.lang.Object... entryValues)

Returns an Iterable whose iterator() method returns the result of a call to entryIterator(Collection,Object...)

Throws:

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

getDirHandler

protected com.healthmarketscience.jackcess.IndexCursor.IndexDirHandler getDirHandler(boolean moveForward)

Description copied from class: Cursor

Returns the DirHandler for the given movement direction.

Specified by:

getDirHandler in class Cursor

isUpToDate

protected boolean isUpToDate()

Description copied from class: Cursor

Returns true if this cursor is up-to-date with respect to the relevant table and related table objects, false otherwise.

Overrides:

isUpToDate in class Cursor

reset

protected void reset(boolean moveForward)

Description copied from class: Cursor

Resets this cursor for traversing the given direction.

Overrides:

reset in class Cursor

restorePositionImpl

protected void restorePositionImpl(Cursor.Position curPos,
                                   Cursor.Position prevPos)
                            throws java.io.IOException

Description copied from class: Cursor

Restores a current and previous position for the cursor.

Overrides:

restorePositionImpl in class Cursor

Throws:

java.io.IOException

findNextRowImpl

protected boolean findNextRowImpl(Column columnPattern,
                                  java.lang.Object valuePattern)
                           throws java.io.IOException

Description copied from class: Cursor

Moves to the next row (as defined by the cursor) where the given column has the given value. Caller manages save/restore on failure.

Default implementation scans the table from beginning to end.

Overrides:

findNextRowImpl in class Cursor

Parameters:

columnPattern - column from the table for this cursor which is being matched by the valuePattern

valuePattern - value which is equal to the corresponding value in the matched row

Returns:

true if a valid row was found with the given value, false if no row was found

Throws:

java.io.IOException

findFirstRowByEntryImpl

protected boolean findFirstRowByEntryImpl(java.lang.Object[] rowValues,
                                          boolean requireMatch)
                                   throws java.io.IOException

Moves to the first row (as defined by the cursor) where the index entries match the given values. Caller manages save/restore on failure.

Parameters:

rowValues - the column values built from the index column values

requireMatch - whether or not an exact match is found

Returns:

true if a valid row was found with the given values, false if no row was found

Throws:

java.io.IOException

findNextRowImpl

protected boolean findNextRowImpl(java.util.Map<java.lang.String,?> rowPattern)
                           throws java.io.IOException

Description copied from class: Cursor

Moves to the next row (as defined by the cursor) where the given columns have the given values. Caller manages save/restore on failure.

Default implementation scans the table from beginning to end.

Overrides:

findNextRowImpl in class Cursor

Parameters:

rowPattern - column names and values which must be equal to the corresponding values in the matched row

Returns:

true if a valid row was found with the given values, false if no row was found

Throws:

java.io.IOException

findAnotherPosition

protected Cursor.Position findAnotherPosition(Table.RowState rowState,
                                              Cursor.Position curPos,
                                              boolean moveForward)
                                       throws java.io.IOException

Description copied from class: Cursor

Finds the next non-deleted row after the given row (as defined by this cursor) and returns the id of the row, where "next" may be backwards if moveForward is false. If there are no more rows, the returned rowId should equal the value returned by Cursor.getLastPosition() if moving forward and Cursor.getFirstPosition() if moving backward.

Specified by:

findAnotherPosition in class Cursor

Throws:

java.io.IOException

getDefaultColumnMatcher

protected ColumnMatcher getDefaultColumnMatcher()

Description copied from class: Cursor

Returns the default ColumnMatcher for this Cursor.

Overrides:

getDefaultColumnMatcher in class Cursor