Clean up CursorWindow lifetime.

Bug: 5332296

Removed dead code in SQLiteCursor related to the use of a background
query thread.  This code could result in CursorWindows being modified
concurrently or used after free.  This code is broken, unused and
is just in the way.

Added comments to explain how CursorWindow ownership is
supposed to work for AbstractWindowedCursors.  (There are still cases
where cursor windows get dropped on the floor without being closed.
Those will be taken care of in a subsequent patch.)

Cleaned up SQLiteQuery.fillWindow to eliminate duplicate code and
remove bits that were only needed for background loading, like
returning -1.

Change-Id: I03e8e2e73ff0c11df76d63f57df4c5ada06ae1cb

Author: Jeff Brown

core/java/android/database/AbstractCursor.java

@@ -64,7 +64,10 @@ public byte[] getBlob(int column) {
     /* Methods that may optionally be implemented by subclasses */
 
     /**
-     * returns a pre-filled window, return NULL if no such window
+     * If the cursor is backed by a {@link CursorWindow}, returns a pre-filled
+     * window with the contents of the cursor, otherwise null.
+     *
+     * @return The pre-filled window that backs this cursor, or null if none.
      */
     public CursorWindow getWindow() {
         return null;

core/java/android/database/AbstractWindowedCursor.java

@@ -18,8 +18,22 @@
 
 /**
  * A base class for Cursors that store their data in {@link CursorWindow}s.
+ * <p>
+ * Subclasses are responsible for filling the cursor window with data during
+ * {@link #onMove(int, int)}, allocating a new cursor window if necessary.
+ * During {@link #requery()}, the existing cursor window should be cleared and
+ * filled with new data.
+ * </p><p>
+ * If the contents of the cursor change or become invalid, the old window must be closed
+ * (because it is owned by the cursor) and set to null.
+ * </p>
  */
 public abstract class AbstractWindowedCursor extends AbstractCursor {
+    /**
+     * The cursor window owned by this cursor.
+     */
+    protected CursorWindow mWindow;
+
     @Override
     public byte[] getBlob(int columnIndex) {
         checkPosition();
@@ -126,25 +140,44 @@ protected void checkPosition() {
     public CursorWindow getWindow() {
         return mWindow;
     }
-    
+
     /**
-     * Set a new cursor window to cursor, usually set a remote cursor window
-     * @param window cursor window
+     * Sets a new cursor window for the cursor to use.
+     * <p>
+     * The cursor takes ownership of the provided cursor window; the cursor window
+     * will be closed when the cursor is closed or when the cursor adopts a new
+     * cursor window.
+     * </p><p>
+     * If the cursor previously had a cursor window, then it is closed when the
+     * new cursor window is assigned.
+     * </p>
+     *
+     * @param window The new cursor window, typically a remote cursor window.
      */
     public void setWindow(CursorWindow window) {
-        if (mWindow != null) {
-            mWindow.close();
+        if (window != mWindow) {
+            closeWindow();
+            mWindow = window;
         }
-        mWindow = window;
     }
-    
+
+    /**
+     * Returns true if the cursor has an associated cursor window.
+     *
+     * @return True if the cursor has an associated cursor window.
+     */
     public boolean hasWindow() {
         return mWindow != null;
     }
 
     /**
-     * This needs be updated in {@link #onMove} by subclasses, and
-     * needs to be set to NULL when the contents of the cursor change.
+     * Closes the cursor window and sets {@link #mWindow} to null.
+     * @hide
      */
-    protected CursorWindow mWindow;
+    protected void closeWindow() {
+        if (mWindow != null) {
+            mWindow.close();
+            mWindow = null;
+        }
+    }
 }

core/java/android/database/BulkCursorToCursorAdaptor.java

@@ -154,10 +154,7 @@ public boolean requery() {
                     false /* the window will be accessed across processes */));
             if (mCount != -1) {
                 mPos = -1;
-                if (mWindow != null) {
-                    mWindow.close();
-                    mWindow = null;
-                }
+                closeWindow();
 
                 // super.requery() will call onChanged. Do it here instead of relying on the
                 // observer from the far side so that observers can see a correct value for mCount

core/java/android/database/CursorWindow.java

@@ -105,8 +105,12 @@ private CursorWindow(Parcel source) {
     }
 
     @Override
-    protected void finalize() {
-        dispose();
+    protected void finalize() throws Throwable {
+        try {
+            dispose();
+        } finally {
+            super.finalize();
+        }
     }
 
     private void dispose() {
@@ -145,21 +149,25 @@ public void clear() {
 
     /**
      * Gets the start position of this cursor window.
-     * The start position is the index of the first row that this window contains
+     * <p>
+     * The start position is the zero-based index of the first row that this window contains
      * relative to the entire result set of the {@link Cursor}.
+     * </p>
      *
-     * @return The start position.
+     * @return The zero-based start position.
      */
     public int getStartPosition() {
         return mStartPos;
     }
 
     /**
      * Sets the start position of this cursor window.
-     * The start position is the index of the first row that this window contains
+     * <p>
+     * The start position is the zero-based index of the first row that this window contains
      * relative to the entire result set of the {@link Cursor}.
+     * </p>
      *
-     * @param pos The new start position.
+     * @param pos The new zero-based start position.
      */
     public void setStartPosition(int pos) {
         mStartPos = pos;

core/java/android/database/CursorWrapper.java

@@ -33,7 +33,9 @@ public CursorWrapper(Cursor cursor) {
     }
 
     /**
-     * @return the wrapped cursor
+     * Gets the underlying cursor that is wrapped by this instance.
+     *
+     * @return The wrapped cursor.
      */
     public Cursor getWrappedCursor() {
         return mCursor;