Class AbstractCursor
- java.lang.Object
-
- android.database.AbstractCursor
-
- All Implemented Interfaces:
CrossProcessCursor,Cursor,Closeable,AutoCloseable
- Direct Known Subclasses:
AbstractWindowedCursor,MatrixCursor,MergeCursor
public abstract class AbstractCursor extends Object implements CrossProcessCursor
This is an abstract cursor class that handles a lot of the common code that all cursors need to deal with and is provided for convenience reasons.
-
-
Field Summary
Fields Modifier and Type Field Description protected booleanmClosedDeprecated.UseisClosed()instead.protected LongmCurrentRowIDprotected intmPosDeprecated.UsegetPosition()instead.protected intmRowIdColumnIndexprotected HashMap<Long,Map<String,Object>>mUpdatedRows-
Fields inherited from interface android.database.Cursor
FIELD_TYPE_BLOB, FIELD_TYPE_FLOAT, FIELD_TYPE_INTEGER, FIELD_TYPE_NULL, FIELD_TYPE_STRING
-
-
Constructor Summary
Constructors Constructor Description AbstractCursor()
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description protected voidcheckPosition()This function throws CursorIndexOutOfBoundsException if the cursor position is out of bounds.voidclose()Closes the Cursor, releasing all of its resources and making it completely invalid.voidcopyStringToBuffer(int columnIndex, CharArrayBuffer buffer)Retrieves the requested column text and stores it in the buffer provided.voiddeactivate()Deactivates the Cursor, making all calls on it fail untilCursor.requery()is called.voidfillWindow(int position, CursorWindow window)Copies cursor data into the window.protected voidfinalize()Invoked when the garbage collector has detected that this instance is no longer reachable.byte[]getBlob(int column)Returns the value of the requested column as a byte array.intgetColumnCount()Return total number of columnsintgetColumnIndex(String columnName)Returns the zero-based index for the given column name, or -1 if the column doesn't exist.intgetColumnIndexOrThrow(String columnName)Returns the zero-based index for the given column name, or throwsIllegalArgumentExceptionif the column doesn't exist.StringgetColumnName(int columnIndex)Returns the column name at the given zero-based column index.abstract String[]getColumnNames()Returns a string array holding the names of all of the columns in the result set in the order in which they were listed in the result.abstract intgetCount()Returns the numbers of rows in the cursor.abstract doublegetDouble(int column)Returns the value of the requested column as a double.BundlegetExtras()Returns a bundle of extra values.abstract floatgetFloat(int column)Returns the value of the requested column as a float.abstract intgetInt(int column)Returns the value of the requested column as an int.abstract longgetLong(int column)Returns the value of the requested column as a long.intgetPosition()Returns the current position of the cursor in the row set.abstract shortgetShort(int column)Returns the value of the requested column as a short.abstract StringgetString(int column)Returns the value of the requested column as a String.intgetType(int column)Returns data type of the given column's value.protected ObjectgetUpdatedField(int columnIndex)Deprecated.Always returns null since Cursors do not support updating rowsbooleangetWantsAllOnMoveCalls()Specifies a content URI to watch for changes.CursorWindowgetWindow()If the cursor is backed by aCursorWindow, returns a pre-filled window with the contents of the cursor, otherwise null.booleanisAfterLast()Returns whether the cursor is pointing to the position after the last row.booleanisBeforeFirst()Returns whether the cursor is pointing to the position before the first row.booleanisClosed()return true if the cursor is closedprotected booleanisFieldUpdated(int columnIndex)Deprecated.Always returns false since Cursors do not support updating rowsbooleanisFirst()Returns whether the cursor is pointing to the first row.booleanisLast()Returns whether the cursor is pointing to the last row.abstract booleanisNull(int column)Returnstrueif the value in the indicated column is null.booleanmove(int offset)Move the cursor by a relative amount, forward or backward, from the current position.booleanmoveToFirst()Move the cursor to the first row.booleanmoveToLast()Move the cursor to the last row.booleanmoveToNext()Move the cursor to the next row.booleanmoveToPosition(int position)Move the cursor to an absolute position.booleanmoveToPrevious()Move the cursor to the previous row.protected voidonChange(boolean selfChange)Subclasses must call this method when they finish committing updates to notify all observers.protected voidonDeactivateOrClose()booleanonMove(int oldPosition, int newPosition)This function is called every time the cursor is successfully scrolled to a new position, giving the subclass a chance to update any state it may have.voidregisterDataSetObserver(DataSetObserver observer)Register an observer that is called when changes happen to the contents of the this cursors data set, for example, when the data set is changed viaCursor.requery(),Cursor.deactivate(), orCursor.close().booleanrequery()Performs the query that created the cursor again, refreshing its contents.Bundlerespond(Bundle extras)This is an out-of-band way for the the user of a cursor to communicate with the cursor.voidsetExtras(Bundle extras)Sets aBundlethat will be returned byCursor.getExtras().voidunregisterDataSetObserver(DataSetObserver observer)Unregister an observer that has previously been registered with this cursor via#registerContentObserver.
-
-
-
Field Detail
-
mRowIdColumnIndex
protected int mRowIdColumnIndex
-
mCurrentRowID
protected Long mCurrentRowID
-
mPos
@Deprecated protected int mPos
Deprecated.UsegetPosition()instead.
-
mClosed
@Deprecated protected boolean mClosed
Deprecated.UseisClosed()instead.
-
-
Method Detail
-
getCount
public abstract int getCount()
Description copied from interface:CursorReturns the numbers of rows in the cursor.
-
getColumnNames
public abstract String[] getColumnNames()
Description copied from interface:CursorReturns a string array holding the names of all of the columns in the result set in the order in which they were listed in the result.- Specified by:
getColumnNamesin interfaceCursor- Returns:
- the names of the columns returned in this query.
-
getString
public abstract String getString(int column)
Description copied from interface:CursorReturns the value of the requested column as a String.The result and whether this method throws an exception when the column value is null or the column type is not a string type is implementation-defined.
-
getShort
public abstract short getShort(int column)
Description copied from interface:CursorReturns the value of the requested column as a short.The result and whether this method throws an exception when the column value is null, the column type is not an integral type, or the integer value is outside the range [
Short.MIN_VALUE,Short.MAX_VALUE] is implementation-defined.
-
getInt
public abstract int getInt(int column)
Description copied from interface:CursorReturns the value of the requested column as an int.The result and whether this method throws an exception when the column value is null, the column type is not an integral type, or the integer value is outside the range [
Integer.MIN_VALUE,Integer.MAX_VALUE] is implementation-defined.
-
getLong
public abstract long getLong(int column)
Description copied from interface:CursorReturns the value of the requested column as a long.The result and whether this method throws an exception when the column value is null, the column type is not an integral type, or the integer value is outside the range [
Long.MIN_VALUE,Long.MAX_VALUE] is implementation-defined.
-
getFloat
public abstract float getFloat(int column)
Description copied from interface:CursorReturns the value of the requested column as a float.The result and whether this method throws an exception when the column value is null, the column type is not a floating-point type, or the floating-point value is not representable as a
floatvalue is implementation-defined.
-
getDouble
public abstract double getDouble(int column)
Description copied from interface:CursorReturns the value of the requested column as a double.The result and whether this method throws an exception when the column value is null, the column type is not a floating-point type, or the floating-point value is not representable as a
doublevalue is implementation-defined.
-
isNull
public abstract boolean isNull(int column)
Description copied from interface:CursorReturnstrueif the value in the indicated column is null.
-
getType
public int getType(int column)
Description copied from interface:CursorReturns data type of the given column's value. The preferred type of the column is returned but the data may be converted to other types as documented in the get-type methods such asCursor.getInt(int),Cursor.getFloat(int)etc.Returned column types are
-
getBlob
public byte[] getBlob(int column)
Description copied from interface:CursorReturns the value of the requested column as a byte array.The result and whether this method throws an exception when the column value is null or the column type is not a blob type is implementation-defined.
-
getWindow
public CursorWindow getWindow()
If the cursor is backed by aCursorWindow, returns a pre-filled window with the contents of the cursor, otherwise null.- Specified by:
getWindowin interfaceCrossProcessCursor- Returns:
- The pre-filled window that backs this cursor, or null if none.
-
getColumnCount
public int getColumnCount()
Description copied from interface:CursorReturn total number of columns- Specified by:
getColumnCountin interfaceCursor- Returns:
- number of columns
-
deactivate
public void deactivate()
Description copied from interface:CursorDeactivates the Cursor, making all calls on it fail untilCursor.requery()is called. Inactive Cursors use fewer resources than active Cursors. CallingCursor.requery()will make the cursor active again.- Specified by:
deactivatein interfaceCursor
-
onDeactivateOrClose
protected void onDeactivateOrClose()
-
requery
public boolean requery()
Description copied from interface:CursorPerforms the query that created the cursor again, refreshing its contents. This may be done at any time, including after a call toCursor.deactivate(). Since this method could execute a query on the database and potentially take a while, it could cause ANR if it is called on Main (UI) thread. A warning is printed if this method is being executed on Main thread.
-
isClosed
public boolean isClosed()
Description copied from interface:Cursorreturn true if the cursor is closed
-
close
public void close()
Description copied from interface:CursorCloses the Cursor, releasing all of its resources and making it completely invalid. UnlikeCursor.deactivate()a call toCursor.requery()will not make the Cursor valid again.
-
onMove
public boolean onMove(int oldPosition, int newPosition)This function is called every time the cursor is successfully scrolled to a new position, giving the subclass a chance to update any state it may have. If it returns false the move function will also do so and the cursor will scroll to the beforeFirst position.- Specified by:
onMovein interfaceCrossProcessCursor- Parameters:
oldPosition- the position that we're moving fromnewPosition- the position that we're moving to- Returns:
- true if the move is successful, false otherwise
-
copyStringToBuffer
public void copyStringToBuffer(int columnIndex, CharArrayBuffer buffer)Description copied from interface:CursorRetrieves the requested column text and stores it in the buffer provided. If the buffer size is not sufficient, a new char buffer will be allocated and assigned to CharArrayBuffer.data- Specified by:
copyStringToBufferin interfaceCursor- Parameters:
columnIndex- the zero-based index of the target column. if the target column is null, return bufferbuffer- the buffer to copy the text into.
-
getPosition
public final int getPosition()
Description copied from interface:CursorReturns the current position of the cursor in the row set. The value is zero-based. When the row set is first returned the cursor will be at positon -1, which is before the first row. After the last row is returned another call to next() will leave the cursor past the last entry, at a position of count().- Specified by:
getPositionin interfaceCursor- Returns:
- the current cursor position.
-
moveToPosition
public final boolean moveToPosition(int position)
Description copied from interface:CursorMove the cursor to an absolute position. The valid range of values is -1 <= position <= count.This method will return true if the request destination was reachable, otherwise, it returns false.
- Specified by:
moveToPositionin interfaceCursor- Parameters:
position- the zero-based position to move to.- Returns:
- whether the requested move fully succeeded.
-
fillWindow
public void fillWindow(int position, CursorWindow window)Description copied from interface:CrossProcessCursorCopies cursor data into the window.Clears the window and fills it with data beginning at the requested row position until all of the data in the cursor is exhausted or the window runs out of space.
The filled window uses the same row indices as the original cursor. For example, if you fill a window starting from row 5 from the cursor, you can query the contents of row 5 from the window just by asking it for row 5 because there is a direct correspondence between the row indices used by the cursor and the window.
The current position of the cursor, as returned by
Cursor.getPosition(), is not changed by this method.- Specified by:
fillWindowin interfaceCrossProcessCursor- Parameters:
position- The zero-based index of the first row to copy into the window.window- The window to fill.
-
move
public final boolean move(int offset)
Description copied from interface:CursorMove the cursor by a relative amount, forward or backward, from the current position. Positive offsets move forwards, negative offsets move backwards. If the final position is outside of the bounds of the result set then the resultant position will be pinned to -1 or count() depending on whether the value is off the front or end of the set, respectively.This method will return true if the requested destination was reachable, otherwise, it returns false. For example, if the cursor is at currently on the second entry in the result set and move(-5) is called, the position will be pinned at -1, and false will be returned.
-
moveToFirst
public final boolean moveToFirst()
Description copied from interface:CursorMove the cursor to the first row.This method will return false if the cursor is empty.
- Specified by:
moveToFirstin interfaceCursor- Returns:
- whether the move succeeded.
-
moveToLast
public final boolean moveToLast()
Description copied from interface:CursorMove the cursor to the last row.This method will return false if the cursor is empty.
- Specified by:
moveToLastin interfaceCursor- Returns:
- whether the move succeeded.
-
moveToNext
public final boolean moveToNext()
Description copied from interface:CursorMove the cursor to the next row.This method will return false if the cursor is already past the last entry in the result set.
- Specified by:
moveToNextin interfaceCursor- Returns:
- whether the move succeeded.
-
moveToPrevious
public final boolean moveToPrevious()
Description copied from interface:CursorMove the cursor to the previous row.This method will return false if the cursor is already before the first entry in the result set.
- Specified by:
moveToPreviousin interfaceCursor- Returns:
- whether the move succeeded.
-
isFirst
public final boolean isFirst()
Description copied from interface:CursorReturns whether the cursor is pointing to the first row.
-
isLast
public final boolean isLast()
Description copied from interface:CursorReturns whether the cursor is pointing to the last row.
-
isBeforeFirst
public final boolean isBeforeFirst()
Description copied from interface:CursorReturns whether the cursor is pointing to the position before the first row.- Specified by:
isBeforeFirstin interfaceCursor- Returns:
- whether the cursor is before the first result.
-
isAfterLast
public final boolean isAfterLast()
Description copied from interface:CursorReturns whether the cursor is pointing to the position after the last row.- Specified by:
isAfterLastin interfaceCursor- Returns:
- whether the cursor is after the last result.
-
getColumnIndex
public int getColumnIndex(String columnName)
Description copied from interface:CursorReturns the zero-based index for the given column name, or -1 if the column doesn't exist. If you expect the column to exist useCursor.getColumnIndexOrThrow(String)instead, which will make the error more clear.- Specified by:
getColumnIndexin interfaceCursor- Parameters:
columnName- the name of the target column.- Returns:
- the zero-based column index for the given column name, or -1 if the column name does not exist.
- See Also:
Cursor.getColumnIndexOrThrow(String)
-
getColumnIndexOrThrow
public int getColumnIndexOrThrow(String columnName)
Description copied from interface:CursorReturns the zero-based index for the given column name, or throwsIllegalArgumentExceptionif the column doesn't exist. If you're not sure if a column will exist or not useCursor.getColumnIndex(String)and check for -1, which is more efficient than catching the exceptions.- Specified by:
getColumnIndexOrThrowin interfaceCursor- Parameters:
columnName- the name of the target column.- Returns:
- the zero-based column index for the given column name
- See Also:
Cursor.getColumnIndex(String)
-
getColumnName
public String getColumnName(int columnIndex)
Description copied from interface:CursorReturns the column name at the given zero-based column index.- Specified by:
getColumnNamein interfaceCursor- Parameters:
columnIndex- the zero-based index of the target column.- Returns:
- the column name for the given column index.
-
registerDataSetObserver
public void registerDataSetObserver(DataSetObserver observer)
Description copied from interface:CursorRegister an observer that is called when changes happen to the contents of the this cursors data set, for example, when the data set is changed viaCursor.requery(),Cursor.deactivate(), orCursor.close().- Specified by:
registerDataSetObserverin interfaceCursor- Parameters:
observer- the object that gets notified when the cursors data set changes.- See Also:
Cursor.unregisterDataSetObserver(DataSetObserver)
-
unregisterDataSetObserver
public void unregisterDataSetObserver(DataSetObserver observer)
Description copied from interface:CursorUnregister an observer that has previously been registered with this cursor via#registerContentObserver.- Specified by:
unregisterDataSetObserverin interfaceCursor- Parameters:
observer- the object to unregister.- See Also:
Cursor.registerDataSetObserver(DataSetObserver)
-
onChange
protected void onChange(boolean selfChange)
Subclasses must call this method when they finish committing updates to notify all observers.- Parameters:
selfChange-
-
getWantsAllOnMoveCalls
public boolean getWantsAllOnMoveCalls()
Specifies a content URI to watch for changes.- Specified by:
getWantsAllOnMoveCallsin interfaceCursor- Parameters:
cr- The content resolver from the caller's context.notifyUri- The URI to watch for changes. This can be a specific row URI, or a base URI for a whole class of content.- Returns:
- whether all cursor movement should result in a call to onMove().
-
setExtras
public void setExtras(Bundle extras)
Description copied from interface:CursorSets aBundlethat will be returned byCursor.getExtras().
-
getExtras
public Bundle getExtras()
Description copied from interface:CursorReturns a bundle of extra values. This is an optional way for cursors to provide out-of-band metadata to their users. One use of this is for reporting on the progress of network requests that are required to fetch data for the cursor.These values may only change when requery is called.
- Specified by:
getExtrasin interfaceCursor- Returns:
- cursor-defined values, or
Bundle.EMPTYif there are no values. Nevernull.
-
respond
public Bundle respond(Bundle extras)
Description copied from interface:CursorThis is an out-of-band way for the the user of a cursor to communicate with the cursor. The structure of each bundle is entirely defined by the cursor.One use of this is to tell a cursor that it should retry its network request after it reported an error.
- Specified by:
respondin interfaceCursor- Parameters:
extras- extra values, orBundle.EMPTY. Nevernull.- Returns:
- extra values, or
Bundle.EMPTY. Nevernull.
-
isFieldUpdated
@Deprecated protected boolean isFieldUpdated(int columnIndex)
Deprecated.Always returns false since Cursors do not support updating rows
-
getUpdatedField
@Deprecated protected Object getUpdatedField(int columnIndex)
Deprecated.Always returns null since Cursors do not support updating rows
-
checkPosition
protected void checkPosition()
This function throws CursorIndexOutOfBoundsException if the cursor position is out of bounds. Subclass implementations of the get functions should call this before attempting to retrieve data.- Throws:
CursorIndexOutOfBoundsException
-
finalize
protected void finalize()
Description copied from class:ObjectInvoked when the garbage collector has detected that this instance is no longer reachable. The default implementation does nothing, but this method can be overridden to free resources.Note that objects that override
finalizeare 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 explicitclosemethod (and implementCloseable), and insist that callers manually dispose of instances. This works well for something like files, but less well for something like aBigIntegerwhere 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
ReferenceQueueand 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.
-
-