AbstractWindowedCursor.java revision 0cde89f5f025b7826be009ebb9673b970e180e32
19066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project/* 29066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Copyright (C) 2006 The Android Open Source Project 39066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 49066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Licensed under the Apache License, Version 2.0 (the "License"); 59066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * you may not use this file except in compliance with the License. 69066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * You may obtain a copy of the License at 79066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 89066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * http://www.apache.org/licenses/LICENSE-2.0 99066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * 109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * Unless required by applicable law or agreed to in writing, software 119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * distributed under the License is distributed on an "AS IS" BASIS, 129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * See the License for the specific language governing permissions and 149066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * limitations under the License. 159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectpackage android.database; 189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 199066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project/** 209066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project * A base class for Cursors that store their data in {@link CursorWindow}s. 217ce745248d4de0e6543a559c93423df899832100Jeff Brown * <p> 22d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown * The cursor owns the cursor window it uses. When the cursor is closed, 23d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown * its window is also closed. Likewise, when the window used by the cursor is 24d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown * changed, its old window is closed. This policy of strict ownership ensures 25d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown * that cursor windows are not leaked. 26d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown * </p><p> 277ce745248d4de0e6543a559c93423df899832100Jeff Brown * Subclasses are responsible for filling the cursor window with data during 287ce745248d4de0e6543a559c93423df899832100Jeff Brown * {@link #onMove(int, int)}, allocating a new cursor window if necessary. 297ce745248d4de0e6543a559c93423df899832100Jeff Brown * During {@link #requery()}, the existing cursor window should be cleared and 307ce745248d4de0e6543a559c93423df899832100Jeff Brown * filled with new data. 317ce745248d4de0e6543a559c93423df899832100Jeff Brown * </p><p> 327ce745248d4de0e6543a559c93423df899832100Jeff Brown * If the contents of the cursor change or become invalid, the old window must be closed 337ce745248d4de0e6543a559c93423df899832100Jeff Brown * (because it is owned by the cursor) and set to null. 347ce745248d4de0e6543a559c93423df899832100Jeff Brown * </p> 359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 36f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamiltonpublic abstract class AbstractWindowedCursor extends AbstractCursor { 377ce745248d4de0e6543a559c93423df899832100Jeff Brown /** 387ce745248d4de0e6543a559c93423df899832100Jeff Brown * The cursor window owned by this cursor. 397ce745248d4de0e6543a559c93423df899832100Jeff Brown */ 407ce745248d4de0e6543a559c93423df899832100Jeff Brown protected CursorWindow mWindow; 417ce745248d4de0e6543a559c93423df899832100Jeff Brown 429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project @Override 43f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton public byte[] getBlob(int columnIndex) { 449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project checkPosition(); 459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return mWindow.getBlob(mPos, columnIndex); 469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project @Override 49f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton public String getString(int columnIndex) { 509066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project checkPosition(); 519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return mWindow.getString(mPos, columnIndex); 529066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 53f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton 549066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project @Override 55f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton public void copyStringToBuffer(int columnIndex, CharArrayBuffer buffer) { 569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project checkPosition(); 579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project mWindow.copyStringToBuffer(mPos, columnIndex, buffer); 589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 599066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 609066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project @Override 61f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton public short getShort(int columnIndex) { 629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project checkPosition(); 639066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return mWindow.getShort(mPos, columnIndex); 649066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project @Override 67f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton public int getInt(int columnIndex) { 689066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project checkPosition(); 699066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return mWindow.getInt(mPos, columnIndex); 709066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 719066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project @Override 73f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton public long getLong(int columnIndex) { 749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project checkPosition(); 759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return mWindow.getLong(mPos, columnIndex); 769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project @Override 79f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton public float getFloat(int columnIndex) { 809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project checkPosition(); 819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return mWindow.getFloat(mPos, columnIndex); 829066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 839066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 849066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project @Override 85f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton public double getDouble(int columnIndex) { 869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project checkPosition(); 879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return mWindow.getDouble(mPos, columnIndex); 889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project @Override 91f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton public boolean isNull(int columnIndex) { 929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project checkPosition(); 938b0dd7da360d70920a37802eb455ba41500d3b45Vasu Nori return mWindow.getType(mPos, columnIndex) == Cursor.FIELD_TYPE_NULL; 949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 959066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 96f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton /** 97f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton * @deprecated Use {@link #getType} 98f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton */ 99f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton @Deprecated 1008b0dd7da360d70920a37802eb455ba41500d3b45Vasu Nori public boolean isBlob(int columnIndex) { 1018b0dd7da360d70920a37802eb455ba41500d3b45Vasu Nori return getType(columnIndex) == Cursor.FIELD_TYPE_BLOB; 1029066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 1039066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 104f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton /** 105f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton * @deprecated Use {@link #getType} 106f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton */ 107f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton @Deprecated 1088b0dd7da360d70920a37802eb455ba41500d3b45Vasu Nori public boolean isString(int columnIndex) { 1098b0dd7da360d70920a37802eb455ba41500d3b45Vasu Nori return getType(columnIndex) == Cursor.FIELD_TYPE_STRING; 11003d9490758c9318cee6d14d3cc5007556dce92d0Fred Quintana } 11103d9490758c9318cee6d14d3cc5007556dce92d0Fred Quintana 112f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton /** 113f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton * @deprecated Use {@link #getType} 114f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton */ 115f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton @Deprecated 1168b0dd7da360d70920a37802eb455ba41500d3b45Vasu Nori public boolean isLong(int columnIndex) { 1178b0dd7da360d70920a37802eb455ba41500d3b45Vasu Nori return getType(columnIndex) == Cursor.FIELD_TYPE_INTEGER; 1188b0dd7da360d70920a37802eb455ba41500d3b45Vasu Nori } 11903d9490758c9318cee6d14d3cc5007556dce92d0Fred Quintana 120f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton /** 121f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton * @deprecated Use {@link #getType} 122f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton */ 123f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton @Deprecated 1248b0dd7da360d70920a37802eb455ba41500d3b45Vasu Nori public boolean isFloat(int columnIndex) { 1258b0dd7da360d70920a37802eb455ba41500d3b45Vasu Nori return getType(columnIndex) == Cursor.FIELD_TYPE_FLOAT; 12603d9490758c9318cee6d14d3cc5007556dce92d0Fred Quintana } 12703d9490758c9318cee6d14d3cc5007556dce92d0Fred Quintana 1288b0dd7da360d70920a37802eb455ba41500d3b45Vasu Nori @Override 129f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton public int getType(int columnIndex) { 13003d9490758c9318cee6d14d3cc5007556dce92d0Fred Quintana checkPosition(); 1318b0dd7da360d70920a37802eb455ba41500d3b45Vasu Nori return mWindow.getType(mPos, columnIndex); 13203d9490758c9318cee6d14d3cc5007556dce92d0Fred Quintana } 13303d9490758c9318cee6d14d3cc5007556dce92d0Fred Quintana 1349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project @Override 135f1a4a0a5b712963b77bf019886cf73cf6bc1b7b4Jeff Hamilton protected void checkPosition() { 1369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project super.checkPosition(); 1379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project if (mWindow == null) { 1398a358a7eedae45178f55c3b514a15e8ae4b10dbaVasu Nori throw new StaleDataException("Attempting to access a closed CursorWindow." + 1408a358a7eedae45178f55c3b514a15e8ae4b10dbaVasu Nori "Most probable cause: cursor is deactivated prior to calling this method."); 1419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 1429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 1439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project @Override 1459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public CursorWindow getWindow() { 1469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return mWindow; 1479066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 1487ce745248d4de0e6543a559c93423df899832100Jeff Brown 1499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1507ce745248d4de0e6543a559c93423df899832100Jeff Brown * Sets a new cursor window for the cursor to use. 1517ce745248d4de0e6543a559c93423df899832100Jeff Brown * <p> 1527ce745248d4de0e6543a559c93423df899832100Jeff Brown * The cursor takes ownership of the provided cursor window; the cursor window 1537ce745248d4de0e6543a559c93423df899832100Jeff Brown * will be closed when the cursor is closed or when the cursor adopts a new 1547ce745248d4de0e6543a559c93423df899832100Jeff Brown * cursor window. 1557ce745248d4de0e6543a559c93423df899832100Jeff Brown * </p><p> 1567ce745248d4de0e6543a559c93423df899832100Jeff Brown * If the cursor previously had a cursor window, then it is closed when the 1577ce745248d4de0e6543a559c93423df899832100Jeff Brown * new cursor window is assigned. 1587ce745248d4de0e6543a559c93423df899832100Jeff Brown * </p> 1597ce745248d4de0e6543a559c93423df899832100Jeff Brown * 1607ce745248d4de0e6543a559c93423df899832100Jeff Brown * @param window The new cursor window, typically a remote cursor window. 1619066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public void setWindow(CursorWindow window) { 1637ce745248d4de0e6543a559c93423df899832100Jeff Brown if (window != mWindow) { 1647ce745248d4de0e6543a559c93423df899832100Jeff Brown closeWindow(); 1657ce745248d4de0e6543a559c93423df899832100Jeff Brown mWindow = window; 1669066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 1679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 1687ce745248d4de0e6543a559c93423df899832100Jeff Brown 1697ce745248d4de0e6543a559c93423df899832100Jeff Brown /** 1707ce745248d4de0e6543a559c93423df899832100Jeff Brown * Returns true if the cursor has an associated cursor window. 1717ce745248d4de0e6543a559c93423df899832100Jeff Brown * 1727ce745248d4de0e6543a559c93423df899832100Jeff Brown * @return True if the cursor has an associated cursor window. 1737ce745248d4de0e6543a559c93423df899832100Jeff Brown */ 1749066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project public boolean hasWindow() { 1759066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return mWindow != null; 1769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 1779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project /** 1797ce745248d4de0e6543a559c93423df899832100Jeff Brown * Closes the cursor window and sets {@link #mWindow} to null. 1807ce745248d4de0e6543a559c93423df899832100Jeff Brown * @hide 1819066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project */ 1827ce745248d4de0e6543a559c93423df899832100Jeff Brown protected void closeWindow() { 1837ce745248d4de0e6543a559c93423df899832100Jeff Brown if (mWindow != null) { 1847ce745248d4de0e6543a559c93423df899832100Jeff Brown mWindow.close(); 1857ce745248d4de0e6543a559c93423df899832100Jeff Brown mWindow = null; 1867ce745248d4de0e6543a559c93423df899832100Jeff Brown } 1877ce745248d4de0e6543a559c93423df899832100Jeff Brown } 188d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown 189d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown /** 190d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown * If there is a window, clear it. 191d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown * Otherwise, creates a local window. 1920cde89f5f025b7826be009ebb9673b970e180e32Jeff Brown * 1930cde89f5f025b7826be009ebb9673b970e180e32Jeff Brown * @param name The window name. 194d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown * @hide 195d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown */ 1960cde89f5f025b7826be009ebb9673b970e180e32Jeff Brown protected void clearOrCreateLocalWindow(String name) { 197d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown if (mWindow == null) { 198d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown // If there isn't a window set already it will only be accessed locally 1990cde89f5f025b7826be009ebb9673b970e180e32Jeff Brown mWindow = new CursorWindow(name, true /* the window is local only */); 200d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown } else { 201d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown mWindow.clear(); 202d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown } 203d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown } 204d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown 205d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown /** @hide */ 206d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown @Override 207d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown protected void onDeactivateOrClose() { 208d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown super.onDeactivateOrClose(); 209d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown closeWindow(); 210d2183654e03d589b120467f4e98da1b178ceeadbJeff Brown } 2119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project} 212