net.rim.device.api.database
Interface Cursor
- All Known Implementing Classes:
- BufferedCursor
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. Cursor can be treated as tables and can be queried just like
persistent tables. The cursor columns can be referenced by Column objects
passed into subsequent queries. When 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 will throw a DatabaseException. The
BufferedCursor class caches cursor data in memory and provides random
data access.
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
|
Method Summary |
|
void |
close()
Closes cursor object, releasing all of its resources and making it
completely invalid. |
|
boolean |
first()
Move 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 current row with values. |
|
boolean |
isEmpty()
Determines if the cursor contains rows. |
|
boolean |
last()
Move the cursor to the last row. |
|
boolean |
next()
Moves the cursor to the next row. |
|
boolean |
position(int row)
Move the cursor to an absolute row position. |
|
boolean |
prev()
Moves the cursor to the previous row. |
close
void close()
throws DatabaseException
- Closes cursor object, releasing all of its resources and making it
completely invalid.
- Throws:
DatabaseException- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
next
boolean next()
throws DatabaseException
- Moves the cursor to the next row.
Calling next() method the first time will position cursor on the first
row if it is available. Similarly, if cursor is positioned on the last
row then calling next() will move the pointer after the last row and row
data access methods would return invalid data.
- Returns:
- whether the move succeeded.
- Throws:
DatabaseException- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
prev
boolean prev()
throws DatabaseException
- Moves the cursor to the previous row.
If cursor is forward type then calling prev() would throw a
DatabaseException.
- Returns:
- whether the move succeeded.
- Throws:
DatabaseException - if database connection is broken or cursor does not
provide backward type navigation.- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
first
boolean first()
throws DatabaseException
- Move the cursor to the first row.
This method would return false if the cursor is empty. If cursor provides
forward-only navigation and is positioned after the first row then
calling first() method would throw a DatabaseException.
- Returns:
- whether the move succeeded.
- Throws:
DatabaseException - if the first row can not be retrieved from database or if
current position is after the first row in the forward
only type cursor.- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
last
boolean last()
throws DatabaseException
- Move the cursor to the last row.
The method would return false if the cursor is empty.
- Returns:
- whether the move succeeded.
- Throws:
DatabaseException - if the last row can not be retrieved from the database.- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
position
boolean position(int row)
throws DatabaseException
- Move the cursor to an absolute row position.
- Parameters:
row - zero-based position to move to.
- Returns:
- whether the requested move fully succeeded.
- Throws:
DatabaseException- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
getPosition
int getPosition()
throws DatabaseException
- Returns the current Cursor position.
If cursor was not navigated through Cursor.next(), Cursor.last() and
similar methods then its current position is before the first row and
marked as -1.
- Returns:
- current Cursor position or -1 when cursor contains no rows or was
never navigated.
- Throws:
DatabaseException - if the cursor was closed- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
getRow
Row getRow()
throws DatabaseException
- Retrieves current row with values.
Cursor must be positioned on a row for this method to return non-null
value. When the cursor is opened it is positioned before the first row
and this method will return NULL. Call Cursor.first() or
Cursor.next() to navigate to the first row and then call getRow() to
get the data.
- Returns:
- Row Current row or NULL if cursor contains no rows or is not
positioned on a row.
- Throws:
DatabaseException- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
getColumnIndex
int getColumnIndex(String columnName)
throws DatabaseException
- Returns the zero-based index for a given column name.
Note that columns meta information is available only after navigation to
the first row. Call Cursor.next() or Cursor.first() before calling
this method.
- Parameters:
columnName - the name of the target column.
- Returns:
- Returns the zero-based column index for the given column name;
or -1 if the column name does not exist.
- Throws:
DatabaseException - if the cursor was closed- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
getColumnName
String getColumnName(int columnIndex)
throws DatabaseException
- Returns the column name at a given zero-based column index.
Note that columns meta information is available only after navigation to
the first row. Call Cursor.next() or Cursor.first() before calling
this method.
- Parameters:
columnIndex - the zero-based index of the target column.
- Returns:
- the column name for the given column index; or
null if the given column index is larger than the number of columns.
- Throws:
DatabaseException - if the cursor was closed- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
isEmpty
boolean isEmpty()
throws DatabaseException
- Determines if the cursor contains rows.
Note that information 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.
- Returns:
- true if cursor contains at least one row, false otherwise.
- Throws:
DatabaseException - if database communication is broken.- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 5.0.0
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.