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
Category: Signed  void close()
          Closes the cursor, releasing all of its resources and making it completely invalid.
Category: Signed  boolean first()
          Moves the cursor to the first row.
Category: Signed  int getColumnIndex(String columnName)
          Returns the zero-based index for a given column name.
Category: Signed  String getColumnName(int columnIndex)
          Returns the column name at a given zero-based column index.
Category: Signed  int getPosition()
          Returns the current cursor position.
Category: Signed  Row getRow()
          Retrieves the current row with its values.
Category: Signed  boolean isEmpty()
          Determines if the cursor contains rows.
Category: Signed  boolean last()
          Moves the cursor to the last row.
Category: Signed  boolean next()
          Moves the cursor to the next row.
Category: Signed  boolean position(int row)
          Moves the cursor to an absolute row position.
Category: Signed  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





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.