com.commonsware.cwac.task
Class AsyncTaskEx<Params,Progress,Result>

java.lang.Object
  com.commonsware.cwac.task.AsyncTaskEx<Params,Progress,Result>

Direct Known Subclasses:

AjaxTask

public abstract class AsyncTaskEx<Params,Progress,Result>
extends Object

AsyncTaskEx 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.

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 begin, doInBackground, processProgress and end.

Usage

AsyncTaskEx 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 AsyncTaskEx<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));
         }
         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);
 

AsyncTaskEx's generic types

The three types used by an asynchronous task are the following:

1. Params, the type of the parameters sent to the task upon execution.
2. Progress, the type of the progress units published during the background computation.
3. Result, the type of the result of the background computation.

Not all types are always used by am asynchronous task. To mark a type as unused, simply use the type Void:

 private class MyTask extends AsyncTaskEx

 
The 4 steps
 
When an asynchronous task is executed, the task goes through 4 steps:
 

     
onPreExecute(), invoked on the UI thread immediately after the task
     is executed. This step is normally used to setup the task, for instance by
     showing a progress bar in the user interface.
     
doInBackground(Params...), invoked on the background thread
     immediately after onPreExecute() finishes executing. This step is used
     to perform background computation that can take a long time. The parameters
     of the asynchronous task are passed to this step. The result of the computation must
     be returned by this step and will be passed back to the last step. This step
     can also use publishProgress(Progress...) to publish one or more units
     of progress. These values are published on the UI thread, in the
     onProgressUpdate(Progress...) step.
     
onProgressUpdate(Progress...), invoked on the UI thread after a
     call to publishProgress(Progress...). The timing of the execution is
     undefined. This method is used to display any form of progress in the user
     interface while the background computation is still executing. For instance,
     it can be used to animate a progress bar or show logs in a text field.
     
onPostExecute(Result), invoked on the UI thread after the background
     computation finishes. The result of the background computation is passed to
     this step as a parameter.
 

 
Threading rules
 
There are a few threading rules that must be followed for this class to
 work properly:
 

     
The task instance must be created on the UI thread.
     
execute(Params...) must be invoked on the UI thread.
     
Do not call onPreExecute(), onPostExecute(Result),
     doInBackground(Params...), onProgressUpdate(Progress...) manually.
     
The task can be executed only once (an exception will be thrown if
     a second execution is attempted.)
 









Nested Class Summary




static class
AsyncTaskEx.Status



          Indicates the current status of the task.


 



Constructor Summary
AsyncTaskEx()



          Creates a new asynchronous task.
 



Method Summary




 boolean
cancel(boolean mayInterruptIfRunning)



          Attempts to cancel execution of this task.



static void
clearQueue()



           



 AsyncTaskEx<Params,Progress,Result>
execute(Params... params)



          Executes the task with the specified parameters.



 Result
get()



          Waits if necessary for the computation to complete, and then
 retrieves its result.



 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.



 AsyncTaskEx.Status
getStatus()



          Returns the current status of this task.



 boolean
isCancelled()



          Returns true if this task was cancelled before it completed
 normally.


 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 





Constructor Detail



AsyncTaskEx
public AsyncTaskEx()

Creates a new asynchronous task. This constructor must be invoked on the UI thread.






Method Detail



clearQueue
public static void clearQueue()








getStatus
public final AsyncTaskEx.Status getStatus()

Returns the current status of this task.



Returns:
The current status.





isCancelled
public final boolean isCancelled()

Returns true if this task was cancelled before it completed
 normally.



Returns:
true if task was cancelled before it completed
See Also:
cancel(boolean)





cancel
public final boolean cancel(boolean mayInterruptIfRunning)

Attempts to cancel execution of this task.  This attempt will
 fail if the task has already completed, already been cancelled,
 or could not be cancelled for some other reason. If successful,
 and this task has not started when cancel is called,
 this task should never run.  If the task has already started,
 then the mayInterruptIfRunning parameter determines
 whether the thread executing this task should be interrupted in
 an attempt to stop the task.


Parameters:
mayInterruptIfRunning - true if the thread executing this
        task should be interrupted; otherwise, in-progress tasks are allowed
        to complete.
Returns:
false if the task could not be cancelled,
         typically because it has already completed normally;
         true otherwise
See Also:
isCancelled(), 
onCancelled()





get
public final Result get()
                 throws InterruptedException,
                        ExecutionException

Waits if necessary for the computation to complete, and then
 retrieves its result.



Returns:
The computed result.
Throws:
CancellationException - If the computation was cancelled.
ExecutionException - If the computation threw an exception.
InterruptedException - If the current thread was interrupted
         while waiting.





get
public final Result get(long timeout,
                        TimeUnit unit)
                 throws InterruptedException,
                        ExecutionException,
                        TimeoutException

Waits if necessary for at most the given time for the computation
 to complete, and then retrieves its result.


Parameters:
timeout - Time to wait before cancelling the operation.
unit - The time unit for the timeout.
Returns:
The computed result.
Throws:
CancellationException - If the computation was cancelled.
ExecutionException - If the computation threw an exception.
InterruptedException - If the current thread was interrupted
         while waiting.
TimeoutException - If the wait timed out.





execute
public final AsyncTaskEx<Params,Progress,Result> execute(Params... params)

Executes the task with the specified parameters. The task returns
 itself (this) so that the caller can keep a reference to it.

 This method must be invoked on the UI thread.


Parameters:
params - The parameters of the task.
Returns:
This instance of AsyncTaskEx.
Throws:
IllegalStateException - If getStatus() returns either
         AsyncTaskEx.Status.RUNNING or AsyncTaskEx.Status.FINISHED.