java.lang.Object | |
↳ | android.os.AsyncTask<Params, Progress, Result> |
Class Overview
AsyncTask enables proper and easy use of the UI thread. This class allows to perform background operations and publish results on the UI thread without having to manipulate threads and/or handlers.
AsyncTask is designed to be a helper class around Thread
and Handler
and does not constitute a generic threading framework. AsyncTasks should ideally be used for short operations (a few seconds at the most.) If you need to keep threads running for long periods of time, it is highly recommended you use the various APIs provided by the java.util.concurrent
pacakge such as Executor
, ThreadPoolExecutor
and FutureTask
.
An asynchronous task is defined by a computation that runs on a background thread and whose result is published on the UI thread. An asynchronous task is defined by 3 generic types, called Params
, Progress
and Result
, and 4 steps, called onPreExecute
, doInBackground
, onProgressUpdate
andonPostExecute
.
Developer Guides
For more information about using tasks and threads, read the Processes and Threads developer guide.
Usage
AsyncTask must be subclassed to be used. The subclass will override at least one method (doInBackground(Params...)
), and most often will override a second one (onPostExecute(Result)
.)
Here is an example of subclassing:
private class DownloadFilesTask extends AsyncTask<URL, Integer, Long> { protected Long doInBackground(URL... urls) { int count = urls.length; long totalSize = 0; for (int i = 0; i < count; i++) { totalSize += Downloader.downloadFile(urls[i]); publishProgress((int) ((i / (float) count) * 100)); // Escape early if cancel() is called if (isCancelled()) break; } return totalSize; } protected void onProgressUpdate(Integer... progress) { setProgressPercent(progress[0]); } protected void onPostExecute(Long result) { showDialog("Downloaded " + result + " bytes"); } }
Once created, a task is executed very simply:
new DownloadFilesTask().execute(url1, url2, url3);
AsyncTask's generic types
The three types used by an asynchronous task are the following:
Params
, the type of the parameters sent to the task upon execution.Progress
, the type of the progress units published during the background computation.Result
, the type of the result of the background computation.
Not all types are always used by an asynchronous task. To mark a type as unused, simply use the type Void
:
private class MyTask extends AsyncTask<Void, Void, Void> { ... }
Summary
Nested Classes enum AsyncTask.Status Indicates the current status of the task.
Fields public static final Executor SERIAL_EXECUTOR An Executor
that executes tasks one at a time in serial order.public static final Executor THREAD_POOL_EXECUTOR An Executor
that can be used to execute tasks in parallel.
Public Constructors AsyncTask() Creates a new asynchronous task.
Public Methods final boolean cancel(boolean mayInterruptIfRunning) Attempts to cancel execution of this task.
static void execute( Runnable runnable) Convenience version ofexecute(Object)
for use with a simple Runnable object.final AsyncTask<Params, Progress, Result> execute(Params... params) Executes the task with the specified parameters.final AsyncTask<Params, Progress, Result> executeOnExecutor( Executor exec, Params... params) Executes the task with the specified parameters.final Result get(long timeout, TimeUnit unit) Waits if necessary for at most the given time for the computation to complete, and then retrieves its result.final Result get() Waits if necessary for the computation to complete, and then retrieves its result.final AsyncTask.Status getStatus() Returns the current status of this task.final boolean isCancelled() Returns true if this task was cancelled before it completed normally.
Protected Methods abstract Result doInBackground(Params... params) Override this method to perform a computation on a background thread.void onCancelled(Result result) Runs on the UI thread after
cancel(boolean)
is invoked anddoInBackground(Object[])
has finished.void onCancelled() Applications should preferably override
onCancelled(Object)
.void onPostExecute(Result result) Runs on the UI thread after
doInBackground(Params...)
.void onPreExecute() Runs on the UI thread beforedoInBackground(Params...)
.void onProgressUpdate(Progress... values) Runs on the UI thread afterpublishProgress(Progress...)
is invoked.final void publishProgress(Progress... values) This method can be invoked fromdoInBackground(Params...)
to publish updates on the UI thread while the background computation is still running.
[Expand] Inherited MethodsFrom class java.lang.Object
Fields
public static final Executor SERIAL_EXECUTOR
Added in API level 11An
Executor
that executes tasks one at a time in serial order. This serialization is global to a particular process.public static final Executor THREAD_POOL_EXECUTOR
Added in API level 11An
Executor
that can be used to execute tasks in parallel.