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
Category: Signed  void close()
          Closes cursor object, releasing all of its resources and making it completely invalid.
Category: Signed  boolean first()
          Move 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 current row with values.
Category: Signed  boolean isEmpty()
          Determines if the cursor contains rows.
Category: Signed  boolean last()
          Move the cursor to the last row.
Category: Signed  boolean next()
          Moves the cursor to the next row.
Category: Signed  boolean position(int row)
          Move 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 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.