org.androidannotations.annotations
Annotation Type Background


@Retention(value=CLASS)
@Target(value=METHOD)
public @interface Background

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 BackgroundExecutor methods.

Cancellation

Since 3.0, you're able to cancel a background task by calling BackgroundExecutor.cancelAll("id") where "id" matches the 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 Future.cancel(boolean) for more information.

Execution flow

By default, all tasks will be put in a 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 BackgroundExecutor to a ScheduledThreadPoolExecutor with a core pool size of 1.

If you want execute some background methods SEQUENTIALLY, you should simply use 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 delay() field.

Example :

 @EBean
 public class MyBean {
 
        @Background(delay = 2000)
        void backgroundTask() {
                // ...
        }
 }
 

See Also:
UiThread, BackgroundExecutor

Optional Element Summary
 int delay
          Minimum delay, in milliseconds, before the background task is executed.
 String id
          Identifier for task cancellation.
 String serial
          Serial execution group.
 

id

public abstract String id
Identifier for task cancellation. To cancel all tasks having a specified background id:
 boolean mayInterruptIfRunning = true;
 BackgroundExecutor.cancelAll("my_background_id", mayInterruptIfRunning);
 

Default:
""

delay

public abstract int delay
Minimum delay, in milliseconds, before the background task is executed.

Default:
0

serial

public abstract String serial
Serial execution group. All background tasks having the same serial will be executed sequentially.

Default:
""


Copyright © 2010-2014. All Rights Reserved.