| java.lang.Object
 com.healthmarketscience.jackcess.Cursor
| Cursor | | abstract public class Cursor implements Iterable<Map<String, Object>>(Code) | | 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.
author:
james |
| Inner Class :abstract protected class DirHandler | |
| Inner Class :final public static class Id | |
| Inner Class :final public static class Savepoint | |
| Inner Class :abstract public static class Position | |
| Constructor Summary | |
| protected | Cursor(Id id, Table table, Position firstPos, Position lastPos)
|
| Method Summary | |
| public void | afterLast()
Resets this cursor for reverse traversal (sets cursor to after the last
row). | | public void | beforeFirst()
Resets this cursor for forward traversal (sets cursor to before the first
row). | | public static Cursor | createCursor(Table table)
Creates a normal, un-indexed cursor for the given table. | | public static Cursor | createIndexCursor(Table table, Index index)
Creates an indexed cursor for the given table. | | public static Cursor | createIndexCursor(Table table, Index index, Object[] startRow, Object[] endRow)
Creates an indexed cursor for the given table, narrowed to the given
range. | | public static Cursor | createIndexCursor(Table table, Index index, Object[] startRow, boolean startInclusive, Object[] endRow, boolean endInclusive)
Creates an indexed cursor for the given table, narrowed to the given
range. | | public boolean | currentRowMatches(Column columnPattern, Object valuePattern)
Returns
true if the current row matches the given pattern. | | public boolean | currentRowMatches(Map<String, Object> rowPattern)
Returns
true if the current row matches the given pattern. | | public void | deleteCurrentRow()
Delete the current row. | | abstract protected Position | findAnotherPosition(RowState rowState, 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 . | | public static Map<String, Object> | findRow(Table table, Map<String, Object> rowPattern)
Convenience method for finding a specific row in a table which matches a
given row "pattern". | | public static Map<String, Object> | findRow(Table table, Index index, Map<String, Object> rowPattern)
Convenience method for finding a specific row in an indexed table which
matches a given row "pattern". | | public boolean | findRow(Column columnPattern, Object valuePattern)
Moves to the first row (as defined by the cursor) where the given column
has the given value. | | public boolean | findRow(Map<String, Object> rowPattern)
Moves to the first row (as defined by the cursor) where the given columns
have the given values. | | protected boolean | findRowImpl(Column columnPattern, Object valuePattern)
Moves to the first row (as defined by the cursor) where the given column
has the given value. | | protected boolean | findRowImpl(Map<String, Object> rowPattern)
Moves to the first row (as defined by the cursor) where the given columns
have the given values. | | public static Object | findValue(Table table, Column column, Column columnPattern, Object valuePattern)
Convenience method for finding a specific row in a table which matches a
given row "pattern". | | public static Object | findValue(Table table, Index index, Column column, Column columnPattern, Object valuePattern)
Convenience method for finding a specific row in a table which matches a
given row "pattern". | | public Map<String, Object> | getCurrentRow()
Returns the current row in this cursor (Column name -> Column value). | | public Map<String, Object> | getCurrentRow(Collection<String> columnNames)
Returns the current row in this cursor (Column name -> Column value). | | public Object | getCurrentRowValue(Column column)
Returns the given column from the current row. | | abstract protected DirHandler | getDirHandler(boolean moveForward)
Returns the DirHandler for the given movement direction. | | protected Position | getFirstPosition()
Returns the first row id (exclusive) as defined by this cursor. | | public JetFormat | getFormat()
| | public Id | getId()
| | public Index | getIndex()
| | protected Position | getLastPosition()
Returns the last row id (exclusive) as defined by this cursor. | | public Map<String, Object> | getNextRow()
Moves to the next row in the table and returns it. | | public Map<String, Object> | getNextRow(Collection<String> columnNames)
Moves to the next row in the table and returns it. | | public PageChannel | getPageChannel()
| | public Map<String, Object> | getPreviousRow()
Moves to the previous row in the table and returns it. | | public Map<String, Object> | getPreviousRow(Collection<String> columnNames)
Moves to the previous row in the table and returns it. | | public Savepoint | getSavepoint()
Returns the current state of the cursor which can be restored at a future
point in time by a call to
Cursor.restoreSavepoint . | | public Table | getTable()
| | public boolean | isAfterLast()
Returns
true if the cursor is currently positioned after the
last row,
false otherwise. | | public boolean | isBeforeFirst()
Returns
true if the cursor is currently positioned before the
first row,
false otherwise. | | public 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. | | public Iterable<Map<String, Object>> | iterable(Collection<String> columnNames)
| | public Iterator<Map<String, Object>> | iterator()
Calls beforeFirst on this cursor and returns an unmodifiable
Iterator which will iterate through all the rows of this table. | | public Iterator<Map<String, Object>> | iterator(Collection<String> columnNames)
Calls beforeFirst on this table and returns an unmodifiable
Iterator which will iterate through all the rows of this table, returning
only the given columns. | | public int | moveNextRows(int numRows)
Moves forward as many rows as possible up to the given number of rows. | | public int | movePreviousRows(int numRows)
Moves backward as many rows as possible up to the given number of rows. | | public boolean | moveToNextRow()
Moves to the next row as defined by this cursor. | | public boolean | moveToPreviousRow()
Moves to the previous row as defined by this cursor. | | public void | reset()
Resets this cursor for forward traversal. | | protected void | reset(boolean moveForward)
Resets this cursor for traversing the given direction. | | protected void | restorePosition(Position curPos)
Restores a current position for the cursor (current position becomes
previous position). | | final protected void | restorePosition(Position curPos, Position prevPos)
Restores a current and previous position for the cursor if the given
positions are different from the current positions. | | protected void | restorePositionImpl(Position curPos, Position prevPos)
Restores a current and previous position for the cursor. | | public void | restoreSavepoint(Savepoint savepoint)
Moves the cursor to a savepoint previously returned from
Cursor.getSavepoint . | | public Iterable<Map<String, Object>> | reverseIterable()
Returns an Iterable whose iterator() method calls afterLast
on this cursor and returns an unmodifiable Iterator which will iterate
through all the rows of this table in reverse order. | | public Iterable<Map<String, Object>> | reverseIterable(Collection<String> columnNames)
Returns an Iterable whose iterator() method calls afterLast
on this table and returns an unmodifiable Iterator which will iterate
through all the rows of this table in reverse order, returning only the
given columns. | | public String | toString()
|
| Cursor | | protected Cursor(Id id, Table table, Position firstPos, Position lastPos)(Code) | | |
| afterLast | | public void afterLast()(Code) | | Resets this cursor for reverse traversal (sets cursor to after the last
row).
|
| beforeFirst | | public void beforeFirst()(Code) | | Resets this cursor for forward traversal (sets cursor to before the first
row).
|
| createCursor | | public static Cursor createCursor(Table table)(Code) | | 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 IOException(Code) | | Creates an indexed cursor for the given table.
Parameters:
table - the table over which this cursor will traverse
Parameters:
index - index for the table which will define traversal order aswell as enhance certain lookups |
| createIndexCursor | | public static Cursor createIndexCursor(Table table, Index index, Object[] startRow, Object[] endRow) throws IOException(Code) | | Creates an indexed cursor for the given table, narrowed to the given
range.
Parameters:
table - the table over which this cursor will traverse
Parameters:
index - index for the table which will define traversal order aswell as enhance certain lookups
Parameters:
startRow - the first row of data for the cursor (inclusive), or null for the first entry
Parameters:
endRow - the last row of data for the cursor (inclusive), or null for the last entry |
| createIndexCursor | | public static Cursor createIndexCursor(Table table, Index index, Object[] startRow, boolean startInclusive, Object[] endRow, boolean endInclusive) throws IOException(Code) | | Creates an indexed cursor for the given table, narrowed to the given
range.
Parameters:
table - the table over which this cursor will traverse
Parameters:
index - index for the table which will define traversal order aswell as enhance certain lookups
Parameters:
startRow - the first row of data for the cursor, or null forthe first entry
Parameters:
startInclusive - whether or not startRow is inclusive or exclusive
Parameters:
endRow - the last row of data for the cursor, or null forthe last entry
Parameters:
endInclusive - whether or not endRow is inclusive or exclusive |
| currentRowMatches | | public boolean currentRowMatches(Column columnPattern, Object valuePattern) throws IOException(Code) | | Returns
true if the current row matches the given pattern.
Parameters:
columnPattern - column from the table for this cursor which is beingmatched by the valuePattern
Parameters:
valuePattern - value which is tested for equality with thecorresponding value in the current row |
| currentRowMatches | | public boolean currentRowMatches(Map<String, Object> rowPattern) throws IOException(Code) | | Returns
true if the current row matches the given pattern.
Parameters:
rowPattern - column names and values which must be equal to thecorresponding values in the current row |
| deleteCurrentRow | | public void deleteCurrentRow() throws IOException(Code) | | Delete the current row.
throws:
IllegalStateException - if the current row is not valid (atbeginning or end of table), or already deleted. |
| findAnotherPosition | | abstract protected Position findAnotherPosition(RowState rowState, Position curPos, boolean moveForward) throws IOException(Code) | | 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.
|
| findRow | | public static Map<String, Object> findRow(Table table, Map<String, Object> rowPattern) throws IOException(Code) | | Convenience method for finding a specific row in a table which matches a
given row "pattern". See
Cursor.findRow(Map) for details on the
rowPattern.
Parameters:
table - the table to search
Parameters:
rowPattern - pattern to be used to find the row the matching row or null if a match could not be found. |
| findRow | | public static Map<String, Object> findRow(Table table, Index index, Map<String, Object> rowPattern) throws IOException(Code) | | Convenience method for finding a specific row in an indexed table which
matches a given row "pattern". See
Cursor.findRow(Map) for details on
the rowPattern.
Parameters:
table - the table to search
Parameters:
index - index to assist the search
Parameters:
rowPattern - pattern to be used to find the row the matching row or null if a match could not be found. |
| findRow | | public boolean findRow(Column columnPattern, Object valuePattern) throws IOException(Code) | | 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.
Parameters:
columnPattern - column from the table for this cursor which is beingmatched by the valuePattern
Parameters:
valuePattern - value which is equal to the corresponding value inthe matched row true if a valid row was found with the given value, false if no row was found |
| findRow | | public boolean findRow(Map<String, Object> rowPattern) throws IOException(Code) | | 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.
Parameters:
rowPattern - column names and values which must be equal to thecorresponding values in the matched row true if a valid row was found with the given values, false if no row was found |
| findRowImpl | | protected boolean findRowImpl(Column columnPattern, Object valuePattern) throws IOException(Code) | | Moves to the first 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 beingmatched by the valuePattern
Parameters:
valuePattern - value which is equal to the corresponding value inthe matched row true if a valid row was found with the given value, false if no row was found |
| findRowImpl | | protected boolean findRowImpl(Map<String, Object> rowPattern) throws IOException(Code) | | Moves to the first 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 thecorresponding values in the matched row true if a valid row was found with the given values, false if no row was found |
| findValue | | public static Object findValue(Table table, Column column, Column columnPattern, Object valuePattern) throws IOException(Code) | | Convenience method for finding a specific row in a table which matches a
given row "pattern". See
Cursor.findRow(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
Parameters:
column - column whose value should be returned
Parameters:
columnPattern - column being matched by the valuePattern
Parameters:
valuePattern - value from the columnPattern which will match thedesired row the matching row or null if a match could not be found. |
| findValue | | public static Object findValue(Table table, Index index, Column column, Column columnPattern, Object valuePattern) throws IOException(Code) | | Convenience method for finding a specific row in a table which matches a
given row "pattern". See
Cursor.findRow(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
Parameters:
index - index to assist the search
Parameters:
column - column whose value should be returned
Parameters:
columnPattern - column being matched by the valuePattern
Parameters:
valuePattern - value from the columnPattern which will match thedesired row the matching row or null if a match could not be found. |
| getCurrentRow | | public Map<String, Object> getCurrentRow(Collection<String> columnNames) throws IOException(Code) | | Returns the current row in this cursor (Column name -> Column value).
Parameters:
columnNames - Only column names in this collection will be returned |
| getDirHandler | | abstract protected DirHandler getDirHandler(boolean moveForward)(Code) | | Returns the DirHandler for the given movement direction.
|
| getFirstPosition | | protected Position getFirstPosition()(Code) | | Returns the first row id (exclusive) as defined by this cursor.
|
| getLastPosition | | protected Position getLastPosition()(Code) | | Returns the last row id (exclusive) as defined by this cursor.
|
| getNextRow | | public Map<String, Object> getNextRow() throws IOException(Code) | | Moves to the next row in the table and returns it.
The next row in this table (Column name -> Column value), or null if no next row is found |
| getNextRow | | public Map<String, Object> getNextRow(Collection<String> columnNames) throws IOException(Code) | | Moves to the next row in the table and returns it.
Parameters:
columnNames - Only column names in this collection will be returned The next row in this table (Column name -> Column value), or null if no next row is found |
| getPreviousRow | | public Map<String, Object> getPreviousRow() throws IOException(Code) | | Moves to the previous row in the table and returns it.
The previous row in this table (Column name -> Column value), or null if no previous row is found |
| getPreviousRow | | public Map<String, Object> getPreviousRow(Collection<String> columnNames) throws IOException(Code) | | Moves to the previous row in the table and returns it.
Parameters:
columnNames - Only column names in this collection will be returned The previous row in this table (Column name -> Column value), or null if no previous row is found |
| getSavepoint | | public Savepoint getSavepoint()(Code) | | Returns the current state of the cursor which can be restored at a future
point in time by a call to
Cursor.restoreSavepoint .
Savepoints may be used across different cursor instances for the same
table, but they must have the same
Id .
|
| isAfterLast | | public boolean isAfterLast() throws IOException(Code) | | Returns
true if the cursor is currently positioned after the
last row,
false otherwise.
|
| isBeforeFirst | | public boolean isBeforeFirst() throws IOException(Code) | | Returns
true if the cursor is currently positioned before the
first row,
false otherwise.
|
| isCurrentRowDeleted | | public boolean isCurrentRowDeleted() throws IOException(Code) | | Returns
true if the row at which the cursor is currently
positioned is deleted,
false otherwise (including invalid rows).
|
| isUpToDate | | protected boolean isUpToDate()(Code) | | Returns
true if this cursor is up-to-date with respect to the
relevant table and related table objects,
false otherwise.
|
| iterator | | public Iterator<Map<String, Object>> iterator()(Code) | | Calls beforeFirst on this cursor and returns an unmodifiable
Iterator which will iterate through all the rows of this table. Use of
the Iterator follows the same restrictions as a call to
getNextRow.
throws:
IllegalStateException - if an IOException is thrown by one of theoperations, the actual exception will be contained within |
| iterator | | public Iterator<Map<String, Object>> iterator(Collection<String> columnNames)(Code) | | Calls beforeFirst on this table and returns an unmodifiable
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:
IllegalStateException - if an IOException is thrown by one of theoperations, the actual exception will be contained within |
| moveNextRows | | public int moveNextRows(int numRows) throws IOException(Code) | | Moves forward as many rows as possible up to the given number of rows.
the number of rows moved. |
| movePreviousRows | | public int movePreviousRows(int numRows) throws IOException(Code) | | Moves backward as many rows as possible up to the given number of rows.
the number of rows moved. |
| moveToNextRow | | public boolean moveToNextRow() throws IOException(Code) | | Moves to the next row as defined by this cursor.
true if a valid next row was found, false otherwise |
| moveToPreviousRow | | public boolean moveToPreviousRow() throws IOException(Code) | | Moves to the previous row as defined by this cursor.
true if a valid previous row was found, false otherwise |
| reset | | protected void reset(boolean moveForward)(Code) | | Resets this cursor for traversing the given direction.
|
| restorePosition | | protected void restorePosition(Position curPos) throws IOException(Code) | | Restores a current position for the cursor (current position becomes
previous position).
|
| restorePosition | | final protected void restorePosition(Position curPos, Position prevPos) throws IOException(Code) | | Restores a current and previous position for the cursor if the given
positions are different from the current positions.
|
| restorePositionImpl | | protected void restorePositionImpl(Position curPos, Position prevPos) throws IOException(Code) | | Restores a current and previous position for the cursor.
|
| reverseIterable | | public Iterable<Map<String, Object>> reverseIterable()(Code) | | Returns an Iterable whose iterator() method calls afterLast
on this cursor and returns an unmodifiable 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:
IllegalStateException - if an IOException is thrown by one of theoperations, the actual exception will be contained within |
| reverseIterable | | public Iterable<Map<String, Object>> reverseIterable(Collection<String> columnNames)(Code) | | Returns an Iterable whose iterator() method calls afterLast
on this table and returns an unmodifiable 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:
IllegalStateException - if an IOException is thrown by one of theoperations, the actual exception will be contained within |
|
|