Merge changes Idbfeb3cc,I03e8e2e7,Iff9eed78

* changes:
  Fix regression in CursorWindow.getString() Bug: 5332296
  Clean up CursorWindow lifetime. Bug: 5332296
  Fix regression in CursorWindow.copyStingToBuffer. Bug: 5332296

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;