6 |
6 |
7 |
8 | ## Overview
9 | This library is enhanced for using AsyncTask api.
10 |
11 | ## Features
12 | - You can handle task's priority in task queue(from fifo queue to priority queue).
13 | - You can handle running thread's priority for task.
14 | - You can set a timer for task.
15 |
16 | ## Gradle & Maven
17 | Gradle
18 | ```groovy
19 | dependencies {
20 | implementation 'net.sjava:advancedasynctask:1.1.0'
21 | }
22 | ```
23 |
24 | Maven
25 | ```xml
26 | AsyncTask enables proper and easy use of the UI thread. This class allows to 26 | * perform background operations and publish results on the UI thread without 27 | * having to manipulate threads and/or handlers.
28 | * 29 | *AsyncTask is designed to be a helper class around {@link Thread} and {@link Handler}
30 | * and does not constitute a generic threading framework. AsyncTasks should ideally be
31 | * used for short operations (a few seconds at the most.) If you need to keep threads
32 | * running for long periods of time, it is highly recommended you use the various APIs
33 | * provided by the java.util.concurrent pacakge such as {@link Executor},
34 | * {@link ThreadPoolExecutor} and {@link FutureTask}.
An asynchronous task is defined by a computation that runs on a background thread and
37 | * whose result is published on the UI thread. An asynchronous task is defined by 3 generic
38 | * types, called Params, Progress and Result,
39 | * and 4 steps, called onPreExecute, doInBackground,
40 | * onProgressUpdate and onPostExecute.
For more information about using tasks and threads, read the 45 | * Processes and 46 | * Threads developer guide.
47 | *AsyncTask must be subclassed to be used. The subclass will override at least 51 | * one method ({@link #doInBackground}), and most often will override a 52 | * second one ({@link #onPostExecute}.)
53 | * 54 | *Here is an example of subclassing:
55 | *
56 | * private class DownloadFilesTask extends AsyncTask<URL, Integer, Long> {
57 | * protected Long doInBackground(URL... urls) {
58 | * int count = urls.length;
59 | * long totalSize = 0;
60 | * for (int i = 0; i < count; i++) {
61 | * totalSize += Downloader.downloadFile(urls[i]);
62 | * publishProgress((int) ((i / (float) count) * 100));
63 | * // Escape early if cancel() is called
64 | * if (isCancelled()) break;
65 | * }
66 | * return totalSize;
67 | * }
68 | *
69 | * protected void onProgressUpdate(Integer... progress) {
70 | * setProgressPercent(progress[0]);
71 | * }
72 | *
73 | * protected void onPostExecute(Long result) {
74 | * showDialog("Downloaded " + result + " bytes");
75 | * }
76 | * }
77 | *
78 | *
79 | * Once created, a task is executed very simply:
80 | *81 | * new DownloadFilesTask().execute(url1, url2, url3); 82 | *83 | * 84 | *
The three types used by an asynchronous task are the following:
86 | *Params, the type of the parameters sent to the task upon
88 | * execution.Progress, the type of the progress units published during
90 | * the background computation.Result, the type of the result of the background
92 | * computation.Not all types are always used by an asynchronous task. To mark a type as unused, 95 | * simply use the type {@link Void}:
96 | *
97 | * private class MyTask extends AsyncTask<Void, Void, Void> { ... }
98 | *
99 | *
100 | * When an asynchronous task is executed, the task goes through 4 steps:
102 | *A task can be cancelled at any time by invoking {@link #cancel(boolean)}. Invoking 126 | * this method will cause subsequent calls to {@link #isCancelled()} to return true. 127 | * After invoking this method, {@link #onCancelled(Object)}, instead of 128 | * {@link #onPostExecute(Object)} will be invoked after {@link #doInBackground(Object[])} 129 | * returns. To ensure that a task is cancelled as quickly as possible, you should always 130 | * check the return value of {@link #isCancelled()} periodically from 131 | * {@link #doInBackground(Object[])}, if possible (inside a loop for instance.)
132 | * 133 | *There are a few threading rules that must be followed for this class to 135 | * work properly:
136 | *AsyncTask guarantees that all callback calls are synchronized in such a way that the following 149 | * operations are safe without explicit synchronizations.
150 | *When first introduced, AsyncTasks were executed serially on a single background 159 | * thread. Starting with {@link Build.VERSION_CODES#DONUT}, this was changed 160 | * to a pool of threads allowing multiple tasks to operate in parallel. Starting with 161 | * {@link Build.VERSION_CODES#HONEYCOMB}, tasks are executed on a single 162 | * thread to avoid common application errors caused by parallel execution.
163 | *If you truly want parallel execution, you can invoke 164 | * {@link #executeOnExecutor(Executor, Object[])} with 165 | * {@link #THREAD_POOL_EXECUTOR}.
166 | */ 167 | public abstract class AdvancedAsyncTaskRuns on the UI thread after {@link #doInBackground}. The 356 | * specified result is the value returned by {@link #doInBackground}.
357 | * 358 | *This method won't be invoked if the task was cancelled.
359 | * 360 | * @param result The result of the operation computed by {@link #doInBackground}. 361 | * 362 | * @see #onPreExecute 363 | * @see #doInBackground 364 | * @see #onCancelled(Object) 365 | */ 366 | @SuppressWarnings({"UnusedDeclaration"}) 367 | protected void onPostExecute(Result result) { 368 | 369 | } 370 | 371 | /** 372 | * Runs on the UI thread after {@link #publishProgress} is invoked. 373 | * The specified values are the values passed to {@link #publishProgress}. 374 | * 375 | * @param values The values indicating progress. 376 | * 377 | * @see #publishProgress 378 | * @see #doInBackground 379 | */ 380 | @SuppressWarnings({"UnusedDeclaration"}) 381 | protected void onProgressUpdate(Progress... values) { 382 | 383 | } 384 | 385 | /** 386 | *Runs on the UI thread after {@link #cancel(boolean)} is invoked and 387 | * {@link #doInBackground(Object[])} has finished.
388 | * 389 | *The default implementation simply invokes {@link #onCancelled()} and
390 | * ignores the result. If you write your own implementation, do not call
391 | * super.onCancelled(result).
Applications should preferably override {@link #onCancelled(Object)}. 406 | * This method is invoked by the default implementation of 407 | * {@link #onCancelled(Object)}.
408 | * 409 | *Runs on the UI thread after {@link #cancel(boolean)} is invoked and 410 | * {@link #doInBackground(Object[])} has finished.
411 | * 412 | * @see #onCancelled(Object) 413 | * @see #cancel(boolean) 414 | * @see #isCancelled() 415 | */ 416 | protected void onCancelled() { 417 | 418 | } 419 | 420 | /** 421 | * Returns true if this task was cancelled before it completed 422 | * normally. If you are calling {@link #cancel(boolean)} on the task, 423 | * the value returned by this method should be checked periodically from 424 | * {@link #doInBackground(Object[])} to end the task as soon as possible. 425 | * 426 | * @return true if task was cancelled before it completed 427 | * 428 | * @see #cancel(boolean) 429 | */ 430 | public final boolean isCancelled() { 431 | return mCancelled.get(); 432 | } 433 | 434 | /** 435 | *Attempts to cancel execution of this task. This attempt will 436 | * fail if the task has already completed, already been cancelled, 437 | * or could not be cancelled for some other reason. If successful, 438 | * and this task has not started when cancel is called, 439 | * this task should never run. If the task has already started, 440 | * then the mayInterruptIfRunning parameter determines 441 | * whether the thread executing this task should be interrupted in 442 | * an attempt to stop the task.
443 | * 444 | *Calling this method will result in {@link #onCancelled(Object)} being 445 | * invoked on the UI thread after {@link #doInBackground(Object[])} 446 | * returns. Calling this method guarantees that {@link #onPostExecute(Object)} 447 | * is never invoked. After invoking this method, you should check the 448 | * value returned by {@link #isCancelled()} periodically from 449 | * {@link #doInBackground(Object[])} to finish the task as early as 450 | * possible.
451 | * 452 | * @param mayInterruptIfRunning true if the thread executing this 453 | * task should be interrupted; otherwise, in-progress tasks are allowed 454 | * to complete. 455 | * 456 | * @return false if the task could not be cancelled, 457 | * typically because it has already completed normally; 458 | * true otherwise 459 | * 460 | * @see #isCancelled() 461 | * @see #onCancelled(Object) 462 | */ 463 | public final boolean cancel(boolean mayInterruptIfRunning) { 464 | mCancelled.set(true); 465 | return mFuture.cancel(mayInterruptIfRunning); 466 | } 467 | 468 | /** 469 | * Waits if necessary for the computation to complete, and then 470 | * retrieves its result. 471 | * 472 | * @return The computed result. 473 | * 474 | * @throws CancellationException If the computation was cancelled. 475 | * @throws ExecutionException If the computation threw an exception. 476 | * @throws InterruptedException If the current thread was interrupted 477 | * while waiting. 478 | */ 479 | public final Result get() throws InterruptedException, ExecutionException { 480 | return mFuture.get(); 481 | } 482 | 483 | /** 484 | * Waits if necessary for at most the given time for the computation 485 | * to complete, and then retrieves its result. 486 | * 487 | * @param timeout Time to wait before cancelling the operation. 488 | * @param unit The time unit for the timeout. 489 | * 490 | * @return The computed result. 491 | * 492 | * @throws CancellationException If the computation was cancelled. 493 | * @throws ExecutionException If the computation threw an exception. 494 | * @throws InterruptedException If the current thread was interrupted 495 | * while waiting. 496 | * @throws TimeoutException If the wait timed out. 497 | */ 498 | public final Result get(long timeout, TimeUnit unit) throws InterruptedException, 499 | ExecutionException, TimeoutException { 500 | return mFuture.get(timeout, unit); 501 | } 502 | 503 | /** 504 | * Executes the task with the specified parameters. The task returns 505 | * itself (this) so that the caller can keep a reference to it. 506 | * 507 | *Note: this function schedules the task on a queue for a single background 508 | * thread or pool of threads depending on the platform version. When first 509 | * introduced, AsyncTasks were executed serially on a single background thread. 510 | * Starting with {@link Build.VERSION_CODES#DONUT}, this was changed 511 | * to a pool of threads allowing multiple tasks to operate in parallel. Starting 512 | * {@link Build.VERSION_CODES#HONEYCOMB}, tasks are back to being 513 | * executed on a single thread to avoid common application errors caused 514 | * by parallel execution. If you truly want parallel execution, you can use 515 | * the {@link #executeOnExecutor} version of this method 516 | * with {@link #THREAD_POOL_EXECUTOR}; however, see commentary there for warnings 517 | * on its use. 518 | * 519 | *
This method must be invoked on the UI thread.
520 | *
521 | * @param params The parameters of the task.
522 | *
523 | * @return This instance of AsyncTask.
524 | *
525 | * @throws IllegalStateException If {@link #getStatus()} returns either
526 | * {@link AsyncTask.Status#RUNNING} or {@link AsyncTask.Status#FINISHED}.
527 | *
528 | * @see #executeOnExecutor(Executor, Object[])
529 | * @see #execute(Runnable)
530 | */
531 | public final AdvancedAsyncTask This method is typically used with {@link #THREAD_POOL_EXECUTOR} to
540 | * allow multiple tasks to run in parallel on a pool of threads managed by
541 | * AsyncTask, however you can also use your own {@link Executor} for custom
542 | * behavior.
543 | *
544 | * Warning: Allowing multiple tasks to run in parallel from
545 | * a thread pool is generally not what one wants, because the order
546 | * of their operation is not defined. For example, if these tasks are used
547 | * to modify any state in common (such as writing a file due to a button click),
548 | * there are no guarantees on the order of the modifications.
549 | * Without careful work it is possible in rare cases for the newer version
550 | * of the data to be over-written by an older one, leading to obscure data
551 | * loss and stability issues. Such changes are best
552 | * executed in serial; to guarantee such work is serialized regardless of
553 | * platform version you can use this function with {@link #SERIAL_EXECUTOR}.
554 | *
555 | * This method must be invoked on the UI thread.
556 | *
557 | * @param exec The executor to use. {@link #THREAD_POOL_EXECUTOR} is available as a
558 | * convenient process-wide thread pool for tasks that are loosely coupled.
559 | * @param params The parameters of the task.
560 | *
561 | * @return This instance of AsyncTask.
562 | *
563 | * @throws IllegalStateException If {@link #getStatus()} returns either
564 | * {@link AsyncTask.Status#RUNNING} or {@link AsyncTask.Status#FINISHED}.
565 | *
566 | * @see #execute(Object[])
567 | */
568 | public final AdvancedAsyncTask