Home | History | Annotate | Download | only in database
      1 /*
      2  * Copyright (C) 2006 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package android.database;
     18 
     19 /**
     20  * A base class for Cursors that store their data in {@link CursorWindow}s.
     21  * <p>
     22  * The cursor owns the cursor window it uses.  When the cursor is closed,
     23  * its window is also closed.  Likewise, when the window used by the cursor is
     24  * changed, its old window is closed.  This policy of strict ownership ensures
     25  * that cursor windows are not leaked.
     26  * </p><p>
     27  * Subclasses are responsible for filling the cursor window with data during
     28  * {@link #onMove(int, int)}, allocating a new cursor window if necessary.
     29  * During {@link #requery()}, the existing cursor window should be cleared and
     30  * filled with new data.
     31  * </p><p>
     32  * If the contents of the cursor change or become invalid, the old window must be closed
     33  * (because it is owned by the cursor) and set to null.
     34  * </p>
     35  */
     36 public abstract class AbstractWindowedCursor extends AbstractCursor {
     37     /**
     38      * The cursor window owned by this cursor.
     39      */
     40     protected CursorWindow mWindow;
     41 
     42     @Override
     43     public byte[] getBlob(int columnIndex) {
     44         checkPosition();
     45         return mWindow.getBlob(mPos, columnIndex);
     46     }
     47 
     48     @Override
     49     public String getString(int columnIndex) {
     50         checkPosition();
     51         return mWindow.getString(mPos, columnIndex);
     52     }
     53 
     54     @Override
     55     public void copyStringToBuffer(int columnIndex, CharArrayBuffer buffer) {
     56         checkPosition();
     57         mWindow.copyStringToBuffer(mPos, columnIndex, buffer);
     58     }
     59 
     60     @Override
     61     public short getShort(int columnIndex) {
     62         checkPosition();
     63         return mWindow.getShort(mPos, columnIndex);
     64     }
     65 
     66     @Override
     67     public int getInt(int columnIndex) {
     68         checkPosition();
     69         return mWindow.getInt(mPos, columnIndex);
     70     }
     71 
     72     @Override
     73     public long getLong(int columnIndex) {
     74         checkPosition();
     75         return mWindow.getLong(mPos, columnIndex);
     76     }
     77 
     78     @Override
     79     public float getFloat(int columnIndex) {
     80         checkPosition();
     81         return mWindow.getFloat(mPos, columnIndex);
     82     }
     83 
     84     @Override
     85     public double getDouble(int columnIndex) {
     86         checkPosition();
     87         return mWindow.getDouble(mPos, columnIndex);
     88     }
     89 
     90     @Override
     91     public boolean isNull(int columnIndex) {
     92         checkPosition();
     93         return mWindow.getType(mPos, columnIndex) == Cursor.FIELD_TYPE_NULL;
     94     }
     95 
     96     /**
     97      * @deprecated Use {@link #getType}
     98      */
     99     @Deprecated
    100     public boolean isBlob(int columnIndex) {
    101         return getType(columnIndex) == Cursor.FIELD_TYPE_BLOB;
    102     }
    103 
    104     /**
    105      * @deprecated Use {@link #getType}
    106      */
    107     @Deprecated
    108     public boolean isString(int columnIndex) {
    109         return getType(columnIndex) == Cursor.FIELD_TYPE_STRING;
    110     }
    111 
    112     /**
    113      * @deprecated Use {@link #getType}
    114      */
    115     @Deprecated
    116     public boolean isLong(int columnIndex) {
    117         return getType(columnIndex) == Cursor.FIELD_TYPE_INTEGER;
    118     }
    119 
    120     /**
    121      * @deprecated Use {@link #getType}
    122      */
    123     @Deprecated
    124     public boolean isFloat(int columnIndex) {
    125         return getType(columnIndex) == Cursor.FIELD_TYPE_FLOAT;
    126     }
    127 
    128     @Override
    129     public int getType(int columnIndex) {
    130         checkPosition();
    131         return mWindow.getType(mPos, columnIndex);
    132     }
    133 
    134     @Override
    135     protected void checkPosition() {
    136         super.checkPosition();
    137 
    138         if (mWindow == null) {
    139             throw new StaleDataException("Attempting to access a closed CursorWindow." +
    140                     "Most probable cause: cursor is deactivated prior to calling this method.");
    141         }
    142     }
    143 
    144     @Override
    145     public CursorWindow getWindow() {
    146         return mWindow;
    147     }
    148 
    149     /**
    150      * Sets a new cursor window for the cursor to use.
    151      * <p>
    152      * The cursor takes ownership of the provided cursor window; the cursor window
    153      * will be closed when the cursor is closed or when the cursor adopts a new
    154      * cursor window.
    155      * </p><p>
    156      * If the cursor previously had a cursor window, then it is closed when the
    157      * new cursor window is assigned.
    158      * </p>
    159      *
    160      * @param window The new cursor window, typically a remote cursor window.
    161      */
    162     public void setWindow(CursorWindow window) {
    163         if (window != mWindow) {
    164             closeWindow();
    165             mWindow = window;
    166         }
    167     }
    168 
    169     /**
    170      * Returns true if the cursor has an associated cursor window.
    171      *
    172      * @return True if the cursor has an associated cursor window.
    173      */
    174     public boolean hasWindow() {
    175         return mWindow != null;
    176     }
    177 
    178     /**
    179      * Closes the cursor window and sets {@link #mWindow} to null.
    180      * @hide
    181      */
    182     protected void closeWindow() {
    183         if (mWindow != null) {
    184             mWindow.close();
    185             mWindow = null;
    186         }
    187     }
    188 
    189     /**
    190      * If there is a window, clear it.
    191      * Otherwise, creates a new window.
    192      *
    193      * @param name The window name.
    194      * @hide
    195      */
    196     protected void clearOrCreateWindow(String name) {
    197         if (mWindow == null) {
    198             mWindow = new CursorWindow(name);
    199         } else {
    200             mWindow.clear();
    201         }
    202     }
    203 
    204     /** @hide */
    205     @Override
    206     protected void onDeactivateOrClose() {
    207         super.onDeactivateOrClose();
    208         closeWindow();
    209     }
    210 }
    211