org.androidannotations.annotations.Background Maven / Gradle / Ivy
Show all versions of androidannotations-api Show documentation
/**
* Copyright (C) 2010-2016 eBusiness Information, Excilys Group
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed To in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package org.androidannotations.annotations;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
*
* Should be used on method that must be run in a background thread.
*
*
* The annotated method MUST return void and MAY contain parameters.
*
*
* The generated code is based on
* {@link org.androidannotations.api.BackgroundExecutor BackgroundExecutor}
* methods.
*
*
* Cancellation
*
* Since 3.0, you're able to cancel a background task by calling
* BackgroundExecutor.cancelAll("id") where "id" matches the
* {@link #id()} value.
*
*
*
*
* Example :
*
*
* @EBean
* public class MyBean {
* private static final String TASK_ID = "task1";
*
* @Background(id = TASK_ID)
* void launchTask() {
* // ...
* }
*
* void stopTask() {
* BackgroundExecutor.cancelAll(TASK_ID);
* }
*
* }
*
*
*
*
* Note: Cancellation may or may not be successful. If the task wasn't
* executed yet, it will be removed from the pool. But it could fail if task has
* already completed, has already been cancelled, or could not be cancelled for
* some other reason. See {@link java.util.concurrent.Future#cancel(boolean)
* Future#cancel(boolean)} for more information.
*
*
* Execution flow
*
* By default, all tasks will be put in a
* {@link java.util.concurrent.ScheduledThreadPoolExecutor
* ScheduledThreadPoolExecutor} with a core pool size of
* 2 * numberOfCpu. Which means that background methods will be
* executed in PARALLEL. You can change this by calling
* BackgroundExecutor.setExecutor(...).
*
*
* If you want execute ALL background methods SEQUENTIALLY, the best way is to
* change the executor of {@link org.androidannotations.api.BackgroundExecutor
* BackgroundExecutor} to a
* {@link java.util.concurrent.ScheduledThreadPoolExecutor
* ScheduledThreadPoolExecutor} with a core pool size of 1.
*
*
* If you want execute some background methods SEQUENTIALLY, you should simply
* use {@link #serial()} field. All task with the same serial key will be
* executed sequentially.
*
*
*
*
* Example 1 (all tasks executed sequentially) :
*
*
* @EBean
* public class MyBean {
*
* static {
* BackgroundExecutor.setExecutor(Executors.newScheduledThreadPool(1));
* }
*
* private int i = 0;
*
* void launchTasks() {
* backgroundTask();
* backgroundTask();
* backgroundTask();
* }
*
* @Background
* void backgroundTask() {
* Log.i("AA", "i = ", i++);
* }
* }
*
*
* Example 2 (some tasks executed sequentially) :
*
*
* @EBean
* public class MyBean {
*
* private int i = 0;
*
* void launchTasks() {
* backgroundTask();
* backgroundTask();
* backgroundTask();
* }
*
* @Background(serial = "sequence1")
* void backgroundTask() {
* Log.i("AA", "i = ", i++);
* }
* }
*
*
*
*
*
* Delay
*
* Sometimes you may want to delay execution of a background method. To do so,
* you should use the {@link #delay()} field.
*
* Example :
*
*
*
*
* @EBean
* public class MyBean {
*
* @Background(delay = 2000)
* void backgroundTask() {
* // ...
* }
* }
*
*
*
*
*
* @see UiThread
* @see org.androidannotations.api.BackgroundExecutor
*/
@Retention(RetentionPolicy.CLASS)
@Target(ElementType.METHOD)
public @interface Background {
/**
* Identifier for task cancellation.
*
* To cancel all tasks having a specified background id:
*
*
* boolean mayInterruptIfRunning = true;
* BackgroundExecutor.cancelAll("my_background_id", mayInterruptIfRunning);
*
*
* @return the task id for cancellation
**/
String id() default "";
/**
* Minimum delay, in milliseconds, before the background task is executed.
*
* @return the delay of the execution
*/
long delay() default 0;
/**
* Serial execution group.
*
* All background tasks having the same serial will be executed
* sequentially.
*
* @return the serial execution group
**/
String serial() default "";
}