Package com.healthmarketscience.jackcess.impl

Class 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

    • 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

      • getId

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

      • 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

      • restoreSavepoint

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

      • 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

      • 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

      • 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

      • 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. If this object is an instance of Predicate, it will be applied to the potential row value instead (overriding any configured ColumnMatcher)
        Returns:
        true if a valid row was found with the given value, false if no row was found
        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. If this object is an instance of Predicate, it will be applied to the potential row value instead (overriding any configured ColumnMatcher)
        Returns:
        true if a valid row was found with the given value, false if no row was found
        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. If a value is an instance of Predicate, it will be applied to the potential row value instead (overriding any configured ColumnMatcher)
        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. If a value is an instance of Predicate, it will be applied to the potential row value instead (overriding any configured ColumnMatcher)
        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 equal to the corresponding value in the matched row. If this object is an instance of Predicate, it will be applied to the potential row value instead (overriding any configured ColumnMatcher)
        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 matched row. If a value is an instance of Predicate, it will be applied to the potential row value instead (overriding any configured ColumnMatcher)
        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​(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