Merge "Update AsyncTask documentation" into jb-dev

 * perform background operations and publish results on the UI thread without

 * having to manipulate threads and/or handlers.</p>

 *

 * <p>AsyncTask is designed to be a helper class around {@link Thread} and {@link 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 <code>java.util.concurrent</code> pacakge such as {@link Executor},

 * {@link ThreadPoolExecutor} and {@link FutureTask}.</p>

 *

 * <p>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 <code>Params</code>, <code>Progress</code> and <code>Result</code>,

 *         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;

 *     }

 *     <li>Set member fields in {@link #doInBackground}, and refer to them in

 *     {@link #onProgressUpdate} and {@link #onPostExecute}.

 * </ul>

 *

 * <h2>Order of execution</h2>

 * <p>When first introduced, AsyncTasks were executed serially on a single background

 * thread. Starting with {@link android.os.Build.VERSION_CODES#DONUT}, this was changed

 * to a pool of threads allowing multiple tasks to operate in parallel. Starting with

 * {@link android.os.Build.VERSION_CODES#HONEYCOMB}, tasks are executed on a single

 * thread to avoid common application errors caused by parallel execution.</p>

 * <p>If you truly want parallel execution, you can invoke

 * {@link #executeOnExecutor(java.util.concurrent.Executor, Object[])} with

 * {@link #THREAD_POOL_EXECUTOR}.</p>

 */

public abstract class AsyncTask<Params, Progress, Result> {

    private static final String LOG_TAG = "AsyncTask";

     * thread or pool of threads depending on the platform version.  When first

     * introduced, AsyncTasks were executed serially on a single background thread.

     * Starting with {@link android.os.Build.VERSION_CODES#DONUT}, this was changed

     * to a pool of threads allowing multiple tasks to operate in parallel.  After

     * {@link android.os.Build.VERSION_CODES#HONEYCOMB}, it is planned to change this

     * back to a single thread to avoid common application errors caused

     * to a pool of threads allowing multiple tasks to operate in parallel. Starting

     * {@link android.os.Build.VERSION_CODES#HONEYCOMB}, tasks are back to being

     * executed on a single thread to avoid common application errors caused

     * by parallel execution.  If you truly want parallel execution, you can use

     * the {@link #executeOnExecutor} version of this method

     * with {@link #THREAD_POOL_EXECUTOR}; however, see commentary there for warnings on

     * its use.

     * with {@link #THREAD_POOL_EXECUTOR}; however, see commentary there for warnings

     * on its use.

     *

     * <p>This method must be invoked on the UI thread.

     *

     *

     * @throws IllegalStateException If {@link #getStatus()} returns either

     *         {@link AsyncTask.Status#RUNNING} or {@link AsyncTask.Status#FINISHED}.

     *

     * @see #executeOnExecutor(java.util.concurrent.Executor, Object[])

     * @see #execute(Runnable)

     */

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

        return executeOnExecutor(sDefaultExecutor, params);

     *

     * @throws IllegalStateException If {@link #getStatus()} returns either

     *         {@link AsyncTask.Status#RUNNING} or {@link AsyncTask.Status#FINISHED}.

     *

     * @see #execute(Object[])

     */

    public final AsyncTask<Params, Progress, Result> executeOnExecutor(Executor exec,

            Params... params) {

    /**

     * Convenience version of {@link #execute(Object...)} for use with

     * a simple Runnable object.

     * a simple Runnable object. See {@link #execute(Object[])} for more

     * information on the order of execution.

     *

     * @see #execute(Object[])

     * @see #executeOnExecutor(java.util.concurrent.Executor, Object[])

     */

    public static void execute(Runnable runnable) {

        sDefaultExecutor.execute(runnable);