com.healthmarketscience.jackcess
Class CursorBuilder

java.lang.Object
  extended by 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
CursorBuilder(Table table)
           
 
Method Summary
 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 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.


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


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