public interface Cursor

Known subtypesCursorExt

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.

Methods

public abstract boolean first() throws IOExceptionMoves the cursor onto the first row.
public abstract boolean last() throws IOExceptionMoves the cursor onto the last row.
public abstract boolean next() throws IOExceptionAdvances the cursor one row.
public abstract boolean prev() throws IOExceptionMoves the cursor back one row.
public abstract int getColumnIndex(String columnName) throws IOExceptionReturns the zero-based index of a column, or -1 if there is no such column.
public abstract String getColumnName(int columnIndex) throws IOExceptionReturns the label of the column at a zero-based index.
public abstract int getColumnCount() throws IOExceptionReturns the column count
public abstract int getPosition() throws IOExceptionReturns the zero-based position of the cursor.
public abstract boolean position(int row) throws IOExceptionMoves the cursor to an absolute zero-based row.
public abstract void close() throws IOExceptionCloses the cursor and releases its resources.
public abstract Row getRow() throws IOExceptionReturns the current row.

Method details

first

public abstract 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

last

public abstract 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

next

public abstract 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

prev

public abstract 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

getColumnIndex

public abstract 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 String
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

getColumnName

public abstract 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 int
the zero-based index of the column

Returns

the column label

Throws

IOException
if the cursor is closed

getColumnCount

public abstract int getColumnCount() throws IOException
Returns the column count

Returns

the column count

Throws

IOException

getPosition

public abstract 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

position

public abstract 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 int
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

close

public abstract 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

getRow

public abstract Row getRow() throws IOException

Returns the current row.

Valid only while the cursor is on a row.

Returns

the current row

Throws

IOException
if the cursor is closed, or is before the first row or past the last one