Interface Cursor

All Known Subinterfaces:
CursorExt
public interface Cursor

Iterates over the results returned from a database query.

Positions are counted from zero and a new cursor sits before the first row, so the usual loop is simply:

Cursor cur = db.executeQuery("SELECT id, body FROM notes ORDER BY id");
try {
    while (cur.next()) {
        Row row = cur.getRow();
        System.out.println(row.getInteger(0) + ": " + row.getString(1));
    }
} finally {
    cur.close();
}

Every navigation method works on every platform. Only the cost varies: #next() is uniformly cheap, while #last(), #prev() and #position(int) may have to rewind and re-step the underlying statement, which costs time proportional to the distance from the start. For a large result set, prefer iterating forward with #next().

Because a backward seek re-runs the statement, a cursor is a repeatable read only inside a transaction. See the com.codename1.db package documentation for the full contract.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Closes the cursor and releases its resources.
    boolean
    first()
    Moves the cursor onto the first row.
    int
    getColumnCount()
    Returns the column count
    int
    getColumnIndex(String columnName)
    Returns the zero-based index of a column, or -1 if there is no such column.
    String
    getColumnName(int columnIndex)
    Returns the label of the column at a zero-based index.
    int
    getPosition()
    Returns the zero-based position of the cursor.
    Row
    getRow()
    Returns the current row.
    boolean
    last()
    Moves the cursor onto the last row.
    boolean
    next()
    Advances the cursor one row.
    boolean
    position(int row)
    Moves the cursor to an absolute zero-based row.
    boolean
    prev()
    Moves the cursor back one row.

  • Method Details

    • first

      boolean first() throws IOException

      Moves the cursor onto the first row.

      Returns

      true if there is a first row, false for an empty result set

      Throws
      • IOException: if the cursor is closed
      Throws:
      IOException

    • last

      boolean last() throws IOException

      Moves the cursor onto the last row.

      Costs a full pass over the result set the first time it is called.

      Returns

      true if there is a last row, false for an empty result set

      Throws
      • IOException: if the cursor is closed
      Throws:
      IOException

    • next

      boolean next() throws IOException

      Advances the cursor one row.

      A new cursor sits before the first row, so the first call lands on it.

      Returns

      true if a row was reached, false at the end of the result set

      Throws
      • IOException: if the cursor is closed
      Throws:
      IOException

    • prev

      boolean prev() throws IOException

      Moves the cursor back one row.

      Returns

      true if a row was reached, false when already at or before the first row

      Throws
      • IOException: if the cursor is closed
      Throws:
      IOException

    • getColumnIndex

      int getColumnIndex(String columnName) throws IOException

      Returns the zero-based index of a column, or -1 if there is no such column.

      The comparison is case-insensitive and matches the result set label, so a column selected as SELECT a AS b is found under b. Available as soon as the query returns, before the first #next().

      Parameters
      • columnName: the name of the column
      Returns

      the zero-based index, or -1 when the column is not in the result set

      Throws
      • IOException: if the cursor is closed
      Throws:
      IOException

    • getColumnName

      String getColumnName(int columnIndex) throws IOException

      Returns the label of the column at a zero-based index.

      Available as soon as the query returns, before the first #next().

      Parameters
      • columnIndex: the zero-based index of the column
      Returns

      the column label

      Throws
      • IOException: if the cursor is closed
      Throws:
      IOException

    • getColumnCount

      int getColumnCount() throws IOException

      Returns the column count

      Returns

      the column count

      Throws
      • IOException
      Throws:
      IOException

    • getPosition

      int getPosition() throws IOException

      Returns the zero-based position of the cursor.

      Reports -1 before any successful move, and the row count once the result set is exhausted.

      Returns

      the cursor position

      Throws
      • IOException: if the cursor is closed
      Throws:
      IOException

    • position

      boolean position(int row) throws IOException

      Moves the cursor to an absolute zero-based row.

      Passing -1 rewinds to before the first row and returns false.

      Parameters
      • row: the zero-based row to move to
      Returns

      true if the row exists, false if it is out of range

      Throws
      • IOException: if the cursor is closed
      Throws:
      IOException

    • close

      void close() throws IOException

      Closes the cursor and releases its resources.

      Calling this more than once is harmless.

      Throws
      • IOException: if the underlying statement cannot be released
      Throws:
      IOException

    • getRow

      Row getRow() throws IOException

      Returns the current row.

      Valid only while the cursor is on a row.

      Returns

      the current row

      Throws
      • IOException: @throws IOException if the cursor is closed, or is before the first row or past the last one
      Throws:
      IOException