com.healthmarketscience.jackcess
Class Cursor

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

All Implemented Interfaces:

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

Direct Known Subclasses:

IndexCursor

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

Manages iteration for a Table. Different cursors provide different methods of traversing a table. Cursors should be fairly robust in the face of table modification during traversal (although depending on how the table is traversed, row updates may or may not be seen). Multiple cursors may traverse the same table simultaneously.

The Cursor provides a variety of static utility methods to construct cursors with given characteristics or easily search for specific values. For even friendlier and more flexible construction, see CursorBuilder.

Is not thread-safe.

Nested Class Summary

protected class	Cursor.BaseIterator Base implementation of iterator for this cursor, modifiable.
protected class	Cursor.DirHandler Handles moving the cursor in a given direction.
static class	Cursor.Id Identifier for a cursor.
static class	Cursor.Position Value object which maintains the current position of the cursor.
static class	Cursor.Savepoint Value object which represents a complete save state of the cursor.

Field Summary

protected ColumnMatcher	_columnMatcher ColumnMatcher to be used when matching column values
protected Cursor.Position	_curPos the current row
protected Cursor.Position	_prevPos the previous row
static boolean	MOVE_FORWARD boolean value indicating forward movement
static boolean	MOVE_REVERSE boolean value indicating reverse movement

Constructor Summary

protected

Cursor(Cursor.Id id, Table table, Cursor.Position firstPos, Cursor.Position lastPos)

Method Summary

void	afterLast() Resets this cursor for reverse traversal (sets cursor to after the last row).
void	beforeFirst() Resets this cursor for forward traversal (sets cursor to before the first row).
java.lang.Iterable<java.util.Map<java.lang.String,java.lang.Object>>	columnMatchIterable(java.util.Collection<java.lang.String> columnNames, Column columnPattern, java.lang.Object valuePattern) Returns an Iterable whose iterator() method returns the result of a call to columnMatchIterator(Collection,Column,Object)
java.lang.Iterable<java.util.Map<java.lang.String,java.lang.Object>>	columnMatchIterable(Column columnPattern, java.lang.Object valuePattern) Returns an Iterable whose iterator() method returns the result of a call to columnMatchIterable(Column,Object)
java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>>	columnMatchIterator(java.util.Collection<java.lang.String> columnNames, Column columnPattern, java.lang.Object valuePattern) Calls beforeFirst on this table and returns a modifiable Iterator which will iterate through all the rows of this table which match the given column pattern, returning only the given columns.
java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>>	columnMatchIterator(Column columnPattern, java.lang.Object valuePattern) Calls beforeFirst on this cursor and returns a modifiable Iterator which will iterate through all the rows of this table which match the given column pattern.
static Cursor	createCursor(Table table) Creates a normal, un-indexed cursor for the given table.
static Cursor	createIndexCursor(Table table, Index index) Creates an indexed cursor for the given table.
static Cursor	createIndexCursor(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 Cursor	createIndexCursor(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	currentRowMatches(Column columnPattern, java.lang.Object valuePattern) Returns true if the current row matches the given pattern.
boolean	currentRowMatches(java.util.Map<java.lang.String,?> rowPattern) Returns true if the current row matches the given pattern.
void	deleteCurrentRow() Delete the current row.
protected abstract 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.
boolean	findFirstRow(Column columnPattern, java.lang.Object valuePattern) Moves to the first row (as defined by the cursor) where the given column has the given value.
boolean	findFirstRow(java.util.Map<java.lang.String,?> rowPattern) Moves to the first row (as defined by the cursor) where the given columns have the given values.
boolean	findNextRow(Column columnPattern, java.lang.Object valuePattern) Moves to the next row (as defined by the cursor) where the given column has the given value.
boolean	findNextRow(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.
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	findRow(Column columnPattern, java.lang.Object valuePattern) Deprecated. renamed to findFirstRow(Column,Object) to be more clear
boolean	findRow(java.util.Map<java.lang.String,?> rowPattern) Deprecated. renamed to findFirstRow(Map) to be more clear
static java.util.Map<java.lang.String,java.lang.Object>	findRow(Table table, 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 java.util.Map<java.lang.String,java.lang.Object>	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 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".
static java.lang.Object	findValue(Table table, 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".
ColumnMatcher	getColumnMatcher() Returns the currently configured ColumnMatcher, always non-null.
java.util.Map<java.lang.String,java.lang.Object>	getCurrentRow() Returns the current row in this cursor (Column name -> Column value).
java.util.Map<java.lang.String,java.lang.Object>	getCurrentRow(java.util.Collection<java.lang.String> columnNames) Returns the current row in this cursor (Column name -> Column value).
java.lang.Object	getCurrentRowValue(Column column) Returns the given column from the current row.
protected ColumnMatcher	getDefaultColumnMatcher() Returns the default ColumnMatcher for this Cursor.
protected abstract Cursor.DirHandler	getDirHandler(boolean moveForward) Returns the DirHandler for the given movement direction.
ErrorHandler	getErrorHandler() Gets the currently configured ErrorHandler (always non-null).
protected Cursor.Position	getFirstPosition() Returns the first row id (exclusive) as defined by this cursor.
JetFormat	getFormat()
Cursor.Id	getId()
protected Cursor.Position	getLastPosition() Returns the last row id (exclusive) as defined by this cursor.
java.util.Map<java.lang.String,java.lang.Object>	getNextRow() Moves to the next row in the table and returns it.
java.util.Map<java.lang.String,java.lang.Object>	getNextRow(java.util.Collection<java.lang.String> columnNames) Moves to the next row in the table and returns it.
PageChannel	getPageChannel()
java.util.Map<java.lang.String,java.lang.Object>	getPreviousRow() Moves to the previous row in the table and returns it.
java.util.Map<java.lang.String,java.lang.Object>	getPreviousRow(java.util.Collection<java.lang.String> columnNames) Moves to the previous row in the table and returns it.
Cursor.Savepoint	getSavepoint() Returns the current state of the cursor which can be restored at a future point in time by a call to restoreSavepoint(com.healthmarketscience.jackcess.Cursor.Savepoint).
Table	getTable()
boolean	isAfterLast() Returns true if the cursor is currently positioned after the last row, false otherwise.
boolean	isBeforeFirst() Returns true if the cursor is currently positioned before the first row, false otherwise.
boolean	isCurrentRowDeleted() Returns true if the row at which the cursor is currently positioned is deleted, false otherwise (including invalid rows).
protected boolean	isUpToDate() Returns true if this cursor is up-to-date with respect to the relevant table and related table objects, false otherwise.
java.lang.Iterable<java.util.Map<java.lang.String,java.lang.Object>>	iterable(java.util.Collection<java.lang.String> columnNames) Returns an Iterable whose iterator() method returns the result of a call to iterator(Collection)
java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>>	iterator() Calls beforeFirst on this cursor 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 beforeFirst on this table and returns a modifiable Iterator which will iterate through all the rows of this table, returning only the given columns.
int	moveNextRows(int numRows) Moves forward as many rows as possible up to the given number of rows.
int	movePreviousRows(int numRows) Moves backward as many rows as possible up to the given number of rows.
boolean	moveToNextRow() Moves to the next row as defined by this cursor.
boolean	moveToPreviousRow() Moves to the previous row as defined by this cursor.
void	reset() Resets this cursor for forward traversal.
protected void	reset(boolean moveForward) Resets this cursor for traversing the given direction.
protected void	restorePosition(Cursor.Position curPos) Restores a current position for the cursor (current position becomes previous position).
protected void	restorePosition(Cursor.Position curPos, Cursor.Position prevPos) Restores a current and previous position for the cursor if the given positions are different from the current positions.
protected void	restorePositionImpl(Cursor.Position curPos, Cursor.Position prevPos) Restores a current and previous position for the cursor.
void	restoreSavepoint(Cursor.Savepoint savepoint) Moves the cursor to a savepoint previously returned from getSavepoint().
java.lang.Iterable<java.util.Map<java.lang.String,java.lang.Object>>	reverseIterable() Returns an Iterable whose iterator() method calls afterLast on this cursor and returns a modifiable Iterator which will iterate through all the rows of this table in reverse order.
java.lang.Iterable<java.util.Map<java.lang.String,java.lang.Object>>	reverseIterable(java.util.Collection<java.lang.String> columnNames) Returns an Iterable whose iterator() method calls afterLast on this table and returns a modifiable Iterator which will iterate through all the rows of this table in reverse order, returning only the given columns.
java.lang.Iterable<java.util.Map<java.lang.String,java.lang.Object>>	rowMatchIterable(java.util.Collection<java.lang.String> columnNames, java.util.Map<java.lang.String,?> rowPattern) Returns an Iterable whose iterator() method returns the result of a call to rowMatchIterator(Collection,Map)
java.lang.Iterable<java.util.Map<java.lang.String,java.lang.Object>>	rowMatchIterable(java.util.Map<java.lang.String,?> rowPattern) Returns an Iterable whose iterator() method returns the result of a call to rowMatchIterator(Map)
java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>>	rowMatchIterator(java.util.Collection<java.lang.String> columnNames, java.util.Map<java.lang.String,?> rowPattern) Calls beforeFirst on this table and returns a modifiable Iterator which will iterate through all the rows of this table which match the given row pattern, returning only the given columns.
java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>>	rowMatchIterator(java.util.Map<java.lang.String,?> rowPattern) Calls beforeFirst on this cursor and returns a modifiable Iterator which will iterate through all the rows of this table which match the given row pattern.
void	setColumnMatcher(ColumnMatcher columnMatcher) Sets a new ColumnMatcher.
void	setCurrentRowValue(Column column, java.lang.Object value) Updates a single value in the current row.
void	setErrorHandler(ErrorHandler newErrorHandler) Sets a new ErrorHandler.
java.lang.String	toString()
void	updateCurrentRow(java.lang.Object... row) Update the current row.

Methods inherited from class java.lang.Object

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

Field Detail

MOVE_FORWARD

public static final boolean MOVE_FORWARD

boolean value indicating forward movement

See Also:

Constant Field Values

MOVE_REVERSE

public static final boolean MOVE_REVERSE

boolean value indicating reverse movement

See Also:

Constant Field Values

_prevPos

protected Cursor.Position _prevPos

the previous row

_curPos

protected Cursor.Position _curPos

the current row

_columnMatcher

protected ColumnMatcher _columnMatcher

ColumnMatcher to be used when matching column values

Constructor Detail

Cursor

protected Cursor(Cursor.Id id,
                 Table table,
                 Cursor.Position firstPos,
                 Cursor.Position lastPos)

Method Detail

createCursor

public static Cursor createCursor(Table table)

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

Parameters:

table - the table over which this cursor will traverse

createIndexCursor

public static Cursor createIndexCursor(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

createIndexCursor

public static Cursor createIndexCursor(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

createIndexCursor

public static Cursor createIndexCursor(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

findRow

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

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 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 java.util.Map<java.lang.String,java.lang.Object> findRow(Table table,
                                                                       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 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

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

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

getId

public Cursor.Id getId()

getTable

public Table getTable()

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.

setErrorHandler

public void setErrorHandler(ErrorHandler newErrorHandler)

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

getColumnMatcher

public ColumnMatcher getColumnMatcher()

Returns the currently configured ColumnMatcher, always non-null.

setColumnMatcher

public void setColumnMatcher(ColumnMatcher columnMatcher)

Sets a new ColumnMatcher. If null, resets to using the default matcher, SimpleColumnMatcher.INSTANCE.

getDefaultColumnMatcher

protected ColumnMatcher getDefaultColumnMatcher()

Returns the default ColumnMatcher for this Cursor.

getSavepoint

public Cursor.Savepoint getSavepoint()

Returns the current state of the cursor which can be restored at a future point in time by a call to restoreSavepoint(com.healthmarketscience.jackcess.Cursor.Savepoint).

Savepoints may be used across different cursor instances for the same table, but they must have the same Cursor.Id.

restoreSavepoint

public void restoreSavepoint(Cursor.Savepoint savepoint)
                      throws java.io.IOException

Moves the cursor to a savepoint previously returned from getSavepoint().

Throws:

java.lang.IllegalArgumentException - if the given savepoint does not have a cursorId equal to this cursor's id

java.io.IOException

getFirstPosition

protected Cursor.Position getFirstPosition()

Returns the first row id (exclusive) as defined by this cursor.

getLastPosition

protected Cursor.Position getLastPosition()

Returns the last row id (exclusive) as defined by this cursor.

reset

public void reset()

Resets this cursor for forward traversal. Calls beforeFirst().

beforeFirst

public void beforeFirst()

Resets this cursor for forward traversal (sets cursor to before the first row).

afterLast

public void afterLast()

Resets this cursor for reverse traversal (sets cursor to after the last row).

isBeforeFirst

public boolean isBeforeFirst()
                      throws java.io.IOException

Returns true if the cursor is currently positioned before the first row, false otherwise.

Throws:

java.io.IOException

isAfterLast

public boolean isAfterLast()
                    throws java.io.IOException

Returns true if the cursor is currently positioned after the last row, false otherwise.

Throws:

java.io.IOException

isCurrentRowDeleted

public boolean isCurrentRowDeleted()
                            throws java.io.IOException

Returns true if the row at which the cursor is currently positioned is deleted, false otherwise (including invalid rows).

Throws:

java.io.IOException

reset

protected void reset(boolean moveForward)

Resets this cursor for traversing the given direction.

reverseIterable

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

Returns an Iterable whose iterator() method calls afterLast on this cursor and returns a modifiable Iterator which will iterate through all the rows of this table in reverse order. Use of the Iterator follows the same restrictions as a call to getPreviousRow.

Throws:

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

reverseIterable

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

Returns an Iterable whose iterator() method calls afterLast on this table and returns a modifiable Iterator which will iterate through all the rows of this table in reverse order, returning only the given columns. Use of the Iterator follows the same restrictions as a call to getPreviousRow.

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()

Calls beforeFirst on this cursor 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

iterable

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

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

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 beforeFirst 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

columnMatchIterable

public java.lang.Iterable<java.util.Map<java.lang.String,java.lang.Object>> columnMatchIterable(Column columnPattern,
                                                                                                java.lang.Object valuePattern)

Returns an Iterable whose iterator() method returns the result of a call to columnMatchIterable(Column,Object)

Throws:

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

columnMatchIterator

public java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>> columnMatchIterator(Column columnPattern,
                                                                                                java.lang.Object valuePattern)

Calls beforeFirst on this cursor and returns a modifiable Iterator which will iterate through all the rows of this table which match the given column pattern. Use of the Iterator follows the same restrictions as a call to getNextRow. See findFirstRow(Column,Object) for details on the columnPattern.

Throws:

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

columnMatchIterable

public java.lang.Iterable<java.util.Map<java.lang.String,java.lang.Object>> columnMatchIterable(java.util.Collection<java.lang.String> columnNames,
                                                                                                Column columnPattern,
                                                                                                java.lang.Object valuePattern)

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

Throws:

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

columnMatchIterator

public java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>> columnMatchIterator(java.util.Collection<java.lang.String> columnNames,
                                                                                                Column columnPattern,
                                                                                                java.lang.Object valuePattern)

Calls beforeFirst on this table and returns a modifiable Iterator which will iterate through all the rows of this table which match the given column pattern, returning only the given columns. Use of the Iterator follows the same restrictions as a call to getNextRow. See findFirstRow(Column,Object) for details on the columnPattern.

Throws:

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

rowMatchIterable

public java.lang.Iterable<java.util.Map<java.lang.String,java.lang.Object>> rowMatchIterable(java.util.Map<java.lang.String,?> rowPattern)

Returns an Iterable whose iterator() method returns the result of a call to rowMatchIterator(Map)

Throws:

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

rowMatchIterator

public java.util.Iterator<java.util.Map<java.lang.String,java.lang.Object>> rowMatchIterator(java.util.Map<java.lang.String,?> rowPattern)

Calls beforeFirst on this cursor and returns a modifiable Iterator which will iterate through all the rows of this table which match the given row pattern. Use of the Iterator follows the same restrictions as a call to getNextRow. See findFirstRow(Map) for details on the rowPattern.

Throws:

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

rowMatchIterable

public java.lang.Iterable<java.util.Map<java.lang.String,java.lang.Object>> rowMatchIterable(java.util.Collection<java.lang.String> columnNames,
                                                                                             java.util.Map<java.lang.String,?> rowPattern)

Returns an Iterable whose iterator() method returns the result of a call to rowMatchIterator(Collection,Map)

Throws:

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

rowMatchIterator

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

Calls beforeFirst on this table and returns a modifiable Iterator which will iterate through all the rows of this table which match the given row pattern, returning only the given columns. Use of the Iterator follows the same restrictions as a call to getNextRow. See findFirstRow(Map) for details on the rowPattern.

Throws:

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

deleteCurrentRow

public void deleteCurrentRow()
                      throws java.io.IOException

Delete the current row.

Throws:

java.lang.IllegalStateException - if the current row is not valid (at beginning or end of table), or already deleted.

java.io.IOException

updateCurrentRow

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

Update the current row.

Throws:

java.lang.IllegalStateException - if the current row is not valid (at beginning or end of table), or deleted.

java.io.IOException

getNextRow

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

Moves to the next row in the table and returns it.

Returns:

The next row in this table (Column name -> Column value), or null if no next row is found

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

Moves to the next row in the table and returns it.

Parameters:

columnNames - Only column names in this collection will be returned

Returns:

The next row in this table (Column name -> Column value), or null if no next row is found

Throws:

java.io.IOException

getPreviousRow

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

Moves to the previous row in the table and returns it.

Returns:

The previous row in this table (Column name -> Column value), or null if no previous row is found

Throws:

java.io.IOException

getPreviousRow

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

Moves to the previous row in the table and returns it.

Parameters:

columnNames - Only column names in this collection will be returned

Returns:

The previous row in this table (Column name -> Column value), or null if no previous row is found

Throws:

java.io.IOException

moveToNextRow

public boolean moveToNextRow()
                      throws java.io.IOException

Moves to the next row as defined by this cursor.

Returns:

true if a valid next row was found, false otherwise

Throws:

java.io.IOException

moveToPreviousRow

public boolean moveToPreviousRow()
                          throws java.io.IOException

Moves to the previous row as defined by this cursor.

Returns:

true if a valid previous row was found, false otherwise

Throws:

java.io.IOException

restorePosition

protected void restorePosition(Cursor.Position curPos)
                        throws java.io.IOException

Restores a current position for the cursor (current position becomes previous position).

Throws:

java.io.IOException

restorePosition

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

Restores a current and previous position for the cursor if the given positions are different from the current positions.

Throws:

java.io.IOException

restorePositionImpl

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

Restores a current and previous position for the cursor.

Throws:

java.io.IOException

findRow

@Deprecated
public boolean findRow(Column columnPattern,
                                  java.lang.Object valuePattern)
                throws java.io.IOException

Deprecated. renamed to findFirstRow(Column,Object) to be more clear

Throws:

java.io.IOException

findFirstRow

public boolean findFirstRow(Column columnPattern,
                            java.lang.Object valuePattern)
                     throws java.io.IOException

Moves to the first row (as defined by the cursor) where the given column has the given value. This may be more efficient on some cursors than others. 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:

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

findNextRow

public boolean findNextRow(Column columnPattern,
                           java.lang.Object valuePattern)
                    throws java.io.IOException

Moves to the next row (as defined by the cursor) where the given column has the given value. This may be more efficient on some cursors than others. If a match is not found (or an exception is thrown), the cursor is restored to its previous state.

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

findRow

@Deprecated
public boolean findRow(java.util.Map<java.lang.String,?> rowPattern)
                throws java.io.IOException

Deprecated. renamed to findFirstRow(Map) to be more clear

Throws:

java.io.IOException

findFirstRow

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

Moves to the first row (as defined by the cursor) where the given columns have the given values. This may be more efficient on some cursors than others. 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:

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

findNextRow

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

Moves to the next row (as defined by the cursor) where the given columns have the given values. This may be more efficient on some cursors than others. If a match is not found (or an exception is thrown), the cursor is restored to its previous state.

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

currentRowMatches

public boolean currentRowMatches(Column columnPattern,
                                 java.lang.Object valuePattern)
                          throws java.io.IOException

Returns true if the current row matches the given pattern.

Parameters:

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

valuePattern - value which is tested for equality with the corresponding value in the current row

Throws:

java.io.IOException

currentRowMatches

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

Returns true if the current row matches the given pattern.

Parameters:

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

Throws:

java.io.IOException

findNextRowImpl

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

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.

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

findNextRowImpl

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

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.

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

moveNextRows

public int moveNextRows(int numRows)
                 throws java.io.IOException

Moves forward as many rows as possible up to the given number of rows.

Returns:

the number of rows moved.

Throws:

java.io.IOException

movePreviousRows

public int movePreviousRows(int numRows)
                     throws java.io.IOException

Moves backward as many rows as possible up to the given number of rows.

Returns:

the number of rows moved.

Throws:

java.io.IOException

getCurrentRow

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

Returns the current row in this cursor (Column name -> Column value).

Throws:

java.io.IOException

getCurrentRow

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

Returns the current row in this cursor (Column name -> Column value).

Parameters:

columnNames - Only column names in this collection will be returned

Throws:

java.io.IOException

getCurrentRowValue

public java.lang.Object getCurrentRowValue(Column column)
                                    throws java.io.IOException

Returns the given column from the current row.

Throws:

java.io.IOException

setCurrentRowValue

public void setCurrentRowValue(Column column,
                               java.lang.Object value)
                        throws java.io.IOException

Updates a single value in the current row.

Throws:

java.lang.IllegalStateException - if the current row is not valid (at beginning or end of table), or deleted.

java.io.IOException

isUpToDate

protected boolean isUpToDate()

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

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

findAnotherPosition

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

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 getLastPosition() if moving forward and getFirstPosition() if moving backward.

Throws:

java.io.IOException

getDirHandler

protected abstract Cursor.DirHandler getDirHandler(boolean moveForward)

Returns the DirHandler for the given movement direction.