Added in API level 1

Summary: Inherited Constants | Fields | Ctors | Methods | Protected Methods | Inherited Methods

CursorWindow

---

Kotlin |Java

public class CursorWindow
extends SQLiteClosable implements Parcelable

java.lang.Object
↳	android.database.sqlite.SQLiteClosable
	↳	android.database.CursorWindow

---

A buffer containing multiple cursor rows.

A CursorWindow is read-write when initially created and used locally. When sent to a remote process (by writing it to a Parcel), the remote process receives a read-only view of the cursor window. Typically the cursor window will be allocated by the producer, filled with data, and then sent to the consumer for reading.

Summary

Inherited constants

From interface android.os.Parcelable int CONTENTS_FILE_DESCRIPTOR Descriptor bit used with describeContents(): indicates that the Parcelable object's flattened representation includes a file descriptor. int PARCELABLE_WRITE_RETURN_VALUE Flag for use with writeToParcel(Parcel, int): the object being written is a return value, that is the result of a function such as "Parcelable someFunction()", "void someFunction(out Parcelable)", or "void someFunction(inout Parcelable)".

Fields
public static final Creator<CursorWindow>	CREATOR

Public constructors
CursorWindow(boolean localWindow) This constructor is deprecated. There is no longer a distinction between local and remote cursor windows. Use the CursorWindow(java.lang.String) constructor instead.
CursorWindow(String name) Creates a new empty cursor window and gives it a name.
CursorWindow(String name, long windowSizeBytes) Creates a new empty cursor window and gives it a name.

Public methods
boolean	allocRow() Allocates a new row at the end of this cursor window.
void	clear() Clears out the existing contents of the window, making it safe to reuse for new data.
void	copyStringToBuffer(int row, int column, CharArrayBuffer buffer) Copies the text of the field at the specified row and column index into a CharArrayBuffer.
int	describeContents() Describe the kinds of special objects contained in this Parcelable instance's marshaled representation.
void	freeLastRow() Frees the last row in this cursor window.
byte[]	getBlob(int row, int column) Gets the value of the field at the specified row and column index as a byte array.
double	getDouble(int row, int column) Gets the value of the field at the specified row and column index as a double.
float	getFloat(int row, int column) Gets the value of the field at the specified row and column index as a float.
int	getInt(int row, int column) Gets the value of the field at the specified row and column index as an int.
long	getLong(int row, int column) Gets the value of the field at the specified row and column index as a long.
int	getNumRows() Gets the number of rows in this window.
short	getShort(int row, int column) Gets the value of the field at the specified row and column index as a short.
int	getStartPosition() Gets the start position of this cursor window.
String	getString(int row, int column) Gets the value of the field at the specified row and column index as a string.
int	getType(int row, int column) Returns the type of the field at the specified row and column index.
boolean	isBlob(int row, int column) This method was deprecated in API level 15. Use getType(int, int) instead.
boolean	isFloat(int row, int column) This method was deprecated in API level 15. Use getType(int, int) instead.
boolean	isLong(int row, int column) This method was deprecated in API level 15. Use getType(int, int) instead.
boolean	isNull(int row, int column) This method was deprecated in API level 15. Use getType(int, int) instead.
boolean	isString(int row, int column) This method was deprecated in API level 15. Use getType(int, int) instead.
static CursorWindow	newFromParcel(Parcel p)
boolean	putBlob(byte[] value, int row, int column) Copies a byte array into the field at the specified row and column index.
boolean	putDouble(double value, int row, int column) Puts a double-precision floating point value into the field at the specified row and column index.
boolean	putLong(long value, int row, int column) Puts a long integer into the field at the specified row and column index.
boolean	putNull(int row, int column) Puts a null value into the field at the specified row and column index.
boolean	putString(String value, int row, int column) Copies a string into the field at the specified row and column index.
boolean	setNumColumns(int columnNum) Sets the number of columns in this window.
void	setStartPosition(int pos) Sets the start position of this cursor window.
String	toString() Returns a string representation of the object.
void	writeToParcel(Parcel dest, int flags) Flatten this object in to a Parcel.

Protected methods
void	finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
void	onAllReferencesReleased() Called when the last reference to the object was released by a call to releaseReference() or close().

Inherited methods
From class android.database.sqlite.SQLiteClosable void acquireReference() Acquires a reference to the object. void close() Releases a reference to the object, closing the object if the last reference was released. abstract void onAllReferencesReleased() Called when the last reference to the object was released by a call to releaseReference() or close(). void onAllReferencesReleasedFromContainer() This method was deprecated in API level 16. Do not use. void releaseReference() Releases a reference to the object, closing the object if the last reference was released. void releaseReferenceFromContainer() This method was deprecated in API level 16. Do not use.
From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
From interface java.io.Closeable abstract void close() Closes this stream and releases any system resources associated with it.
From interface android.os.Parcelable abstract int describeContents() Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. abstract void writeToParcel(Parcel dest, int flags) Flatten this object in to a Parcel.
From interface java.lang.AutoCloseable abstract void close() Closes this resource, relinquishing any underlying resources.

Fields

CREATOR

Added in API level 1

public static final Creator<CursorWindow> CREATOR

Public constructors

CursorWindow

Added in API level 1

public CursorWindow (boolean localWindow)

This constructor is deprecated.
There is no longer a distinction between local and remote cursor windows. Use the CursorWindow(java.lang.String) constructor instead.

Creates a new empty cursor window.

The cursor initially has no rows or columns. Call setNumColumns(int) to set the number of columns before adding any rows to the cursor.

Parameters
localWindow	boolean: True if this window will be used in this process only, false if it might be sent to another processes. This argument is ignored.

CursorWindow

Added in API level 15

public CursorWindow (String name)

Creates a new empty cursor window and gives it a name.

The cursor initially has no rows or columns. Call setNumColumns(int) to set the number of columns before adding any rows to the cursor.

Parameters
name	String: The name of the cursor window, or null if none.

CursorWindow

Added in API level 28

public CursorWindow (String name, 
                long windowSizeBytes)

Creates a new empty cursor window and gives it a name.

The cursor initially has no rows or columns. Call setNumColumns(int) to set the number of columns before adding any rows to the cursor.

Parameters
name	String: The name of the cursor window, or null if none.
windowSizeBytes	long: Size of cursor window in bytes. Value is a non-negative number of bytes.

Throws
IllegalArgumentException	if windowSizeBytes is less than 0
AssertionError	if created window pointer is 0 Note: Memory is dynamically allocated as data rows are added to the window. Depending on the amount of data stored, the actual amount of memory allocated can be lower than specified size, but cannot exceed it.

Public methods

allocRow

Added in API level 1

public boolean allocRow ()

Allocates a new row at the end of this cursor window.

Returns
boolean	True if successful, false if the cursor window is out of memory.

clear

Added in API level 1

public void clear ()

Clears out the existing contents of the window, making it safe to reuse for new data.

The start position (getStartPosition()), number of rows (getNumRows()), and number of columns in the cursor are all reset to zero.

copyStringToBuffer

Added in API level 1

public void copyStringToBuffer (int row, 
                int column, 
                CharArrayBuffer buffer)

Copies the text of the field at the specified row and column index into a CharArrayBuffer.

The buffer is populated as follows:

• If the buffer is too small for the value to be copied, then it is automatically resized.
• If the field is of type Cursor.FIELD_TYPE_NULL, then the buffer is set to an empty string.
• If the field is of type Cursor.FIELD_TYPE_STRING, then the buffer is set to the contents of the string.
• If the field is of type Cursor.FIELD_TYPE_INTEGER, then the buffer is set to a string representation of the integer in decimal, obtained by formatting the value with the printf family of functions using format specifier %lld.
• If the field is of type Cursor.FIELD_TYPE_FLOAT, then the buffer is set to a string representation of the floating-point value in decimal, obtained by formatting the value with the printf family of functions using format specifier %g.
• If the field is of type Cursor.FIELD_TYPE_BLOB, then a SQLiteException is thrown.

Parameters
row	int: The zero-based row index. Value is 0 or greater
column	int: The zero-based column index. Value is 0 or greater
buffer	CharArrayBuffer: The CharArrayBuffer to hold the string. It is automatically resized if the requested string is larger than the buffer's current capacity.

describeContents

Added in API level 1

public int describeContents ()

Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. For example, if the object will include a file descriptor in the output of writeToParcel(android.os.Parcel, int), the return value of this method must include the CONTENTS_FILE_DESCRIPTOR bit.

Returns
int	a bitmask indicating the set of special object types marshaled by this Parcelable object instance. Value is either 0 or CONTENTS_FILE_DESCRIPTOR

freeLastRow

Added in API level 1

public void freeLastRow ()

Frees the last row in this cursor window.

getBlob

Added in API level 1

public byte[] getBlob (int row, 
                int column)

Gets the value of the field at the specified row and column index as a byte array.

The result is determined as follows:

• If the field is of type Cursor.FIELD_TYPE_NULL, then the result is null.
• If the field is of type Cursor.FIELD_TYPE_BLOB, then the result is the blob value.
• If the field is of type Cursor.FIELD_TYPE_STRING, then the result is the array of bytes that make up the internal representation of the string value.
• If the field is of type Cursor.FIELD_TYPE_INTEGER or Cursor.FIELD_TYPE_FLOAT, then a SQLiteException is thrown.

Parameters
row	int: The zero-based row index. Value is 0 or greater
column	int: The zero-based column index. Value is 0 or greater

Returns
byte[]	The value of the field as a byte array.

getDouble

Added in API level 1

public double getDouble (int row, 
                int column)

Gets the value of the field at the specified row and column index as a double.

The result is determined as follows:

• If the field is of type Cursor.FIELD_TYPE_NULL, then the result is 0.0.
• If the field is of type Cursor.FIELD_TYPE_STRING, then the result is the value obtained by parsing the string value with strtod.
• If the field is of type Cursor.FIELD_TYPE_INTEGER, then the result is the integer value converted to a double.
• If the field is of type Cursor.FIELD_TYPE_FLOAT, then the result is the double value.
• If the field is of type Cursor.FIELD_TYPE_BLOB, then a SQLiteException is thrown.

Parameters
row	int: The zero-based row index. Value is 0 or greater
column	int: The zero-based column index. Value is 0 or greater

Returns
double	The value of the field as a double.

getFloat

Added in API level 1

public float getFloat (int row, 
                int column)

Gets the value of the field at the specified row and column index as a float.

The result is determined by invoking getDouble(int, int) and converting the result to float.

Parameters
row	int: The zero-based row index. Value is 0 or greater
column	int: The zero-based column index. Value is 0 or greater

Returns
float	The value of the field as an float.

getInt

Added in API level 1

public int getInt (int row, 
                int column)

Gets the value of the field at the specified row and column index as an int.

The result is determined by invoking getLong(int, int) and converting the result to int.

Parameters
row	int: The zero-based row index. Value is 0 or greater
column	int: The zero-based column index. Value is 0 or greater

Returns
int	The value of the field as an int.

getLong

Added in API level 1

public long getLong (int row, 
                int column)

Gets the value of the field at the specified row and column index as a long.

The result is determined as follows:

• If the field is of type Cursor.FIELD_TYPE_NULL, then the result is 0L.
• If the field is of type Cursor.FIELD_TYPE_STRING, then the result is the value obtained by parsing the string value with strtoll.
• If the field is of type Cursor.FIELD_TYPE_INTEGER, then the result is the long value.
• If the field is of type Cursor.FIELD_TYPE_FLOAT, then the result is the floating-point value converted to a long.
• If the field is of type Cursor.FIELD_TYPE_BLOB, then a SQLiteException is thrown.

Parameters
row	int: The zero-based row index. Value is 0 or greater
column	int: The zero-based column index. Value is 0 or greater

Returns
long	The value of the field as a long.

getNumRows

Added in API level 1

public int getNumRows ()

Gets the number of rows in this window.

Returns
int	The number of rows in this cursor window. Value is 0 or greater

getShort

Added in API level 1

public short getShort (int row, 
                int column)

Gets the value of the field at the specified row and column index as a short.

The result is determined by invoking getLong(int, int) and converting the result to short.

Parameters
row	int: The zero-based row index. Value is 0 or greater
column	int: The zero-based column index. Value is 0 or greater

Returns
short	The value of the field as a short.

getStartPosition

Added in API level 1

public int getStartPosition ()

Gets the start position of this cursor window.

The start position is the zero-based index of the first row that this window contains relative to the entire result set of the Cursor.

Returns
int	The zero-based start position. Value is 0 or greater

getString

Added in API level 1

public String getString (int row, 
                int column)

Gets the value of the field at the specified row and column index as a string.

The result is determined as follows:

• If the field is of type Cursor.FIELD_TYPE_NULL, then the result is null.
• If the field is of type Cursor.FIELD_TYPE_STRING, then the result is the string value.
• If the field is of type Cursor.FIELD_TYPE_INTEGER, then the result is a string representation of the integer in decimal, obtained by formatting the value with the printf family of functions using format specifier %lld.
• If the field is of type Cursor.FIELD_TYPE_FLOAT, then the result is a string representation of the floating-point value in decimal, obtained by formatting the value with the printf family of functions using format specifier %g.
• If the field is of type Cursor.FIELD_TYPE_BLOB, then a SQLiteException is thrown.

Parameters
row	int: The zero-based row index. Value is 0 or greater
column	int: The zero-based column index. Value is 0 or greater

Returns
String	The value of the field as a string.

getType

Added in API level 11

public int getType (int row, 
                int column)

Returns the type of the field at the specified row and column index.

Parameters
row	int: The zero-based row index. Value is 0 or greater
column	int: The zero-based column index. Value is 0 or greater

Returns
int	The field type. Value is Cursor.FIELD_TYPE_NULL, Cursor.FIELD_TYPE_INTEGER, Cursor.FIELD_TYPE_FLOAT, Cursor.FIELD_TYPE_STRING, or Cursor.FIELD_TYPE_BLOB

isBlob

Added in API level 1
Deprecated in API level 15

public boolean isBlob (int row, 
                int column)

This method was deprecated in API level 15.
Use getType(int, int) instead.

Returns true if the field at the specified row and column index has type Cursor.FIELD_TYPE_BLOB or Cursor.FIELD_TYPE_NULL.

Parameters
row	int: The zero-based row index. Value is 0 or greater
column	int: The zero-based column index. Value is 0 or greater

Returns
boolean	True if the field has type Cursor.FIELD_TYPE_BLOB or Cursor.FIELD_TYPE_NULL.

isFloat

Added in API level 5
Deprecated in API level 15

public boolean isFloat (int row, 
                int column)

This method was deprecated in API level 15.
Use getType(int, int) instead.

Returns true if the field at the specified row and column index has type Cursor.FIELD_TYPE_FLOAT.

Parameters
row	int: The zero-based row index. Value is 0 or greater
column	int: The zero-based column index. Value is 0 or greater

Returns
boolean	True if the field has type Cursor.FIELD_TYPE_FLOAT.

isLong

Added in API level 5
Deprecated in API level 15

public boolean isLong (int row, 
                int column)

This method was deprecated in API level 15.
Use getType(int, int) instead.

Returns true if the field at the specified row and column index has type Cursor.FIELD_TYPE_INTEGER.

Parameters
row	int: The zero-based row index. Value is 0 or greater
column	int: The zero-based column index. Value is 0 or greater

Returns
boolean	True if the field has type Cursor.FIELD_TYPE_INTEGER.

isNull

Added in API level 1
Deprecated in API level 15

public boolean isNull (int row, 
                int column)

This method was deprecated in API level 15.
Use getType(int, int) instead.

Returns true if the field at the specified row and column index has type Cursor.FIELD_TYPE_NULL.

Parameters
row	int: The zero-based row index. Value is 0 or greater
column	int: The zero-based column index. Value is 0 or greater

Returns
boolean	True if the field has type Cursor.FIELD_TYPE_NULL.

isString

Added in API level 5
Deprecated in API level 15

public boolean isString (int row, 
                int column)

This method was deprecated in API level 15.
Use getType(int, int) instead.

Returns true if the field at the specified row and column index has type Cursor.FIELD_TYPE_STRING or Cursor.FIELD_TYPE_NULL.

Parameters
row	int: The zero-based row index. Value is 0 or greater
column	int: The zero-based column index. Value is 0 or greater

Returns
boolean	True if the field has type Cursor.FIELD_TYPE_STRING or Cursor.FIELD_TYPE_NULL.

newFromParcel

Added in API level 1

public static CursorWindow newFromParcel (Parcel p)

Parameters
p	Parcel

Returns
CursorWindow

putBlob

Added in API level 1

public boolean putBlob (byte[] value, 
                int row, 
                int column)

Copies a byte array into the field at the specified row and column index.

Parameters
value	byte: The value to store.
row	int: The zero-based row index. Value is 0 or greater
column	int: The zero-based column index. Value is 0 or greater

Returns
boolean	True if successful.

putDouble

Added in API level 1

public boolean putDouble (double value, 
                int row, 
                int column)

Puts a double-precision floating point value into the field at the specified row and column index.

Parameters
value	double: The value to store.
row	int: The zero-based row index. Value is 0 or greater
column	int: The zero-based column index. Value is 0 or greater

Returns
boolean	True if successful.

putLong

Added in API level 1

public boolean putLong (long value, 
                int row, 
                int column)

Puts a long integer into the field at the specified row and column index.

Parameters
value	long: The value to store.
row	int: The zero-based row index. Value is 0 or greater
column	int: The zero-based column index. Value is 0 or greater

Returns
boolean	True if successful.

putNull

Added in API level 1

public boolean putNull (int row, 
                int column)

Puts a null value into the field at the specified row and column index.

Parameters
row	int: The zero-based row index. Value is 0 or greater
column	int: The zero-based column index. Value is 0 or greater

Returns
boolean	True if successful.

putString

Added in API level 1

public boolean putString (String value, 
                int row, 
                int column)

Copies a string into the field at the specified row and column index.

Parameters
value	String: The value to store.
row	int: The zero-based row index. Value is 0 or greater
column	int: The zero-based column index. Value is 0 or greater

Returns
boolean	True if successful.

setNumColumns

Added in API level 1

public boolean setNumColumns (int columnNum)

Sets the number of columns in this window.

This method must be called before any rows are added to the window, otherwise it will fail to set the number of columns if it differs from the current number of columns.

Parameters
columnNum	int: The new number of columns. Value is 0 or greater

Returns
boolean	True if successful.

setStartPosition

Added in API level 1

public void setStartPosition (int pos)

Sets the start position of this cursor window.

The start position is the zero-based index of the first row that this window contains relative to the entire result set of the Cursor.

Parameters
pos	int: The new zero-based start position. Value is 0 or greater

toString

Added in API level 1

public String toString ()

Returns a string representation of the object.

Returns
String	a string representation of the object.

writeToParcel

Added in API level 1

public void writeToParcel (Parcel dest, 
                int flags)

Flatten this object in to a Parcel.

Parameters
dest	Parcel: The Parcel in which the object should be written. This value cannot be null.
flags	int: Additional flags about how the object should be written. May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE. Value is either 0 or a combination of Parcelable.PARCELABLE_WRITE_RETURN_VALUE, and android.os.Parcelable.PARCELABLE_ELIDE_DUPLICATES

Protected methods

finalize

Added in API level 1

protected void finalize ()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the Java virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

Throws
Throwable

onAllReferencesReleased

Added in API level 1

protected void onAllReferencesReleased ()

Called when the last reference to the object was released by a call to releaseReference() or close().