(this, result));
345 | message.sendToTarget();
346 | return result;
347 | }
348 |
349 | /**
350 | * Returns the current status of this task.
351 | *
352 | * @return The current status.
353 | */
354 | public final Status getStatus() {
355 | return mStatus;
356 | }
357 |
358 | /**
359 | * Override this method to perform a computation on a background thread. The
360 | * specified parameters are the parameters passed to {@link #execute}
361 | * by the caller of this task.
362 | *
363 | * This method can call {@link #publishProgress} to publish updates
364 | * on the UI thread.
365 | *
366 | * @param params The parameters of the task.
367 | *
368 | * @return A result, defined by the subclass of this task.
369 | *
370 | * @see #onPreExecute()
371 | * @see #onPostExecute
372 | * @see #publishProgress
373 | */
374 | protected abstract Result doInBackground(Params... params);
375 |
376 | /**
377 | * Runs on the UI thread before {@link #doInBackground}.
378 | *
379 | * @see #onPostExecute
380 | * @see #doInBackground
381 | */
382 | protected void onPreExecute() {
383 | }
384 |
385 | /**
386 | * Runs on the UI thread after {@link #doInBackground}. The
387 | * specified result is the value returned by {@link #doInBackground}.
388 | *
389 | * This method won't be invoked if the task was cancelled.
390 | *
391 | * @param result The result of the operation computed by {@link #doInBackground}.
392 | *
393 | * @see #onPreExecute
394 | * @see #doInBackground
395 | * @see #onCancelled(Object)
396 | */
397 | @SuppressWarnings({"UnusedDeclaration"})
398 | protected void onPostExecute(Result result) {
399 | }
400 |
401 | /**
402 | * Runs on the UI thread after {@link #publishProgress} is invoked.
403 | * The specified values are the values passed to {@link #publishProgress}.
404 | *
405 | * @param values The values indicating progress.
406 | *
407 | * @see #publishProgress
408 | * @see #doInBackground
409 | */
410 | @SuppressWarnings({"UnusedDeclaration"})
411 | protected void onProgressUpdate(Progress... values) {
412 | }
413 |
414 | /**
415 | * Runs on the UI thread after {@link #cancel(boolean)} is invoked and
416 | * {@link #doInBackground(Object[])} has finished.
417 | *
418 | * The default implementation simply invokes {@link #onCancelled()} and
419 | * ignores the result. If you write your own implementation, do not call
420 | * super.onCancelled(result).
421 | *
422 | * @param result The result, if any, computed in
423 | * {@link #doInBackground(Object[])}, can be null
424 | *
425 | * @see #cancel(boolean)
426 | * @see #isCancelled()
427 | */
428 | @SuppressWarnings({"UnusedParameters"})
429 | protected void onCancelled(Result result) {
430 | onCancelled();
431 | }
432 |
433 | /**
434 | * Applications should preferably override {@link #onCancelled(Object)}.
435 | * This method is invoked by the default implementation of
436 | * {@link #onCancelled(Object)}.
437 | *
438 | * Runs on the UI thread after {@link #cancel(boolean)} is invoked and
439 | * {@link #doInBackground(Object[])} has finished.
440 | *
441 | * @see #onCancelled(Object)
442 | * @see #cancel(boolean)
443 | * @see #isCancelled()
444 | */
445 | protected void onCancelled() {
446 | }
447 |
448 | /**
449 | * Returns true if this task was cancelled before it completed
450 | * normally. If you are calling {@link #cancel(boolean)} on the task,
451 | * the value returned by this method should be checked periodically from
452 | * {@link #doInBackground(Object[])} to end the task as soon as possible.
453 | *
454 | * @return true if task was cancelled before it completed
455 | *
456 | * @see #cancel(boolean)
457 | */
458 | public final boolean isCancelled() {
459 | return mCancelled.get();
460 | }
461 |
462 | /**
463 | * Attempts to cancel execution of this task. This attempt will
464 | * fail if the task has already completed, already been cancelled,
465 | * or could not be cancelled for some other reason. If successful,
466 | * and this task has not started when cancel is called,
467 | * this task should never run. If the task has already started,
468 | * then the mayInterruptIfRunning parameter determines
469 | * whether the thread executing this task should be interrupted in
470 | * an attempt to stop the task.
471 | *
472 | * Calling this method will result in {@link #onCancelled(Object)} being
473 | * invoked on the UI thread after {@link #doInBackground(Object[])}
474 | * returns. Calling this method guarantees that {@link #onPostExecute(Object)}
475 | * is never invoked. After invoking this method, you should check the
476 | * value returned by {@link #isCancelled()} periodically from
477 | * {@link #doInBackground(Object[])} to finish the task as early as
478 | * possible.
479 | *
480 | * @param mayInterruptIfRunning true if the thread executing this
481 | * task should be interrupted; otherwise, in-progress tasks are allowed
482 | * to complete.
483 | *
484 | * @return false if the task could not be cancelled,
485 | * typically because it has already completed normally;
486 | * true otherwise
487 | *
488 | * @see #isCancelled()
489 | * @see #onCancelled(Object)
490 | */
491 | public final boolean cancel(boolean mayInterruptIfRunning) {
492 | mCancelled.set(true);
493 | return mFuture.cancel(mayInterruptIfRunning);
494 | }
495 |
496 | /**
497 | * Waits if necessary for the computation to complete, and then
498 | * retrieves its result.
499 | *
500 | * @return The computed result.
501 | *
502 | * @throws CancellationException If the computation was cancelled.
503 | * @throws ExecutionException If the computation threw an exception.
504 | * @throws InterruptedException If the current thread was interrupted
505 | * while waiting.
506 | */
507 | public final Result get() throws InterruptedException, ExecutionException {
508 | return mFuture.get();
509 | }
510 |
511 | /**
512 | * Waits if necessary for at most the given time for the computation
513 | * to complete, and then retrieves its result.
514 | *
515 | * @param timeout Time to wait before cancelling the operation.
516 | * @param unit The time unit for the timeout.
517 | *
518 | * @return The computed result.
519 | *
520 | * @throws CancellationException If the computation was cancelled.
521 | * @throws ExecutionException If the computation threw an exception.
522 | * @throws InterruptedException If the current thread was interrupted
523 | * while waiting.
524 | * @throws TimeoutException If the wait timed out.
525 | */
526 | public final Result get(long timeout, TimeUnit unit) throws InterruptedException,
527 | ExecutionException, TimeoutException {
528 | return mFuture.get(timeout, unit);
529 | }
530 |
531 | /**
532 | * Executes the task with the specified parameters. The task returns
533 | * itself (this) so that the caller can keep a reference to it.
534 | *
535 | * Note: this function schedules the task on a queue for a single background
536 | * thread or pool of threads depending on the platform version. When first
537 | * introduced, AsyncTasks were executed serially on a single background thread.
538 | * Starting with {@link android.os.Build.VERSION_CODES#DONUT}, this was changed
539 | * to a pool of threads allowing multiple tasks to operate in parallel. Starting
540 | * {@link android.os.Build.VERSION_CODES#HONEYCOMB}, tasks are back to being
541 | * executed on a single thread to avoid common application errors caused
542 | * by parallel execution. If you truly want parallel execution, you can use
543 | * the {@link #executeOnExecutor} version of this method
544 | * with {@link #THREAD_POOL_EXECUTOR}; however, see commentary there for warnings
545 | * on its use.
546 | *
547 | *
This method must be invoked on the UI thread.
548 | *
549 | * @param params The parameters of the task.
550 | *
551 | * @return This instance of AsyncTask.
552 | *
553 | * @throws IllegalStateException If {@link #getStatus()} returns either
554 | * {@link Status#RUNNING} or {@link Status#FINISHED}.
555 | *
556 | * @see #executeOnExecutor(Executor, Object[])
557 | * @see #execute(Runnable)
558 | */
559 | public final AsyncTask execute(Params... params) {
560 | return executeOnExecutor(sDefaultExecutor, params);
561 | }
562 |
563 | /**
564 | * Executes the task with the specified parameters. The task returns
565 | * itself (this) so that the caller can keep a reference to it.
566 | *
567 | * This method is typically used with {@link #THREAD_POOL_EXECUTOR} to
568 | * allow multiple tasks to run in parallel on a pool of threads managed by
569 | * AsyncTask, however you can also use your own {@link Executor} for custom
570 | * behavior.
571 | *
572 | *
Warning: Allowing multiple tasks to run in parallel from
573 | * a thread pool is generally not what one wants, because the order
574 | * of their operation is not defined. For example, if these tasks are used
575 | * to modify any state in common (such as writing a file due to a button click),
576 | * there are no guarantees on the order of the modifications.
577 | * Without careful work it is possible in rare cases for the newer version
578 | * of the data to be over-written by an older one, leading to obscure data
579 | * loss and stability issues. Such changes are best
580 | * executed in serial; to guarantee such work is serialized regardless of
581 | * platform version you can use this function with {@link #SERIAL_EXECUTOR}.
582 | *
583 | *
This method must be invoked on the UI thread.
584 | *
585 | * @param exec The executor to use. {@link #THREAD_POOL_EXECUTOR} is available as a
586 | * convenient process-wide thread pool for tasks that are loosely coupled.
587 | * @param params The parameters of the task.
588 | *
589 | * @return This instance of AsyncTask.
590 | *
591 | * @throws IllegalStateException If {@link #getStatus()} returns either
592 | * {@link Status#RUNNING} or {@link Status#FINISHED}.
593 | *
594 | * @see #execute(Object[])
595 | */
596 | public final AsyncTask executeOnExecutor(Executor exec,
597 | Params... params) {
598 | if (mStatus != Status.PENDING) {
599 | switch (mStatus) {
600 | case RUNNING:
601 | throw new IllegalStateException("Cannot execute task:"
602 | + " the task is already running.");
603 | case FINISHED:
604 | throw new IllegalStateException("Cannot execute task:"
605 | + " the task has already been executed "
606 | + "(a task can be executed only once)");
607 | }
608 | }
609 |
610 | mStatus = Status.RUNNING;
611 |
612 | onPreExecute();
613 |
614 | mWorker.mParams = params;
615 | exec.execute(mFuture);
616 |
617 | return this;
618 | }
619 |
620 | /**
621 | * Convenience version of {@link #execute(Object...)} for use with
622 | * a simple Runnable object. See {@link #execute(Object[])} for more
623 | * information on the order of execution.
624 | *
625 | * @see #execute(Object[])
626 | * @see #executeOnExecutor(Executor, Object[])
627 | */
628 | public static void execute(Runnable runnable) {
629 | sDefaultExecutor.execute(runnable);
630 | }
631 |
632 | /**
633 | * This method can be invoked from {@link #doInBackground} to
634 | * publish updates on the UI thread while the background computation is
635 | * still running. Each call to this method will trigger the execution of
636 | * {@link #onProgressUpdate} on the UI thread.
637 | *
638 | * {@link #onProgressUpdate} will note be called if the task has been
639 | * canceled.
640 | *
641 | * @param values The progress values to update the UI with.
642 | *
643 | * @see #onProgressUpdate
644 | * @see #doInBackground
645 | */
646 | protected final void publishProgress(Progress... values) {
647 | if (!isCancelled()) {
648 | sHandler.obtainMessage(MESSAGE_POST_PROGRESS,
649 | new AsyncTaskResult