Jeff Hamilton | 9911b7f | 2010-05-15 02:20:31 -0500 | [diff] [blame] | 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.os.AsyncTask; |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 20 | import android.os.Handler; |
Jeff Brown | a7771df | 2012-05-07 20:06:46 -0700 | [diff] [blame] | 21 | import android.os.OperationCanceledException; |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 22 | import android.os.SystemClock; |
Jeff Brown | c64ff37 | 2013-10-09 18:50:56 -0700 | [diff] [blame] | 23 | import android.util.Log; |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 24 | import android.util.TimeUtils; |
Dmitri Plotnikov | cd3676e | 2011-01-06 18:39:33 -0800 | [diff] [blame] | 25 | |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 26 | import java.io.FileDescriptor; |
| 27 | import java.io.PrintWriter; |
Dmitri Plotnikov | 59d8edd | 2011-01-09 11:05:50 -0800 | [diff] [blame] | 28 | import java.util.concurrent.CountDownLatch; |
Jeff Sharkey | d01571e | 2013-10-01 17:57:41 -0700 | [diff] [blame] | 29 | import java.util.concurrent.Executor; |
Jeff Hamilton | 9911b7f | 2010-05-15 02:20:31 -0500 | [diff] [blame] | 30 | |
| 31 | /** |
Dianne Hackborn | 9567a66 | 2011-04-19 18:44:03 -0700 | [diff] [blame] | 32 | * Abstract Loader that provides an {@link AsyncTask} to do the work. See |
| 33 | * {@link Loader} and {@link android.app.LoaderManager} for more details. |
| 34 | * |
| 35 | * <p>Here is an example implementation of an AsyncTaskLoader subclass that |
| 36 | * loads the currently installed applications from the package manager. This |
| 37 | * implementation takes care of retrieving the application labels and sorting |
| 38 | * its result set from them, monitoring for changes to the installed |
| 39 | * applications, and rebuilding the list when a change in configuration requires |
| 40 | * this (such as a locale change). |
| 41 | * |
| 42 | * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/LoaderCustom.java |
| 43 | * loader} |
| 44 | * |
| 45 | * <p>An example implementation of a fragment that uses the above loader to show |
| 46 | * the currently installed applications in a list is below. |
| 47 | * |
| 48 | * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/LoaderCustom.java |
| 49 | * fragment} |
Dmitri Plotnikov | bef9c7a | 2010-06-16 15:38:07 -0700 | [diff] [blame] | 50 | * |
Jeff Hamilton | 9911b7f | 2010-05-15 02:20:31 -0500 | [diff] [blame] | 51 | * @param <D> the data type to be loaded. |
Ian Lake | 0a1feb8 | 2017-11-13 10:26:46 -0800 | [diff] [blame] | 52 | * |
| 53 | * @deprecated Use {@link android.support.v4.content.AsyncTaskLoader} |
Jeff Hamilton | 9911b7f | 2010-05-15 02:20:31 -0500 | [diff] [blame] | 54 | */ |
Ian Lake | 0a1feb8 | 2017-11-13 10:26:46 -0800 | [diff] [blame] | 55 | @Deprecated |
Jeff Hamilton | 9911b7f | 2010-05-15 02:20:31 -0500 | [diff] [blame] | 56 | public abstract class AsyncTaskLoader<D> extends Loader<D> { |
Dianne Hackborn | 540f86a | 2011-01-11 17:52:22 -0800 | [diff] [blame] | 57 | static final String TAG = "AsyncTaskLoader"; |
| 58 | static final boolean DEBUG = false; |
Dmitri Plotnikov | cd3676e | 2011-01-06 18:39:33 -0800 | [diff] [blame] | 59 | |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 60 | final class LoadTask extends AsyncTask<Void, Void, D> implements Runnable { |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 61 | private final CountDownLatch mDone = new CountDownLatch(1); |
Dmitri Plotnikov | bef9c7a | 2010-06-16 15:38:07 -0700 | [diff] [blame] | 62 | |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 63 | // Set to true to indicate that the task has been posted to a handler for |
| 64 | // execution at a later time. Used to throttle updates. |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 65 | boolean waiting; |
Dmitri Plotnikov | bef9c7a | 2010-06-16 15:38:07 -0700 | [diff] [blame] | 66 | |
Jeff Hamilton | 9911b7f | 2010-05-15 02:20:31 -0500 | [diff] [blame] | 67 | /* Runs on a worker thread */ |
| 68 | @Override |
| 69 | protected D doInBackground(Void... params) { |
Jeff Brown | c64ff37 | 2013-10-09 18:50:56 -0700 | [diff] [blame] | 70 | if (DEBUG) Log.v(TAG, this + " >>> doInBackground"); |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 71 | try { |
| 72 | D data = AsyncTaskLoader.this.onLoadInBackground(); |
Jeff Brown | c64ff37 | 2013-10-09 18:50:56 -0700 | [diff] [blame] | 73 | if (DEBUG) Log.v(TAG, this + " <<< doInBackground"); |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 74 | return data; |
| 75 | } catch (OperationCanceledException ex) { |
| 76 | if (!isCancelled()) { |
| 77 | // onLoadInBackground threw a canceled exception spuriously. |
| 78 | // This is problematic because it means that the LoaderManager did not |
| 79 | // cancel the Loader itself and still expects to receive a result. |
| 80 | // Additionally, the Loader's own state will not have been updated to |
| 81 | // reflect the fact that the task was being canceled. |
| 82 | // So we treat this case as an unhandled exception. |
| 83 | throw ex; |
| 84 | } |
Jeff Brown | c64ff37 | 2013-10-09 18:50:56 -0700 | [diff] [blame] | 85 | if (DEBUG) Log.v(TAG, this + " <<< doInBackground (was canceled)", ex); |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 86 | return null; |
| 87 | } |
Jeff Hamilton | 9911b7f | 2010-05-15 02:20:31 -0500 | [diff] [blame] | 88 | } |
| 89 | |
| 90 | /* Runs on the UI thread */ |
| 91 | @Override |
| 92 | protected void onPostExecute(D data) { |
Jeff Brown | c64ff37 | 2013-10-09 18:50:56 -0700 | [diff] [blame] | 93 | if (DEBUG) Log.v(TAG, this + " onPostExecute"); |
Dmitri Plotnikov | 59d8edd | 2011-01-09 11:05:50 -0800 | [diff] [blame] | 94 | try { |
| 95 | AsyncTaskLoader.this.dispatchOnLoadComplete(this, data); |
| 96 | } finally { |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 97 | mDone.countDown(); |
Dmitri Plotnikov | 59d8edd | 2011-01-09 11:05:50 -0800 | [diff] [blame] | 98 | } |
Jeff Hamilton | 9911b7f | 2010-05-15 02:20:31 -0500 | [diff] [blame] | 99 | } |
Dmitri Plotnikov | bef9c7a | 2010-06-16 15:38:07 -0700 | [diff] [blame] | 100 | |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 101 | /* Runs on the UI thread */ |
Dmitri Plotnikov | bef9c7a | 2010-06-16 15:38:07 -0700 | [diff] [blame] | 102 | @Override |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 103 | protected void onCancelled(D data) { |
Jeff Brown | c64ff37 | 2013-10-09 18:50:56 -0700 | [diff] [blame] | 104 | if (DEBUG) Log.v(TAG, this + " onCancelled"); |
Dmitri Plotnikov | 59d8edd | 2011-01-09 11:05:50 -0800 | [diff] [blame] | 105 | try { |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 106 | AsyncTaskLoader.this.dispatchOnCancelled(this, data); |
Dmitri Plotnikov | 59d8edd | 2011-01-09 11:05:50 -0800 | [diff] [blame] | 107 | } finally { |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 108 | mDone.countDown(); |
Dmitri Plotnikov | 59d8edd | 2011-01-09 11:05:50 -0800 | [diff] [blame] | 109 | } |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 110 | } |
| 111 | |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 112 | /* Runs on the UI thread, when the waiting task is posted to a handler. |
| 113 | * This method is only executed when task execution was deferred (waiting was true). */ |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 114 | @Override |
| 115 | public void run() { |
| 116 | waiting = false; |
| 117 | AsyncTaskLoader.this.executePendingTask(); |
Dmitri Plotnikov | bef9c7a | 2010-06-16 15:38:07 -0700 | [diff] [blame] | 118 | } |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 119 | |
| 120 | /* Used for testing purposes to wait for the task to complete. */ |
| 121 | public void waitForLoader() { |
| 122 | try { |
| 123 | mDone.await(); |
| 124 | } catch (InterruptedException e) { |
| 125 | // Ignore |
| 126 | } |
| 127 | } |
Jeff Hamilton | 9911b7f | 2010-05-15 02:20:31 -0500 | [diff] [blame] | 128 | } |
| 129 | |
Jeff Sharkey | d01571e | 2013-10-01 17:57:41 -0700 | [diff] [blame] | 130 | private final Executor mExecutor; |
| 131 | |
Dmitri Plotnikov | cd3676e | 2011-01-06 18:39:33 -0800 | [diff] [blame] | 132 | volatile LoadTask mTask; |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 133 | volatile LoadTask mCancellingTask; |
| 134 | |
| 135 | long mUpdateThrottle; |
| 136 | long mLastLoadCompleteTime = -10000; |
| 137 | Handler mHandler; |
Jeff Hamilton | 9911b7f | 2010-05-15 02:20:31 -0500 | [diff] [blame] | 138 | |
| 139 | public AsyncTaskLoader(Context context) { |
Jeff Sharkey | d01571e | 2013-10-01 17:57:41 -0700 | [diff] [blame] | 140 | this(context, AsyncTask.THREAD_POOL_EXECUTOR); |
| 141 | } |
| 142 | |
| 143 | /** {@hide} */ |
| 144 | public AsyncTaskLoader(Context context, Executor executor) { |
Jeff Hamilton | 9911b7f | 2010-05-15 02:20:31 -0500 | [diff] [blame] | 145 | super(context); |
Jeff Sharkey | d01571e | 2013-10-01 17:57:41 -0700 | [diff] [blame] | 146 | mExecutor = executor; |
Jeff Hamilton | 9911b7f | 2010-05-15 02:20:31 -0500 | [diff] [blame] | 147 | } |
| 148 | |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 149 | /** |
| 150 | * Set amount to throttle updates by. This is the minimum time from |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 151 | * when the last {@link #loadInBackground()} call has completed until |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 152 | * a new load is scheduled. |
| 153 | * |
| 154 | * @param delayMS Amount of delay, in milliseconds. |
| 155 | */ |
| 156 | public void setUpdateThrottle(long delayMS) { |
| 157 | mUpdateThrottle = delayMS; |
| 158 | if (delayMS != 0) { |
| 159 | mHandler = new Handler(); |
| 160 | } |
| 161 | } |
| 162 | |
Jeff Hamilton | 9911b7f | 2010-05-15 02:20:31 -0500 | [diff] [blame] | 163 | @Override |
Dianne Hackborn | a2ea747 | 2010-12-20 12:10:01 -0800 | [diff] [blame] | 164 | protected void onForceLoad() { |
Dianne Hackborn | 0e3b8f42 | 2010-12-20 23:22:11 -0800 | [diff] [blame] | 165 | super.onForceLoad(); |
Dmitri Plotnikov | bef9c7a | 2010-06-16 15:38:07 -0700 | [diff] [blame] | 166 | cancelLoad(); |
Jeff Hamilton | 9911b7f | 2010-05-15 02:20:31 -0500 | [diff] [blame] | 167 | mTask = new LoadTask(); |
Jeff Brown | c64ff37 | 2013-10-09 18:50:56 -0700 | [diff] [blame] | 168 | if (DEBUG) Log.v(TAG, "Preparing load: mTask=" + mTask); |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 169 | executePendingTask(); |
Jeff Hamilton | 9911b7f | 2010-05-15 02:20:31 -0500 | [diff] [blame] | 170 | } |
| 171 | |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 172 | @Override |
| 173 | protected boolean onCancelLoad() { |
Jeff Brown | c64ff37 | 2013-10-09 18:50:56 -0700 | [diff] [blame] | 174 | if (DEBUG) Log.v(TAG, "onCancelLoad: mTask=" + mTask); |
Jeff Hamilton | 9911b7f | 2010-05-15 02:20:31 -0500 | [diff] [blame] | 175 | if (mTask != null) { |
George Mount | 899ca32 | 2017-03-08 14:53:43 -0800 | [diff] [blame] | 176 | if (!mStarted) { |
| 177 | mContentChanged = true; |
| 178 | } |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 179 | if (mCancellingTask != null) { |
| 180 | // There was a pending task already waiting for a previous |
| 181 | // one being canceled; just drop it. |
Jeff Brown | c64ff37 | 2013-10-09 18:50:56 -0700 | [diff] [blame] | 182 | if (DEBUG) Log.v(TAG, |
Dianne Hackborn | 540f86a | 2011-01-11 17:52:22 -0800 | [diff] [blame] | 183 | "cancelLoad: still waiting for cancelled task; dropping next"); |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 184 | if (mTask.waiting) { |
| 185 | mTask.waiting = false; |
| 186 | mHandler.removeCallbacks(mTask); |
| 187 | } |
| 188 | mTask = null; |
| 189 | return false; |
| 190 | } else if (mTask.waiting) { |
| 191 | // There is a task, but it is waiting for the time it should |
| 192 | // execute. We can just toss it. |
Jeff Brown | c64ff37 | 2013-10-09 18:50:56 -0700 | [diff] [blame] | 193 | if (DEBUG) Log.v(TAG, "cancelLoad: task is waiting, dropping it"); |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 194 | mTask.waiting = false; |
| 195 | mHandler.removeCallbacks(mTask); |
| 196 | mTask = null; |
| 197 | return false; |
| 198 | } else { |
| 199 | boolean cancelled = mTask.cancel(false); |
Jeff Brown | c64ff37 | 2013-10-09 18:50:56 -0700 | [diff] [blame] | 200 | if (DEBUG) Log.v(TAG, "cancelLoad: cancelled=" + cancelled); |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 201 | if (cancelled) { |
| 202 | mCancellingTask = mTask; |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 203 | cancelLoadInBackground(); |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 204 | } |
| 205 | mTask = null; |
| 206 | return cancelled; |
| 207 | } |
Jeff Hamilton | 9911b7f | 2010-05-15 02:20:31 -0500 | [diff] [blame] | 208 | } |
| 209 | return false; |
| 210 | } |
Dmitri Plotnikov | bef9c7a | 2010-06-16 15:38:07 -0700 | [diff] [blame] | 211 | |
| 212 | /** |
| 213 | * Called if the task was canceled before it was completed. Gives the class a chance |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 214 | * to clean up post-cancellation and to properly dispose of the result. |
| 215 | * |
| 216 | * @param data The value that was returned by {@link #loadInBackground}, or null |
| 217 | * if the task threw {@link OperationCanceledException}. |
Dmitri Plotnikov | bef9c7a | 2010-06-16 15:38:07 -0700 | [diff] [blame] | 218 | */ |
Dianne Hackborn | 327fbd2 | 2011-01-17 14:38:50 -0800 | [diff] [blame] | 219 | public void onCanceled(D data) { |
Dianne Hackborn | 327fbd2 | 2011-01-17 14:38:50 -0800 | [diff] [blame] | 220 | } |
Dmitri Plotnikov | 4afde4f | 2011-01-18 09:41:29 -0800 | [diff] [blame] | 221 | |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 222 | void executePendingTask() { |
| 223 | if (mCancellingTask == null && mTask != null) { |
| 224 | if (mTask.waiting) { |
| 225 | mTask.waiting = false; |
| 226 | mHandler.removeCallbacks(mTask); |
| 227 | } |
| 228 | if (mUpdateThrottle > 0) { |
| 229 | long now = SystemClock.uptimeMillis(); |
| 230 | if (now < (mLastLoadCompleteTime+mUpdateThrottle)) { |
| 231 | // Not yet time to do another load. |
Jeff Brown | c64ff37 | 2013-10-09 18:50:56 -0700 | [diff] [blame] | 232 | if (DEBUG) Log.v(TAG, "Waiting until " |
Dianne Hackborn | 540f86a | 2011-01-11 17:52:22 -0800 | [diff] [blame] | 233 | + (mLastLoadCompleteTime+mUpdateThrottle) |
| 234 | + " to execute: " + mTask); |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 235 | mTask.waiting = true; |
| 236 | mHandler.postAtTime(mTask, mLastLoadCompleteTime+mUpdateThrottle); |
| 237 | return; |
| 238 | } |
| 239 | } |
Jeff Brown | c64ff37 | 2013-10-09 18:50:56 -0700 | [diff] [blame] | 240 | if (DEBUG) Log.v(TAG, "Executing: " + mTask); |
Jeff Sharkey | d01571e | 2013-10-01 17:57:41 -0700 | [diff] [blame] | 241 | mTask.executeOnExecutor(mExecutor, (Void[]) null); |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 242 | } |
| 243 | } |
| 244 | |
| 245 | void dispatchOnCancelled(LoadTask task, D data) { |
Dianne Hackborn | 327fbd2 | 2011-01-17 14:38:50 -0800 | [diff] [blame] | 246 | onCanceled(data); |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 247 | if (mCancellingTask == task) { |
Jeff Brown | c64ff37 | 2013-10-09 18:50:56 -0700 | [diff] [blame] | 248 | if (DEBUG) Log.v(TAG, "Cancelled task is now canceled!"); |
Dianne Hackborn | ca614f7 | 2013-03-14 19:10:04 -0700 | [diff] [blame] | 249 | rollbackContentChanged(); |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 250 | mLastLoadCompleteTime = SystemClock.uptimeMillis(); |
| 251 | mCancellingTask = null; |
Jeff Brown | c64ff37 | 2013-10-09 18:50:56 -0700 | [diff] [blame] | 252 | if (DEBUG) Log.v(TAG, "Delivering cancellation"); |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 253 | deliverCancellation(); |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 254 | executePendingTask(); |
| 255 | } |
| 256 | } |
| 257 | |
Dianne Hackborn | 0e3b8f42 | 2010-12-20 23:22:11 -0800 | [diff] [blame] | 258 | void dispatchOnLoadComplete(LoadTask task, D data) { |
| 259 | if (mTask != task) { |
Jeff Brown | c64ff37 | 2013-10-09 18:50:56 -0700 | [diff] [blame] | 260 | if (DEBUG) Log.v(TAG, "Load complete of old task, trying to cancel"); |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 261 | dispatchOnCancelled(task, data); |
Dianne Hackborn | 0e3b8f42 | 2010-12-20 23:22:11 -0800 | [diff] [blame] | 262 | } else { |
Dianne Hackborn | 260c3c7 | 2011-01-30 16:55:55 -0800 | [diff] [blame] | 263 | if (isAbandoned()) { |
| 264 | // This cursor has been abandoned; just cancel the new data. |
| 265 | onCanceled(data); |
| 266 | } else { |
Dianne Hackborn | ca614f7 | 2013-03-14 19:10:04 -0700 | [diff] [blame] | 267 | commitContentChanged(); |
Dianne Hackborn | 260c3c7 | 2011-01-30 16:55:55 -0800 | [diff] [blame] | 268 | mLastLoadCompleteTime = SystemClock.uptimeMillis(); |
| 269 | mTask = null; |
Jeff Brown | c64ff37 | 2013-10-09 18:50:56 -0700 | [diff] [blame] | 270 | if (DEBUG) Log.v(TAG, "Delivering result"); |
Dianne Hackborn | 260c3c7 | 2011-01-30 16:55:55 -0800 | [diff] [blame] | 271 | deliverResult(data); |
| 272 | } |
Dianne Hackborn | 0e3b8f42 | 2010-12-20 23:22:11 -0800 | [diff] [blame] | 273 | } |
Jeff Hamilton | 9911b7f | 2010-05-15 02:20:31 -0500 | [diff] [blame] | 274 | } |
| 275 | |
| 276 | /** |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 277 | * Called on a worker thread to perform the actual load and to return |
| 278 | * the result of the load operation. |
| 279 | * |
| 280 | * Implementations should not deliver the result directly, but should return them |
| 281 | * from this method, which will eventually end up calling {@link #deliverResult} on |
| 282 | * the UI thread. If implementations need to process the results on the UI thread |
| 283 | * they may override {@link #deliverResult} and do so there. |
| 284 | * |
| 285 | * To support cancellation, this method should periodically check the value of |
| 286 | * {@link #isLoadInBackgroundCanceled} and terminate when it returns true. |
| 287 | * Subclasses may also override {@link #cancelLoadInBackground} to interrupt the load |
| 288 | * directly instead of polling {@link #isLoadInBackgroundCanceled}. |
| 289 | * |
| 290 | * When the load is canceled, this method may either return normally or throw |
| 291 | * {@link OperationCanceledException}. In either case, the {@link Loader} will |
| 292 | * call {@link #onCanceled} to perform post-cancellation cleanup and to dispose of the |
| 293 | * result object, if any. |
| 294 | * |
| 295 | * @return The result of the load operation. |
| 296 | * |
| 297 | * @throws OperationCanceledException if the load is canceled during execution. |
| 298 | * |
| 299 | * @see #isLoadInBackgroundCanceled |
| 300 | * @see #cancelLoadInBackground |
| 301 | * @see #onCanceled |
Jeff Hamilton | 9911b7f | 2010-05-15 02:20:31 -0500 | [diff] [blame] | 302 | */ |
| 303 | public abstract D loadInBackground(); |
Dmitri Plotnikov | cd3676e | 2011-01-06 18:39:33 -0800 | [diff] [blame] | 304 | |
| 305 | /** |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 306 | * Calls {@link #loadInBackground()}. |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 307 | * |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 308 | * This method is reserved for use by the loader framework. |
| 309 | * Subclasses should override {@link #loadInBackground} instead of this method. |
| 310 | * |
| 311 | * @return The result of the load operation. |
| 312 | * |
| 313 | * @throws OperationCanceledException if the load is canceled during execution. |
| 314 | * |
| 315 | * @see #loadInBackground |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 316 | */ |
| 317 | protected D onLoadInBackground() { |
| 318 | return loadInBackground(); |
| 319 | } |
| 320 | |
| 321 | /** |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 322 | * Called on the main thread to abort a load in progress. |
Jeff Brown | 75ea64f | 2012-01-25 19:37:13 -0800 | [diff] [blame] | 323 | * |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 324 | * Override this method to abort the current invocation of {@link #loadInBackground} |
| 325 | * that is running in the background on a worker thread. |
| 326 | * |
| 327 | * This method should do nothing if {@link #loadInBackground} has not started |
| 328 | * running or if it has already finished. |
| 329 | * |
| 330 | * @see #loadInBackground |
Jeff Brown | 75ea64f | 2012-01-25 19:37:13 -0800 | [diff] [blame] | 331 | */ |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 332 | public void cancelLoadInBackground() { |
Jeff Brown | 75ea64f | 2012-01-25 19:37:13 -0800 | [diff] [blame] | 333 | } |
| 334 | |
| 335 | /** |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 336 | * Returns true if the current invocation of {@link #loadInBackground} is being canceled. |
Jeff Brown | 75ea64f | 2012-01-25 19:37:13 -0800 | [diff] [blame] | 337 | * |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 338 | * @return True if the current invocation of {@link #loadInBackground} is being canceled. |
| 339 | * |
| 340 | * @see #loadInBackground |
Jeff Brown | 75ea64f | 2012-01-25 19:37:13 -0800 | [diff] [blame] | 341 | */ |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 342 | public boolean isLoadInBackgroundCanceled() { |
Jeff Brown | 75ea64f | 2012-01-25 19:37:13 -0800 | [diff] [blame] | 343 | return mCancellingTask != null; |
| 344 | } |
| 345 | |
| 346 | /** |
Dmitri Plotnikov | cd3676e | 2011-01-06 18:39:33 -0800 | [diff] [blame] | 347 | * Locks the current thread until the loader completes the current load |
| 348 | * operation. Returns immediately if there is no load operation running. |
Dmitri Plotnikov | 59d8edd | 2011-01-09 11:05:50 -0800 | [diff] [blame] | 349 | * Should not be called from the UI thread: calling it from the UI |
| 350 | * thread would cause a deadlock. |
Dmitri Plotnikov | cd3676e | 2011-01-06 18:39:33 -0800 | [diff] [blame] | 351 | * <p> |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 352 | * Use for testing only. <b>Never</b> call this from a UI thread. |
Dmitri Plotnikov | 4afde4f | 2011-01-18 09:41:29 -0800 | [diff] [blame] | 353 | * |
| 354 | * @hide |
Dmitri Plotnikov | cd3676e | 2011-01-06 18:39:33 -0800 | [diff] [blame] | 355 | */ |
| 356 | public void waitForLoader() { |
| 357 | LoadTask task = mTask; |
| 358 | if (task != null) { |
Jeff Brown | b19a71a | 2012-01-31 11:48:39 -0800 | [diff] [blame] | 359 | task.waitForLoader(); |
Dmitri Plotnikov | cd3676e | 2011-01-06 18:39:33 -0800 | [diff] [blame] | 360 | } |
| 361 | } |
Dianne Hackborn | 247fe74 | 2011-01-08 17:25:57 -0800 | [diff] [blame] | 362 | |
| 363 | @Override |
| 364 | public void dump(String prefix, FileDescriptor fd, PrintWriter writer, String[] args) { |
| 365 | super.dump(prefix, fd, writer, args); |
| 366 | if (mTask != null) { |
| 367 | writer.print(prefix); writer.print("mTask="); writer.print(mTask); |
| 368 | writer.print(" waiting="); writer.println(mTask.waiting); |
| 369 | } |
| 370 | if (mCancellingTask != null) { |
| 371 | writer.print(prefix); writer.print("mCancellingTask="); writer.print(mCancellingTask); |
| 372 | writer.print(" waiting="); writer.println(mCancellingTask.waiting); |
| 373 | } |
| 374 | if (mUpdateThrottle != 0) { |
| 375 | writer.print(prefix); writer.print("mUpdateThrottle="); |
| 376 | TimeUtils.formatDuration(mUpdateThrottle, writer); |
| 377 | writer.print(" mLastLoadCompleteTime="); |
| 378 | TimeUtils.formatDuration(mLastLoadCompleteTime, |
| 379 | SystemClock.uptimeMillis(), writer); |
| 380 | writer.println(); |
| 381 | } |
| 382 | } |
Jeff Hamilton | 9911b7f | 2010-05-15 02:20:31 -0500 | [diff] [blame] | 383 | } |