|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
public interface Cursor
Provides read-only access to results returned by a database query.
Cursor is an iterator over an internal temporary table holding the query
results. Cursors can be queried just like persistent tables. Column
data can be retrieved using Row methods. When the cursor is
closed the temporary table is discarded.
The default implementation of this interface does not cache any data, thus
providing a one-way forward-only navigation method. As a result, any attempt
to navigate to a row before the current one will throw a DatabaseException.
For example, first() cannot be called once the cursor is past the first row.
Alternatively, the BufferedCursor class caches cursor data in memory and provides random
data access, but there are limits on the amount of data it can handle.
By default, one row is buffered at a time.
When the cursor moves past the buffered set, a new batch of rows is automatically fetched.
To improve performance, you may want to increase the buffer size to a value greater than 1.
You can set the buffer size using the Statement.setCursorBufferSize method.
For more information about the Database API, see the Data Storage Development Guide for BlackBerry Java SDK, available at www.blackberry.com/go/devguides. For more information about SQLite, see www.sqlite.org.
| Method Summary | ||
|---|---|---|
|
void |
close()
Closes the cursor, releasing all of its resources and making it completely invalid. |
|
boolean |
first()
Moves the cursor to the first row. |
|
int |
getColumnIndex(String columnName)
Returns the zero-based index for a given column name. |
|
String |
getColumnName(int columnIndex)
Returns the column name at a given zero-based column index. |
|
int |
getPosition()
Returns the current cursor position. |
|
Row |
getRow()
Retrieves the current row with its values. |
|
boolean |
isEmpty()
Determines if the cursor contains rows. |
|
boolean |
last()
Moves the cursor to the last row. |
|
boolean |
next()
Moves the cursor to the next row. |
|
boolean |
position(int row)
Moves the cursor to an absolute row position. |
|
boolean |
prev()
Moves the cursor to the previous row. |
| Method Detail |
|---|
void close()
throws DatabaseException
DatabaseException - Never thrown but is kept for backwards compatibility.
boolean next()
throws DatabaseException
Calling the next() method the first time positions the cursor on the first
row, if it is available. If the cursor is positioned on the last
row then calling next() moves the pointer after the last row, and row
data access methods will return invalid data.
true if the move succeeded; otherwise false.
DatabaseException
boolean prev()
throws DatabaseException
If the cursor is the forward type, then calling prev() will throw a
DatabaseException.
true if the move succeeded; otherwise false.
DatabaseException - If the cursor does not provide backward type navigation.
boolean first()
throws DatabaseException
This method returns false if the cursor is empty. If the cursor provides
forward-only navigation and is positioned after the first row, then
calling the first() method throws a DatabaseException.
true if the move succeeded; otherwise false.
DatabaseException - If the first row cannot be retrieved from the database; if
the current position is after the first row in a forward-only
cursor; or if the cursor was closed.
boolean last()
throws DatabaseException
If the cursor is empty, the method returns false.
true if the move succeeded; otherwise false.
DatabaseException - If the last row cannot be retrieved from the database
or if the cursor was closed.
boolean position(int row)
throws DatabaseException
If a negative position is specified, the cursor position is not changed and false is returned, and row
data access methods will return invalid data.
If the specified row is after the last one, the cursor will be positioned at the last row and false is returned,
and row data access methods will return invalid data.
If the cursor has no rows, then it will be positioned at -1 and false is returned, and row
data access methods will return invalid data.
Call getPosition() to confirm the current position.
row - Zero-based position to move to.
true if the move succeeded; otherwise false.
DatabaseException - If the cursor was closed.
int getPosition()
throws DatabaseException
If the cursor was not navigated through Cursor.next(), Cursor.last() or
similar methods, then its current position is before the first row and is
marked as -1.
DatabaseException - If the cursor was closed.
Row getRow()
throws DatabaseException
The cursor must be positioned on a row for this method to return a non-null
value. When the cursor is first opened, the cursor is positioned before the first row and
this method returns null. Call Cursor.first() or
Cursor.next() to navigate to the first row and then call getRow() to
get the data.
null if the cursor contains no rows or is not
positioned on a row.
DatabaseException - If the cursor was closed.
int getColumnIndex(String columnName)
throws DatabaseException
Column metadata is available only after navigation to
the first row. Call Cursor.next() or Cursor.first() before calling
this method.
columnName - The name of the target column.
DatabaseException - If the cursor was closed.
String getColumnName(int columnIndex)
throws DatabaseException
Column metadata is available only after navigation to
the first row. Call Cursor.next() or Cursor.first() before calling
this method.
columnIndex - The zero-based index of the target column.
null if the given column index is larger than the number of columns.
DatabaseException - If the cursor was closed.
IndexOutOfBoundsException - if the columnIndex is negative.
boolean isEmpty()
throws DatabaseException
Information about whether the cursor is empty or not is available
only after navigating to a row through any of the following methods:
Cursor.first(), Cursor.next(), Cursor.last(). If the cursor was
never navigated then this method returns true, meaning that
no rows were fetched.
true if the cursor contains no rows or hasn't been
navigated, false otherwise.
DatabaseException - If the cursor was closed.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal