Package com.healthmarketscience.jackcess

Class CursorBuilder

  • public class CursorBuilder
extends Object
    Builder style class for constructing a Cursor. By default, a cursor is created at the beginning of the table, and any start/end rows are inclusive.

    Simple example traversal: 

       for(Row row : table.newCursor().toCursor()) {
     // ... process each row ...
   }

    Simple example search: 

       Row row = CursorBuilder.findRow(table, Collections.singletonMap(col, "foo"));
    Author:
    James Ahlborn
    Usage:
    General: This class is general use.

    • Constructor Detail

      • CursorBuilder

        public CursorBuilder​(Table table)

    • Method Detail

      • beforeFirst

        public CursorBuilder beforeFirst()
        Sets the cursor so that it will start at the beginning (unless a savepoint is given).

      • afterLast

        public CursorBuilder afterLast()
        Sets the cursor so that it will start at the end (unless a savepoint is given).

      • restoreSavepoint

        public CursorBuilder restoreSavepoint​(Cursor.Savepoint savepoint)
        Sets a savepoint to restore for the initial position of the cursor.

      • setIndex

        public CursorBuilder setIndex​(Index index)
        Sets an index to use for the cursor.

      • setIndexByName

        public CursorBuilder setIndexByName​(String indexName)
        Sets an index to use for the cursor by searching the table for an index with the given name.
        Throws:
        IllegalArgumentException - if no index can be found on the table with the given name

      • setIndexByColumnNames

        public CursorBuilder setIndexByColumnNames​(String... columnNames)
        Sets an index to use for the cursor by searching the table for an index with exactly the given columns.
        Throws:
        IllegalArgumentException - if no index can be found on the table with the given columns

      • setIndexByColumns

        public CursorBuilder setIndexByColumns​(Column... columns)
        Sets an index to use for the cursor by searching the table for an index with exactly the given columns.
        Throws:
        IllegalArgumentException - if no index can be found on the table with the given columns

      • setSpecificRow

        public CursorBuilder setSpecificRow​(Object... specificRow)
        Sets the starting and ending row for a range based index cursor.

        A valid index must be specified before calling this method.

      • setSpecificEntry

        public CursorBuilder setSpecificEntry​(Object... specificEntry)
        Sets the starting and ending row for a range based index cursor to the given entry (where the given values correspond to the index's columns).

        A valid index must be specified before calling this method.

      • setStartRow

        public CursorBuilder setStartRow​(Object... startRow)
        Sets the starting row for a range based index cursor.

        A valid index must be specified before calling this method.

      • setStartEntry

        public CursorBuilder setStartEntry​(Object... startEntry)
        Sets the starting row for a range based index cursor to the given entry (where the given values correspond to the index's columns).

        A valid index must be specified before calling this method.

      • setStartRowInclusive

        public CursorBuilder setStartRowInclusive​(boolean inclusive)
        Sets whether the starting row for a range based index cursor is inclusive or exclusive.

      • setEndRow

        public CursorBuilder setEndRow​(Object... endRow)
        Sets the ending row for a range based index cursor.

        A valid index must be specified before calling this method.

      • setEndEntry

        public CursorBuilder setEndEntry​(Object... endEntry)
        Sets the ending row for a range based index cursor to the given entry (where the given values correspond to the index's columns).

        A valid index must be specified before calling this method.

      • setEndRowInclusive

        public CursorBuilder setEndRowInclusive​(boolean inclusive)
        Sets whether the ending row for a range based index cursor is inclusive or exclusive.

      • setColumnMatcher

        public CursorBuilder setColumnMatcher​(ColumnMatcher columnMatcher)
        Sets the ColumnMatcher to use for matching row patterns.

      • setCaseInsensitive

        public CursorBuilder setCaseInsensitive()
        Sets the ColumnMatcher to an instance of CaseInsensitiveColumnMatcher

      • toCursor

        public Cursor toCursor()
                throws IOException
        Returns a new cursor for the table, constructed to the given specifications.
        Throws:
        IOException

      • toIndexCursor

        public IndexCursor toIndexCursor()
                          throws IOException
        Returns a new index cursor for the table, constructed to the given specifications.
        Throws:
        IOException

      • createCursor

        public static Cursor createCursor​(Table table)
                           throws IOException
        Creates a normal, un-indexed cursor for the given table.
        Parameters:
        table - the table over which this cursor will traverse
        Throws:
        IOException

      • createCursor

        public static IndexCursor createCursor​(Index index)
                                throws 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:
        index - index for the table which will define traversal order as well as enhance certain lookups
        Throws:
        IOException

      • createPrimaryKeyCursor

        public static IndexCursor createPrimaryKeyCursor​(Table table)
                                          throws IOException
        Creates an indexed cursor for the primary key cursor of the given table.
        Parameters:
        table - the table over which this cursor will traverse
        Throws:
        IOException

      • createCursor

        public static IndexCursor createCursor​(Index index,
                                       Object[] startRow,
                                       Object[] endRow)
                                throws 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:
        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:
        IOException

      • createCursor

        public static IndexCursor createCursor​(Index index,
                                       Object[] startRow,
                                       boolean startInclusive,
                                       Object[] endRow,
                                       boolean endInclusive)
                                throws 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:
        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:
        IOException

      • findRow

        public static Row findRow​(Table table,
                          Map<String,​?> rowPattern)
                   throws IOException
        Convenience method for finding a specific row in a table which matches a given row "pattern". See Cursor.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:
        IOException

      • findRowByEntry

        public static Row findRowByEntry​(Index index,
                                 Object... entryValues)
                          throws IOException
        Convenience method for finding a specific row (as defined by the cursor) where the index entries match the given values. See IndexCursor.findRowByEntry(Object...) for details on the entryValues.
        Parameters:
        index - the index to search
        entryValues - the column values for the index's columns.
        Returns:
        the matching row or null if a match could not be found.
        Throws:
        IOException

      • findRowByPrimaryKey

        public static Row findRowByPrimaryKey​(Table table,
                                      Object... entryValues)
                               throws IOException
        Convenience method for finding a specific row by the primary key of the table. See IndexCursor.findRowByEntry(Object...) for details on the entryValues.
        Parameters:
        table - the table to search
        entryValues - the column values for the table's primary key columns.
        Returns:
        the matching row or null if a match could not be found.
        Throws:
        IOException

      • findValue

        public static Object findValue​(Table table,
                               Column column,
                               Column columnPattern,
                               Object valuePattern)
                        throws IOException
        Convenience method for finding a specific row in a table which matches a given row "pattern". See Cursor.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:
        IOException

      • findRow

        public static Row findRow​(Index index,
                          Map<String,​?> rowPattern)
                   throws IOException
        Convenience method for finding a specific row in an indexed table which matches a given row "pattern". See Cursor.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:
        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:
        IOException

      • findValue

        public static Object findValue​(Index index,
                               Column column,
                               Column columnPattern,
                               Object valuePattern)
                        throws IOException
        Convenience method for finding a specific row in a table which matches a given row "pattern". See Cursor.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:
        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:
        IOException