# Interface CursorExt

All Superinterfaces:
  `Cursor`

public interface CursorExt extends Cursor

Optional cursor capabilities, in the same spirit as `RowExt`.

These are not on `Cursor` itself because that interface is public and is implemented outside this repository; adding a method to it would break every third party library that provides one. Reach these through the static helpers on `Database`, which degrade gracefully on a cursor that does not implement this interface:

    Database.beforeFirst(cursor);
    int rows = Database.count(cursor); // -1 when the port cannot say cheaply

Every cursor returned by a Codename One port implements this.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `beforeFirst()`
  Rewinds to before the first row, without landing on a row.
  `int`
  `getCount()`
  Returns the number of rows in the result set, or -1 where a port cannot determine it.

  ### Methods inherited from interface Cursor

  `close, first, getColumnCount, getColumnIndex, getColumnName, getPosition, getRow, last, next, position, prev`

- ## Method Details

  - ### beforeFirst

    void beforeFirst() throws IOException

    Rewinds to before the first row, without landing on a row.

    After this call `Cursor#getPosition()` reports -1 and `Cursor#getRow()` throws, exactly as on a freshly returned cursor. This is the operation `Cursor#position(int)` performs when given -1.

    ###### Throws

    - `IOException`: if the cursor is closed or the rewind fails
    Throws:
      `IOException`

  - ### getCount

    int getCount() throws IOException

    Returns the number of rows in the result set, or -1 where a port cannot determine it.

    This can be expensive. Ports whose engine already tracks the count -- Android -- report it directly. Ports backed by a forward-only statement, which is the rest of them, answer by walking: rewind, step through every row, and rewind again. That is a full scan of the result set, so calling it on a large query costs what the query costs, and doing so on the EDT stops the application for that long. The count is remembered afterwards, and a rewind through `#beforeFirst()` drops it, since the next pass may not see the same rows.

    -1 means the port cannot answer at all. Treat it as "unknown", not as "empty".

    ###### Returns

    the row count, or -1 where the port cannot determine it

    ###### Throws

    - `IOException`: if the cursor is closed
    Throws:
      `IOException`