com.healthmarketscience.jackcess.impl
Class CursorImpl

java.lang.Object
  extended by com.healthmarketscience.jackcess.impl.CursorImpl
All Implemented Interfaces:
Cursor, Iterable<Row>
Direct Known Subclasses:
IndexCursorImpl, TableScanCursor

public abstract class CursorImpl
extends Object
implements Cursor

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 Ahlborn

Nested Class Summary
 
Nested classes/interfaces inherited from interface com.healthmarketscience.jackcess.Cursor
Cursor.Id, Cursor.Position, Cursor.Savepoint
 
Field Summary
static boolean MOVE_FORWARD
          boolean value indicating forward movement
static boolean MOVE_REVERSE
          boolean value indicating reverse movement
 
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).
static CursorImpl createCursor(TableImpl table)
          Creates a normal, un-indexed cursor for the given table.
 boolean currentRowMatches(ColumnImpl columnPattern, Object valuePattern)
           
 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(ColumnImpl columnPattern, Object valuePattern)
           
 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(ColumnImpl columnPattern, Object valuePattern)
           
 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.
 Object getCurrentRowValue(ColumnImpl column)
           
 ErrorHandler getErrorHandler()
          Gets the currently configured ErrorHandler (always non-null).
 JetFormat getFormat()
           
 com.healthmarketscience.jackcess.impl.CursorImpl.IdImpl 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.
 PageChannel getPageChannel()
           
 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.
 TableImpl.RowState getRowState()
           
 com.healthmarketscience.jackcess.impl.CursorImpl.SavepointImpl getSavepoint()
          Returns the current state of the cursor which can be restored at a future point in time by a call to Cursor.restoreSavepoint(com.healthmarketscience.jackcess.Cursor.Savepoint).
 TableImpl 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 Cursor.beforeFirst() on this cursor and returns a modifiable Iterator which will iterate through all the rows of this table.
 Iterator<Row> iterator(IterableBuilder iterBuilder)
           
 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 Cursor.getSavepoint().
 void restoreSavepoint(com.healthmarketscience.jackcess.impl.CursorImpl.SavepointImpl savepoint)
           
 void setColumnMatcher(ColumnMatcher columnMatcher)
          Sets a new ColumnMatcher.
 void setCurrentRowValue(ColumnImpl column, Object value)
           
 void setCurrentRowValue(Column column, Object value)
          Updates a single value in the current row.
 void setErrorHandler(ErrorHandler newErrorHandler)
          Sets a new ErrorHandler.
 String toString()
           
 Object[] updateCurrentRow(Object... row)
          Update the current row.
<M extends Map<String,Object>>
M
updateCurrentRowFromMap(M row)
          Update the current row.
 
Methods inherited from class java.lang.Object
equals, 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
Method Detail

createCursor

public static CursorImpl createCursor(TableImpl table)
Creates a normal, un-indexed cursor for the given table.

Parameters:
table - the table over which this cursor will traverse

getRowState

public TableImpl.RowState getRowState()

getId

public com.healthmarketscience.jackcess.impl.CursorImpl.IdImpl getId()
Specified by:
getId in interface Cursor

getTable

public TableImpl getTable()
Specified by:
getTable in interface Cursor

getFormat

public JetFormat getFormat()

getPageChannel

public PageChannel getPageChannel()

getErrorHandler

public ErrorHandler getErrorHandler()
Description copied from interface: Cursor
Gets the currently configured ErrorHandler (always non-null). This will be used to handle all errors.

Specified by:
getErrorHandler in interface Cursor

setErrorHandler

public void setErrorHandler(ErrorHandler newErrorHandler)
Description copied from interface: Cursor
Sets a new ErrorHandler. If null, resets to using the ErrorHandler configured at the Table level.

Specified by:
setErrorHandler in interface Cursor

getColumnMatcher

public ColumnMatcher getColumnMatcher()
Description copied from interface: Cursor
Returns the currently configured ColumnMatcher, always non-null.

Specified by:
getColumnMatcher in interface Cursor

setColumnMatcher

public void setColumnMatcher(ColumnMatcher columnMatcher)
Description copied from interface: Cursor
Sets a new ColumnMatcher. If null, resets to using the default matcher (default depends on Cursor type).

Specified by:
setColumnMatcher in interface Cursor

getSavepoint

public com.healthmarketscience.jackcess.impl.CursorImpl.SavepointImpl getSavepoint()
Description copied from interface: Cursor
Returns the current state of the cursor which can be restored at a future point in time by a call to Cursor.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.

Specified by:
getSavepoint in interface Cursor

restoreSavepoint

public void restoreSavepoint(Cursor.Savepoint savepoint)
                      throws IOException
Description copied from interface: Cursor
Moves the cursor to a savepoint previously returned from Cursor.getSavepoint().

Specified by:
restoreSavepoint in interface Cursor
Throws:
IOException

restoreSavepoint

public void restoreSavepoint(com.healthmarketscience.jackcess.impl.CursorImpl.SavepointImpl savepoint)
                      throws IOException
Throws:
IOException

reset

public void reset()
Description copied from interface: Cursor
Resets this cursor for forward traversal. Calls Cursor.beforeFirst().

Specified by:
reset in interface Cursor

beforeFirst

public void beforeFirst()
Description copied from interface: Cursor
Resets this cursor for forward traversal (sets cursor to before the first row).

Specified by:
beforeFirst in interface Cursor

afterLast

public void afterLast()
Description copied from interface: Cursor
Resets this cursor for reverse traversal (sets cursor to after the last row).

Specified by:
afterLast in interface Cursor

isBeforeFirst

public boolean isBeforeFirst()
                      throws IOException
Description copied from interface: Cursor
Returns true if the cursor is currently positioned before the first row, false otherwise.

Specified by:
isBeforeFirst in interface Cursor
Throws:
IOException

isAfterLast

public boolean isAfterLast()
                    throws IOException
Description copied from interface: Cursor
Returns true if the cursor is currently positioned after the last row, false otherwise.

Specified by:
isAfterLast in interface Cursor
Throws:
IOException

isCurrentRowDeleted

public boolean isCurrentRowDeleted()
                            throws IOException
Description copied from interface: Cursor
Returns true if the row at which the cursor is currently positioned is deleted, false otherwise (including invalid rows).

Specified by:
isCurrentRowDeleted in interface Cursor
Throws:
IOException

iterator

public Iterator<Row> iterator()
Description copied from interface: Cursor
Calls Cursor.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 Cursor.getNextRow().

For more flexible iteration see Cursor.newIterable().

Specified by:
iterator in interface Cursor
Specified by:
iterator in interface Iterable<Row>

newIterable

public IterableBuilder newIterable()
Description copied from interface: Cursor
Convenience method for constructing a new IterableBuilder for this cursor. An IterableBuilder provides a variety of options for more flexible iteration.

Specified by:
newIterable in interface Cursor

iterator

public Iterator<Row> iterator(IterableBuilder iterBuilder)

deleteCurrentRow

public void deleteCurrentRow()
                      throws IOException
Description copied from interface: Cursor
Delete the current row.

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

Specified by:
deleteCurrentRow in interface Cursor
Throws:
IOException

updateCurrentRow

public Object[] updateCurrentRow(Object... row)
                          throws IOException
Description copied from interface: Cursor
Update the current row.

Specified by:
updateCurrentRow in interface Cursor
Returns:
the given row values if long enough, otherwise a new array, updated with the current row values
Throws:
IOException

updateCurrentRowFromMap

public <M extends Map<String,Object>> M updateCurrentRowFromMap(M row)
                                                     throws IOException
Description copied from interface: Cursor
Update the current row.

Specified by:
updateCurrentRowFromMap in interface Cursor
Returns:
the given row, updated with the current row values
Throws:
IOException

getNextRow

public Row getNextRow()
               throws IOException
Description copied from interface: Cursor
Moves to the next row in the table and returns it.

Specified by:
getNextRow in interface Cursor
Returns:
The next row in this table (Column name -> Column value), or null if no next row is found
Throws:
IOException

getNextRow

public Row getNextRow(Collection<String> columnNames)
               throws IOException
Description copied from interface: Cursor
Moves to the next row in the table and returns it.

Specified by:
getNextRow in interface Cursor
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

public Row getPreviousRow()
                   throws IOException
Description copied from interface: Cursor
Moves to the previous row in the table and returns it.

Specified by:
getPreviousRow in interface Cursor
Returns:
The previous row in this table (Column name -> Column value), or null if no previous row is found
Throws:
IOException

getPreviousRow

public Row getPreviousRow(Collection<String> columnNames)
                   throws IOException
Description copied from interface: Cursor
Moves to the previous row in the table and returns it.

Specified by:
getPreviousRow in interface Cursor
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

public boolean moveToNextRow()
                      throws IOException
Description copied from interface: Cursor
Moves to the next row as defined by this cursor.

Specified by:
moveToNextRow in interface Cursor
Returns:
true if a valid next row was found, false otherwise
Throws:
IOException

moveToPreviousRow

public boolean moveToPreviousRow()
                          throws IOException
Description copied from interface: Cursor
Moves to the previous row as defined by this cursor.

Specified by:
moveToPreviousRow in interface Cursor
Returns:
true if a valid previous row was found, false otherwise
Throws:
IOException

findRow

public boolean findRow(RowId rowId)
                throws IOException
Description copied from interface: Cursor
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.

Specified by:
findRow in interface Cursor
Returns:
true if a valid row was found with the given id, false if no row was found
Throws:
IOException

findFirstRow

public boolean findFirstRow(Column columnPattern,
                            Object valuePattern)
                     throws IOException
Description copied from interface: Cursor
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).

Specified by:
findFirstRow in interface 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:
IOException

findFirstRow

public boolean findFirstRow(ColumnImpl columnPattern,
                            Object valuePattern)
                     throws IOException
Throws:
IOException

findNextRow

public boolean findNextRow(Column columnPattern,
                           Object valuePattern)
                    throws IOException
Description copied from interface: Cursor
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.

Specified by:
findNextRow in interface 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:
IOException

findNextRow

public boolean findNextRow(ColumnImpl columnPattern,
                           Object valuePattern)
                    throws IOException
Throws:
IOException

findFirstRow

public boolean findFirstRow(Map<String,?> rowPattern)
                     throws IOException
Description copied from interface: Cursor
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).

Specified by:
findFirstRow in interface 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:
IOException

findNextRow

public boolean findNextRow(Map<String,?> rowPattern)
                    throws IOException
Description copied from interface: Cursor
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.

Specified by:
findNextRow in interface 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:
IOException

currentRowMatches

public boolean currentRowMatches(Column columnPattern,
                                 Object valuePattern)
                          throws IOException
Description copied from interface: Cursor
Returns true if the current row matches the given pattern.

Specified by:
currentRowMatches in interface Cursor
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

public boolean currentRowMatches(ColumnImpl columnPattern,
                                 Object valuePattern)
                          throws IOException
Throws:
IOException

currentRowMatches

public boolean currentRowMatches(Map<String,?> rowPattern)
                          throws IOException
Description copied from interface: Cursor
Returns true if the current row matches the given pattern.

Specified by:
currentRowMatches in interface Cursor
Parameters:
rowPattern - column names and values which must be equal to the corresponding values in the current row
Throws:
IOException

moveNextRows

public int moveNextRows(int numRows)
                 throws IOException
Description copied from interface: Cursor
Moves forward as many rows as possible up to the given number of rows.

Specified by:
moveNextRows in interface Cursor
Returns:
the number of rows moved.
Throws:
IOException

movePreviousRows

public int movePreviousRows(int numRows)
                     throws IOException
Description copied from interface: Cursor
Moves backward as many rows as possible up to the given number of rows.

Specified by:
movePreviousRows in interface Cursor
Returns:
the number of rows moved.
Throws:
IOException

getCurrentRow

public Row getCurrentRow()
                  throws IOException
Description copied from interface: Cursor
Returns the current row in this cursor (Column name -> Column value).

Specified by:
getCurrentRow in interface Cursor
Throws:
IOException

getCurrentRow

public Row getCurrentRow(Collection<String> columnNames)
                  throws IOException
Description copied from interface: Cursor
Returns the current row in this cursor (Column name -> Column value).

Specified by:
getCurrentRow in interface Cursor
Parameters:
columnNames - Only column names in this collection will be returned
Throws:
IOException

getCurrentRowValue

public Object getCurrentRowValue(Column column)
                          throws IOException
Description copied from interface: Cursor
Returns the given column from the current row.

Specified by:
getCurrentRowValue in interface Cursor
Throws:
IOException

getCurrentRowValue

public Object getCurrentRowValue(ColumnImpl column)
                          throws IOException
Throws:
IOException

setCurrentRowValue

public void setCurrentRowValue(Column column,
                               Object value)
                        throws IOException
Description copied from interface: Cursor
Updates a single value in the current row.

Specified by:
setCurrentRowValue in interface Cursor
Throws:
IOException

setCurrentRowValue

public void setCurrentRowValue(ColumnImpl column,
                               Object value)
                        throws IOException
Throws:
IOException

toString

public String toString()
Overrides:
toString in class Object


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