CursorLoader.java revision c286d5c93640e82c649888b7e5045801581e4d6c
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 17package android.support.v4.content; 18 19import android.content.Context; 20import android.database.ContentObserver; 21import android.database.Cursor; 22import android.net.Uri; 23 24import java.io.FileDescriptor; 25import java.io.PrintWriter; 26import 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 */ 35public 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} 216