|
|||||||||
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. The cursor columns can be referenced by Column objects passed into subsequent queries. 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. Any attempt to navigate to
the row before the current row will throw a DatabaseException
. 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.
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
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 database connection is broken or 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 or if
the current position is after the first row in a forward-only
cursor.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.boolean position(int row) throws DatabaseException
row
- Zero-based position to move to.
true
if the move succeeded; otherwise false
.
DatabaseException
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 closedRow 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
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 closedString 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 is closed.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 at least one row, false
otherwise.
DatabaseException
- If the database communication is broken.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.