apps/AndroidSupportV2/src/android/support/v2/content/CursorLoader.java

   1 /*
   2  * Copyright (C) 2011 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.support.v2.content;
  18
  19 import android.content.Context;
  20 import android.database.ContentObserver;
  21 import android.database.Cursor;
  22 import android.net.Uri;
  23
  24 import java.io.FileDescriptor;
  25 import java.io.PrintWriter;
  26 import java.util.Arrays;
  27
  28 /**
  29  * Static library support version of the framework's {@link android.content.CursorLoader}.
  30  * Used to write apps that run on platforms prior to Android 3.0.  When running
  31  * on Android 3.0 or above, this implementation is still used; it does not try
  32  * to switch to the framework's implementation.  See the framework SDK
  33  * documentation for a class overview.
  34  */
  35 public class CursorLoader extends AsyncTaskLoader<Cursor> {
  36     final ForceLoadContentObserver mObserver;
  37
  38     Uri mUri;
  39     String[] mProjection;
  40     String mSelection;
  41     String[] mSelectionArgs;
  42     String mSortOrder;
  43
  44     Cursor mCursor;
  45
  46     /* Runs on a worker thread */
  47     @Override
  48     public Cursor loadInBackground() {
  49         Cursor cursor = getContext().getContentResolver().query(mUri, mProjection, mSelection,
  50                 mSelectionArgs, mSortOrder);
  51         if (cursor != null) {
  52             // Ensure the cursor window is filled
  53             cursor.getCount();
  54             registerContentObserver(cursor, mObserver);
  55         }
  56         return cursor;
  57     }
  58
  59     /**
  60      * Registers an observer to get notifications from the content provider
  61      * when the cursor needs to be refreshed.
  62      */
  63     void registerContentObserver(Cursor cursor, ContentObserver observer) {
  64         cursor.registerContentObserver(mObserver);
  65     }
  66
  67     /* Runs on the UI thread */
  68     @Override
  69     public void deliverResult(Cursor cursor) {
  70         if (isReset()) {
  71             // An async query came in while the loader is stopped
  72             if (cursor != null) {
  73                 cursor.close();
  74             }
  75             return;
  76         }
  77         Cursor oldCursor = mCursor;
  78         mCursor = cursor;
  79
  80         if (isStarted()) {
  81             super.deliverResult(cursor);
  82         }
  83
  84         if (oldCursor != null && oldCursor != cursor && !oldCursor.isClosed()) {
  85             oldCursor.close();
  86         }
  87     }
  88
  89     /**
  90      * Creates an empty unspecified CursorLoader.  You must follow this with
  91      * calls to {@link #setUri(Uri)}, {@link #setSelection(String)}, etc
  92      * to specify the query to perform.
  93      */
  94     public CursorLoader(Context context) {
  95         super(context);
  96         mObserver = new ForceLoadContentObserver();
  97     }
  98
  99     /**
 100      * Creates a fully-specified CursorLoader.  See
 101      * {@link ContentResolver#query(Uri, String[], String, String[], String)
 102      * ContentResolver.query()} for documentation on the meaning of the
 103      * parameters.  These will be passed as-is to that call.
 104      */
 105     public CursorLoader(Context context, Uri uri, String[] projection, String selection,
 106             String[] selectionArgs, String sortOrder) {
 107         super(context);
 108         mObserver = new ForceLoadContentObserver();
 109         mUri = uri;
 110         mProjection = projection;
 111         mSelection = selection;
 112         mSelectionArgs = selectionArgs;
 113         mSortOrder = sortOrder;
 114     }
 115
 116     /**
 117      * Starts an asynchronous load of the contacts list data. When the result is ready the callbacks
 118      * will be called on the UI thread. If a previous load has been completed and is still valid
 119      * the result may be passed to the callbacks immediately.
 120      *
 121      * Must be called from the UI thread
 122      */
 123     @Override
 124     protected void onStartLoading() {
 125         if (mCursor != null) {
 126             deliverResult(mCursor);
 127         }
 128         if (takeContentChanged() || mCursor == null) {
 129             forceLoad();
 130         }
 131     }
 132
 133     /**
 134      * Must be called from the UI thread
 135      */
 136     @Override
 137     protected void onStopLoading() {
 138         // Attempt to cancel the current load task if possible.
 139         cancelLoad();
 140     }
 141
 142     @Override
 143     public void onCanceled(Cursor cursor) {
 144         if (cursor != null && !cursor.isClosed()) {
 145             cursor.close();
 146         }
 147     }
 148
 149     @Override
 150     protected void onReset() {
 151         super.onReset();
 152
 153         // Ensure the loader is stopped
 154         onStopLoading();
 155
 156         if (mCursor != null && !mCursor.isClosed()) {
 157             mCursor.close();
 158         }
 159         mCursor = null;
 160     }
 161
 162     public Uri getUri() {
 163         return mUri;
 164     }
 165
 166     public void setUri(Uri uri) {
 167         mUri = uri;
 168     }
 169
 170     public String[] getProjection() {
 171         return mProjection;
 172     }
 173
 174     public void setProjection(String[] projection) {
 175         mProjection = projection;
 176     }
 177
 178     public String getSelection() {
 179         return mSelection;
 180     }
 181
 182     public void setSelection(String selection) {
 183         mSelection = selection;
 184     }
 185
 186     public String[] getSelectionArgs() {
 187         return mSelectionArgs;
 188     }
 189
 190     public void setSelectionArgs(String[] selectionArgs) {
 191         mSelectionArgs = selectionArgs;
 192     }
 193
 194     public String getSortOrder() {
 195         return mSortOrder;
 196     }
 197
 198     public void setSortOrder(String sortOrder) {
 199         mSortOrder = sortOrder;
 200     }
 201
 202     @Override
 203     public void dump(String prefix, FileDescriptor fd, PrintWriter writer, String[] args) {
 204         super.dump(prefix, fd, writer, args);
 205         writer.print(prefix); writer.print("mUri="); writer.println(mUri);
 206         writer.print(prefix); writer.print("mProjection=");
 207                 writer.println(Arrays.toString(mProjection));
 208         writer.print(prefix); writer.print("mSelection="); writer.println(mSelection);
 209         writer.print(prefix); writer.print("mSelectionArgs=");
 210                 writer.println(Arrays.toString(mSelectionArgs));
 211         writer.print(prefix); writer.print("mSortOrder="); writer.println(mSortOrder);
 212         writer.print(prefix); writer.print("mCursor="); writer.println(mCursor);
 213         writer.print(prefix); writer.print("mContentChanged="); writer.println(mContentChanged);
 214     }
 215 }