net.rim.device.api.database
Class BufferedCursor

java.lang.Object
  extended by net.rim.device.api.database.BufferedCursor
All Implemented Interfaces:
Cursor

public class BufferedCursor
extends Object
implements Cursor

Caches all rows in memory for bidirectional or random access. Suitable for small cursors that provide forward-only data access.

Note that using the buffered cursor may throw an OutOfMemoryError if it is used with huge data queries.

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

Constructor Summary
Category: Signed BufferedCursor(Cursor cursor)
          Creates buffered cursor based on given delegate
 
Method Summary
Category: Signed  void close()
          Closes cursor object, releasing all of its resources and making it completely invalid.
Category: Signed  boolean first()
          Navigates 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)
          Positiones cursor on the specified position
Category: Signed  boolean prev()
          Navigates to the previous row if it exists
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Constructor Detail

BufferedCursor

public BufferedCursor(Cursor cursor)
               throws NullPointerException
Creates buffered cursor based on given delegate

Throws:
NullPointerException - if the cursor parameter is NULL
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 Detail

first

public boolean first()
              throws DatabaseException
Navigates to the first row

Specified by:
first in interface Cursor
Returns:
true if there is at least one row in the cursor, false if the cursor is empty
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

getPosition

public int getPosition()
                throws DatabaseException
Description copied from interface: Cursor
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.

Specified by:
getPosition in interface Cursor
Returns:
current Cursor position or -1 when cursor contains no rows or was never navigated.
Throws:
DatabaseException
See Also:
Cursor.getPosition()
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

public Row getRow()
           throws DatabaseException
Description copied from interface: Cursor
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.

Specified by:
getRow in interface Cursor
Returns:
Row Current row or NULL if cursor contains no rows or is not positioned on a row.
Throws:
DatabaseException
See Also:
Cursor.getRow()
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

public boolean last()
             throws DatabaseException
Description copied from interface: Cursor
Move the cursor to the last row.

The method would return false if the cursor is empty.

Specified by:
last in interface Cursor
Returns:
whether the move succeeded.
Throws:
DatabaseException - if the last row can not be retrieved from the database.
See Also:
Cursor.last()
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

public boolean next()
             throws DatabaseException
Description copied from interface: Cursor
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.

Specified by:
next in interface Cursor
Returns:
whether the move succeeded.
Throws:
DatabaseException
See Also:
Cursor.next()
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

public boolean position(int row)
                 throws DatabaseException
Positiones cursor on the specified position

Specified by:
position in interface Cursor
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

prev

public boolean prev()
             throws DatabaseException
Navigates to the previous row if it exists

Specified by:
prev in interface Cursor
Returns:
true if there is a previous row, false otherwise
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

close

public void close()
           throws DatabaseException
Description copied from interface: Cursor
Closes cursor object, releasing all of its resources and making it completely invalid.

Specified by:
close in interface Cursor
Throws:
DatabaseException
See Also:
Cursor.close()
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

public boolean isEmpty()
                throws DatabaseException
Description copied from interface: Cursor
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.

Specified by:
isEmpty in interface Cursor
Returns:
true if cursor contains at least one row, false otherwise.
Throws:
DatabaseException - if database communication is broken.
See Also:
Cursor.isEmpty()
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

public int getColumnIndex(String columnName)
                   throws DatabaseException
Description copied from interface: Cursor
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.

Specified by:
getColumnIndex in interface Cursor
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 cursor is closed
See Also:
Cursor.getColumnIndex(String)
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

public String getColumnName(int columnIndex)
                     throws DatabaseException
Description copied from interface: Cursor
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.

Specified by:
getColumnName in interface Cursor
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 cursor is closed
See Also:
Cursor.getColumnName(int)
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.