public class CursorWindow extends SQLiteClosable implements Parcelable
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.
Parcelable.ClassLoaderCreator<T>, Parcelable.Creator<T>
Modifier and Type | Field and Description |
---|---|
static Parcelable.Creator<CursorWindow> |
CREATOR |
int |
mWindowPtr
The native CursorWindow object pointer.
|
CONTENTS_FILE_DESCRIPTOR, PARCELABLE_WRITE_RETURN_VALUE
Constructor and Description |
---|
CursorWindow(boolean localWindow)
Deprecated.
There is no longer a distinction between local and remote
cursor windows. Use the
CursorWindow(String) constructor instead. |
CursorWindow(String name)
Creates a new empty cursor window and gives it a name.
|
Modifier and Type | Method and Description |
---|---|
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's
marshalled representation.
|
protected void |
finalize()
Invoked when the garbage collector has detected that this instance is no longer reachable.
|
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 . |
String |
getName()
Gets the name of this cursor window, never null.
|
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)
Deprecated.
Use
getType(int, int) instead. |
boolean |
isFloat(int row,
int column)
Deprecated.
Use
getType(int, int) instead. |
boolean |
isLong(int row,
int column)
Deprecated.
Use
getType(int, int) instead. |
boolean |
isNull(int row,
int column)
Deprecated.
Use
getType(int, int) instead. |
boolean |
isString(int row,
int column)
Deprecated.
Use
getType(int, int) instead. |
static CursorWindow |
newFromParcel(Parcel p) |
protected void |
onAllReferencesReleased()
Called when the last reference to the object was released by
a call to
SQLiteClosable.releaseReference() or SQLiteClosable.close() . |
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 containing a concise, human-readable description of this
object.
|
void |
writeToParcel(Parcel dest,
int flags)
Flatten this object in to a Parcel.
|
acquireReference, close, onAllReferencesReleasedFromContainer, releaseReference, releaseReferenceFromContainer
public int mWindowPtr
public static final Parcelable.Creator<CursorWindow> CREATOR
public CursorWindow(String 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.
name
- The name of the cursor window, or null if none.@Deprecated public CursorWindow(boolean localWindow)
CursorWindow(String)
constructor instead.
The cursor initially has no rows or columns. Call setNumColumns(int)
to
set the number of columns before adding any rows to the cursor.
localWindow
- True if this window will be used in this process only,
false if it might be sent to another processes. This argument is ignored.protected void finalize() throws Throwable
Object
Note that objects that override finalize
are significantly more expensive than
objects that don't. Finalizers may be run a long time after the object is no longer
reachable, depending on memory pressure, so it's a bad idea to rely on them for cleanup.
Note also that finalizers are run on a single VM-wide finalizer thread,
so doing blocking work in a finalizer is a bad idea. A finalizer is usually only necessary
for a class that has a native peer and needs to call a native method to destroy that peer.
Even then, it's better to provide an explicit close
method (and implement
Closeable
), and insist that callers manually dispose of instances. This
works well for something like files, but less well for something like a BigInteger
where typical calling code would have to deal with lots of temporaries. Unfortunately,
code that creates lots of temporaries is the worst kind of code from the point of view of
the single finalizer thread.
If you must use finalizers, consider at least providing your own
ReferenceQueue
and having your own thread process that queue.
Unlike constructors, finalizers are not automatically chained. You are responsible for
calling super.finalize()
yourself.
Uncaught exceptions thrown by finalizers are ignored and do not terminate the finalizer thread. See Effective Java Item 7, "Avoid finalizers" for more.
public String getName()
public void clear()
The start position (getStartPosition()
), number of rows (getNumRows()
),
and number of columns in the cursor are all reset to zero.
public int getStartPosition()
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
.
public void setStartPosition(int pos)
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
.
pos
- The new zero-based start position.public int getNumRows()
public boolean setNumColumns(int columnNum)
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.
columnNum
- The new number of columns.public boolean allocRow()
public void freeLastRow()
@Deprecated public boolean isNull(int row, int column)
getType(int, int)
instead.Cursor.FIELD_TYPE_NULL
.row
- The zero-based row index.column
- The zero-based column index.Cursor.FIELD_TYPE_NULL
.@Deprecated public boolean isBlob(int row, int column)
getType(int, int)
instead.Cursor.FIELD_TYPE_BLOB
or Cursor.FIELD_TYPE_NULL
.row
- The zero-based row index.column
- The zero-based column index.Cursor.FIELD_TYPE_BLOB
or
Cursor.FIELD_TYPE_NULL
.@Deprecated public boolean isLong(int row, int column)
getType(int, int)
instead.Cursor.FIELD_TYPE_INTEGER
.row
- The zero-based row index.column
- The zero-based column index.Cursor.FIELD_TYPE_INTEGER
.@Deprecated public boolean isFloat(int row, int column)
getType(int, int)
instead.Cursor.FIELD_TYPE_FLOAT
.row
- The zero-based row index.column
- The zero-based column index.Cursor.FIELD_TYPE_FLOAT
.@Deprecated public boolean isString(int row, int column)
getType(int, int)
instead.Cursor.FIELD_TYPE_STRING
or Cursor.FIELD_TYPE_NULL
.row
- The zero-based row index.column
- The zero-based column index.Cursor.FIELD_TYPE_STRING
or Cursor.FIELD_TYPE_NULL
.public int getType(int row, int column)
The returned field types are:
row
- The zero-based row index.column
- The zero-based column index.public byte[] getBlob(int row, int column)
The result is determined as follows:
Cursor.FIELD_TYPE_NULL
, then the result
is null
.Cursor.FIELD_TYPE_BLOB
, then the result
is the blob value.Cursor.FIELD_TYPE_STRING
, then the result
is the array of bytes that make up the internal representation of the
string value.Cursor.FIELD_TYPE_INTEGER
or
Cursor.FIELD_TYPE_FLOAT
, then a SQLiteException
is thrown.row
- The zero-based row index.column
- The zero-based column index.public String getString(int row, int column)
The result is determined as follows:
Cursor.FIELD_TYPE_NULL
, then the result
is null
.Cursor.FIELD_TYPE_STRING
, then the result
is the string value.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
.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
.Cursor.FIELD_TYPE_BLOB
, then a
SQLiteException
is thrown.row
- The zero-based row index.column
- The zero-based column index.public void copyStringToBuffer(int row, int column, CharArrayBuffer buffer)
CharArrayBuffer
.
The buffer is populated as follows:
Cursor.FIELD_TYPE_NULL
, then the buffer
is set to an empty string.Cursor.FIELD_TYPE_STRING
, then the buffer
is set to the contents of the string.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
.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
.Cursor.FIELD_TYPE_BLOB
, then a
SQLiteException
is thrown.row
- The zero-based row index.column
- The zero-based column index.buffer
- The CharArrayBuffer
to hold the string. It is automatically
resized if the requested string is larger than the buffer's current capacity.public long getLong(int row, int column)
long
.
The result is determined as follows:
Cursor.FIELD_TYPE_NULL
, then the result
is 0L
.Cursor.FIELD_TYPE_STRING
, then the result
is the value obtained by parsing the string value with strtoll
.
Cursor.FIELD_TYPE_INTEGER
, then the result
is the long
value.Cursor.FIELD_TYPE_FLOAT
, then the result
is the floating-point value converted to a long
.Cursor.FIELD_TYPE_BLOB
, then a
SQLiteException
is thrown.row
- The zero-based row index.column
- The zero-based column index.long
.public double getDouble(int row, int column)
double
.
The result is determined as follows:
Cursor.FIELD_TYPE_NULL
, then the result
is 0.0
.Cursor.FIELD_TYPE_STRING
, then the result
is the value obtained by parsing the string value with strtod
.
Cursor.FIELD_TYPE_INTEGER
, then the result
is the integer value converted to a double
.Cursor.FIELD_TYPE_FLOAT
, then the result
is the double
value.Cursor.FIELD_TYPE_BLOB
, then a
SQLiteException
is thrown.row
- The zero-based row index.column
- The zero-based column index.double
.public short getShort(int row, int column)
short
.
The result is determined by invoking getLong(int, int)
and converting the
result to short
.
row
- The zero-based row index.column
- The zero-based column index.short
.public int getInt(int row, int column)
int
.
The result is determined by invoking getLong(int, int)
and converting the
result to int
.
row
- The zero-based row index.column
- The zero-based column index.int
.public float getFloat(int row, int column)
float
.
The result is determined by invoking getDouble(int, int)
and converting the
result to float
.
row
- The zero-based row index.column
- The zero-based column index.float
.public boolean putBlob(byte[] value, int row, int column)
value
- The value to store.row
- The zero-based row index.column
- The zero-based column index.public boolean putString(String value, int row, int column)
value
- The value to store.row
- The zero-based row index.column
- The zero-based column index.public boolean putLong(long value, int row, int column)
value
- The value to store.row
- The zero-based row index.column
- The zero-based column index.public boolean putDouble(double value, int row, int column)
value
- The value to store.row
- The zero-based row index.column
- The zero-based column index.public boolean putNull(int row, int column)
row
- The zero-based row index.column
- The zero-based column index.public static CursorWindow newFromParcel(Parcel p)
public int describeContents()
Parcelable
describeContents
in interface Parcelable
public void writeToParcel(Parcel dest, int flags)
Parcelable
writeToParcel
in interface Parcelable
dest
- The Parcel in which the object should be written.flags
- Additional flags about how the object should be written.
May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE
.protected void onAllReferencesReleased()
SQLiteClosable
SQLiteClosable.releaseReference()
or SQLiteClosable.close()
.onAllReferencesReleased
in class SQLiteClosable
public String toString()
Object
getClass().getName() + '@' + Integer.toHexString(hashCode())
See Writing a useful
toString
method
if you intend implementing your own toString
method.