# 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`