com.healthmarketscience.jackcess
Interface Cursor

All Superinterfaces:
Iterable<Row>
All Known Subinterfaces:
IndexCursor
All Known Implementing Classes:
CursorImpl, IndexCursorImpl, TableScanCursor

public interface Cursor
extends Iterable<Row>

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.

Basic cursors will generally iterate table data in the order it appears in the database and searches will require scanning the entire table. Additional features are available when utilizing an Index backed IndexCursor.

The CursorBuilder provides a variety of static utility methods to construct cursors with given characteristics or easily search for specific values as well as friendly and flexible construction options.

A Cursor instance is not thread-safe (see Database for more thread-safety details).

Author:
James Ahlborn
Usage:
General: This class is general use.

Nested Class Summary
static interface Cursor.Id
          Identifier for a cursor.
static interface Cursor.Position
          Value object which maintains the current position of the cursor.
static interface Cursor.Savepoint
          Value object which represents a complete save state of the cursor.
 
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).
 boolean currentRowMatches(Column columnPattern, Object valuePattern)
          Returns true if the current row matches the given pattern.
 boolean currentRowMatches(Map<String,?> rowPattern)
          Returns true if the current row matches the given pattern.
 void deleteCurrentRow()
          Delete the current row.
 boolean findFirstRow(Column columnPattern, Object valuePattern)
          Moves to the first row (as defined by the cursor) where the given column has the given value.
 boolean findFirstRow(Map<String,?> rowPattern)
          Moves to the first row (as defined by the cursor) where the given columns have the given values.
 boolean findNextRow(Column columnPattern, Object valuePattern)
          Moves to the next row (as defined by the cursor) where the given column has the given value.
 boolean findNextRow(Map<String,?> rowPattern)
          Moves to the next row (as defined by the cursor) where the given columns have the given values.
 boolean findRow(RowId rowId)
          Moves to the row with the given rowId.
 ColumnMatcher getColumnMatcher()
          Returns the currently configured ColumnMatcher, always non-null.
 Row getCurrentRow()
          Returns the current row in this cursor (Column name -> Column value).
 Row getCurrentRow(Collection<String> columnNames)
          Returns the current row in this cursor (Column name -> Column value).
 Object getCurrentRowValue(Column column)
          Returns the given column from the current row.
 ErrorHandler getErrorHandler()
          Gets the currently configured ErrorHandler (always non-null).
 Cursor.Id getId()
           
 Row getNextRow()
          Moves to the next row in the table and returns it.
 Row getNextRow(Collection<String> columnNames)
          Moves to the next row in the table and returns it.
 Row getPreviousRow()
          Moves to the previous row in the table and returns it.
 Row getPreviousRow(Collection<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).
 Iterator<Row> iterator()
          Calls beforeFirst() on this cursor and returns a modifiable Iterator which will iterate through all the rows of this table.
 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.
 IterableBuilder newIterable()
          Convenience method for constructing a new IterableBuilder for this cursor.
 void reset()
          Resets this cursor for forward traversal.
 void restoreSavepoint(Cursor.Savepoint savepoint)
          Moves the cursor to a savepoint previously returned from getSavepoint().
 void setColumnMatcher(ColumnMatcher columnMatcher)
          Sets a new ColumnMatcher.
 void setCurrentRowValue(Column column, Object value)
          Updates a single value in the current row.
 void setErrorHandler(ErrorHandler newErrorHandler)
          Sets a new ErrorHandler.
 Object[] updateCurrentRow(Object... row)
          Update the current row.
<M extends Map<String,Object>>
M
updateCurrentRowFromMap(M row)
          Update the current row.
 

Method Detail

getId

Cursor.Id getId()

getTable

Table getTable()

getErrorHandler

ErrorHandler getErrorHandler()
Gets the currently configured ErrorHandler (always non-null). This will be used to handle all errors.


setErrorHandler

void setErrorHandler(ErrorHandler newErrorHandler)
Sets a new ErrorHandler. If null, resets to using the ErrorHandler configured at the Table level.


getColumnMatcher

ColumnMatcher getColumnMatcher()
Returns the currently configured ColumnMatcher, always non-null.


setColumnMatcher

void setColumnMatcher(ColumnMatcher columnMatcher)
Sets a new ColumnMatcher. If null, resets to using the default matcher (default depends on Cursor type).


getSavepoint

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

void restoreSavepoint(Cursor.Savepoint savepoint)
                      throws IOException
Moves the cursor to a savepoint previously returned from getSavepoint().

Throws:
IllegalArgumentException - if the given savepoint does not have a cursorId equal to this cursor's id
IOException

reset

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


beforeFirst

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


afterLast

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


isBeforeFirst

boolean isBeforeFirst()
                      throws IOException
Returns true if the cursor is currently positioned before the first row, false otherwise.

Throws:
IOException

isAfterLast

boolean isAfterLast()
                    throws IOException
Returns true if the cursor is currently positioned after the last row, false otherwise.

Throws:
IOException

isCurrentRowDeleted

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

Throws:
IOException

iterator

Iterator<Row> 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().

For more flexible iteration see newIterable().

Specified by:
iterator in interface Iterable<Row>
Throws:
RuntimeIOException - if an IOException is thrown by one of the operations, the actual exception will be contained within

newIterable

IterableBuilder newIterable()
Convenience method for constructing a new IterableBuilder for this cursor. An IterableBuilder provides a variety of options for more flexible iteration.


deleteCurrentRow

void deleteCurrentRow()
                      throws IOException
Delete the current row.

Note, re-deleting an already deleted row is allowed (it does nothing).

Throws:
IllegalStateException - if the current row is not valid (at beginning or end of table)
IOException

updateCurrentRow

Object[] updateCurrentRow(Object... row)
                          throws IOException
Update the current row.

Returns:
the given row values if long enough, otherwise a new array, updated with the current row values
Throws:
IllegalStateException - if the current row is not valid (at beginning or end of table), or deleted.
IOException

updateCurrentRowFromMap

<M extends Map<String,Object>> M updateCurrentRowFromMap(M row)
                                                     throws IOException
Update the current row.

Returns:
the given row, updated with the current row values
Throws:
IllegalStateException - if the current row is not valid (at beginning or end of table), or deleted.
IOException

getNextRow

Row getNextRow()
               throws 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:
IOException

getNextRow

Row getNextRow(Collection<String> columnNames)
               throws 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:
IOException

getPreviousRow

Row getPreviousRow()
                   throws 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:
IOException

getPreviousRow

Row getPreviousRow(Collection<String> columnNames)
                   throws 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:
IOException

moveToNextRow

boolean moveToNextRow()
                      throws IOException
Moves to the next row as defined by this cursor.

Returns:
true if a valid next row was found, false otherwise
Throws:
IOException

moveToPreviousRow

boolean moveToPreviousRow()
                          throws IOException
Moves to the previous row as defined by this cursor.

Returns:
true if a valid previous row was found, false otherwise
Throws:
IOException

findRow

boolean findRow(RowId rowId)
                throws IOException
Moves to the row with the given rowId. If the row is not found (or an exception is thrown), the cursor is restored to its previous state.

Returns:
true if a valid row was found with the given id, false if no row was found
Throws:
IOException

findFirstRow

boolean findFirstRow(Column columnPattern,
                     Object valuePattern)
                     throws 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:
IOException

findNextRow

boolean findNextRow(Column columnPattern,
                    Object valuePattern)
                    throws 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:
IOException

findFirstRow

boolean findFirstRow(Map<String,?> rowPattern)
                     throws 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:
IOException

findNextRow

boolean findNextRow(Map<String,?> rowPattern)
                    throws 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:
IOException

currentRowMatches

boolean currentRowMatches(Column columnPattern,
                          Object valuePattern)
                          throws 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:
IOException

currentRowMatches

boolean currentRowMatches(Map<String,?> rowPattern)
                          throws 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:
IOException

moveNextRows

int moveNextRows(int numRows)
                 throws IOException
Moves forward as many rows as possible up to the given number of rows.

Returns:
the number of rows moved.
Throws:
IOException

movePreviousRows

int movePreviousRows(int numRows)
                     throws IOException
Moves backward as many rows as possible up to the given number of rows.

Returns:
the number of rows moved.
Throws:
IOException

getCurrentRow

Row getCurrentRow()
                  throws IOException
Returns the current row in this cursor (Column name -> Column value).

Throws:
IOException

getCurrentRow

Row getCurrentRow(Collection<String> columnNames)
                  throws IOException
Returns the current row in this cursor (Column name -> Column value).

Parameters:
columnNames - Only column names in this collection will be returned
Throws:
IOException

getCurrentRowValue

Object getCurrentRowValue(Column column)
                          throws IOException
Returns the given column from the current row.

Throws:
IOException

setCurrentRowValue

void setCurrentRowValue(Column column,
                        Object value)
                        throws IOException
Updates a single value in the current row.

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


Copyright © 2005–2017 Health Market Science. All rights reserved.