CursorBuilder (Jackcess 4.0.7 API)

java.lang.Object
- com.healthmarketscience.jackcess.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 Summary

Constructors
Constructor and Description

CursorBuilder(Table table)

Constructors
Constructor and Description
`CursorBuilder(Table table)`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`CursorBuilder`	`afterLast()` Sets the cursor so that it will start at the end (unless a savepoint is given).
`CursorBuilder`	`beforeFirst()` Sets the cursor so that it will start at the beginning (unless a savepoint is given).
`static IndexCursor`	`createCursor(Index index)` Creates an indexed cursor for the given table.
`static IndexCursor`	`createCursor(Index index, Object[] startRow, boolean startInclusive, Object[] endRow, boolean endInclusive)` Creates an indexed cursor for the given table, narrowed to the given range.
`static IndexCursor`	`createCursor(Index index, Object[] startRow, Object[] endRow)` Creates an indexed cursor for the given table, narrowed to the given range.
`static Cursor`	`createCursor(Table table)` Creates a normal, un-indexed cursor for the given table.
`static IndexCursor`	`createPrimaryKeyCursor(Table table)` Creates an indexed cursor for the primary key cursor of the given table.
`static Row`	`findRow(Index index, Map<String,?> rowPattern)` Convenience method for finding a specific row in an indexed table which matches a given row "pattern".
`static Row`	`findRow(Table table, Map<String,?> rowPattern)` Convenience method for finding a specific row in a table which matches a given row "pattern".
`static Row`	`findRowByEntry(Index index, Object... entryValues)` Convenience method for finding a specific row (as defined by the cursor) where the index entries match the given values.
`static Row`	`findRowByPrimaryKey(Table table, Object... entryValues)` Convenience method for finding a specific row by the primary key of the table.
`static Object`	`findValue(Index index, Column column, Column columnPattern, Object valuePattern)` Convenience method for finding a specific row in a table which matches a given row "pattern".
`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".
`CursorBuilder`	`restoreSavepoint(Cursor.Savepoint savepoint)` Sets a savepoint to restore for the initial position of the cursor.
`CursorBuilder`	`setCaseInsensitive()` Sets the ColumnMatcher to an instance of CaseInsensitiveColumnMatcher
`CursorBuilder`	`setColumnMatcher(ColumnMatcher columnMatcher)` Sets the ColumnMatcher to use for matching row patterns.
`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).
`CursorBuilder`	`setEndRow(Object... endRow)` Sets the ending row for a range based index cursor.
`CursorBuilder`	`setEndRowInclusive(boolean inclusive)` Sets whether the ending row for a range based index cursor is inclusive or exclusive.
`CursorBuilder`	`setIndex(Index index)` Sets an index to use for the cursor.
`CursorBuilder`	`setIndexByColumnNames(String... columnNames)` Sets an index to use for the cursor by searching the table for an index with exactly the given columns.
`CursorBuilder`	`setIndexByColumns(Column... columns)` Sets an index to use for the cursor by searching the table for an index with exactly the given columns.
`CursorBuilder`	`setIndexByName(String indexName)` Sets an index to use for the cursor by searching the table for an index with the given name.
`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).
`CursorBuilder`	`setSpecificRow(Object... specificRow)` Sets the starting and ending row for a range based index cursor.
`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).
`CursorBuilder`	`setStartRow(Object... startRow)` Sets the starting row for a range based index cursor.
`CursorBuilder`	`setStartRowInclusive(boolean inclusive)` Sets whether the starting row for a range based index cursor is inclusive or exclusive.
`Cursor`	`toCursor()` Returns a new cursor for the table, constructed to the given specifications.
`IndexCursor`	`toIndexCursor()` Returns a new index cursor for the table, constructed to the given specifications.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- 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

Class CursorBuilder

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CursorBuilder

Method Detail

beforeFirst

afterLast

restoreSavepoint

setIndex

setIndexByName

setIndexByColumnNames

setIndexByColumns

setSpecificRow

setSpecificEntry

setStartRow

setStartEntry

setStartRowInclusive

setEndRow

setEndEntry

setEndRowInclusive

setColumnMatcher

setCaseInsensitive

toCursor

toIndexCursor

createCursor

createCursor

createPrimaryKeyCursor

createCursor

createCursor

findRow

findRowByEntry

findRowByPrimaryKey

findValue

findRow

findValue