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