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. 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.

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

close

void close()
           throws DatabaseException

Closes the cursor, 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 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.

Returns:

true if the move succeeded; otherwise false.

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 the cursor is the forward type, then calling prev() will throw a DatabaseException.

Returns:

true if the move succeeded; otherwise false.

Throws:

DatabaseException - If the database connection is broken or the 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

Moves the cursor to the first row.

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.

Returns:

true if the move succeeded; otherwise false.

Throws:

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.

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

Moves the cursor to the last row.

If the cursor is empty, the method returns false.

Returns:

true if the move succeeded; otherwise false.

Throws:

DatabaseException - If the last row cannot 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

Moves the cursor to an absolute row position.

Parameters:

row - Zero-based position to move to.

Returns:

true if the move succeeded; otherwise false.

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 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.

Returns:

Current cursor position, or -1 when the 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 the current row with its values.

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.

Returns:

The current row, or null if the 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.

Column metadata 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.

Column metadata 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 is 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.

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.

Returns:

true if the cursor contains at least one row, false otherwise.

Throws:

DatabaseException - If the 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