4.5.6.1. Using Background Tasks

  1. Define a task as an inheritor of the BackgroundTask abstract class. Pass a link to a screen controller which will be associated with the task and the task timeout to the task constructor.

    Closing the screen will interrupt the tasks associated with it. Additionally, the task will be interrupted automatically after the specified timeout.

    Actual actions performed by the task are implemented in the run() method.

  2. Create an object of BackgroundTaskHandler class controlling the task by passing the task instance to the handle() method of the BackgroundWorker bean. A link to BackgroundWorker can be obtained by an injection in a screen controller, or through the AppBeans class.

  3. Run the task by invoking the execute() method of BackgroundTaskHandler.

Example:

@Inject
protected BackgroundWorker backgroundWorker;

@Override
public void init(Map<String, Object> params) {
    // Create task with 10 sec timeout and this screen as owner
    BackgroundTask<Integer, Void> task = new BackgroundTask<Integer, Void>(10, this) {
        @Override
        public Void run(TaskLifeCycle<Integer> taskLifeCycle) throws Exception {
            // Do something in background thread
            for (int i = 0; i < 5; i++) {
                TimeUnit.SECONDS.sleep(1); // time consuming computations
                taskLifeCycle.publish(i);  // publish current progress to show it in progress() method
            }
            return null;
        }

        @Override
        public void canceled() {
            // Do something in UI thread if the task is canceled
        }

        @Override
        public void done(Void result) {
            // Do something in UI thread when the task is done
        }

        @Override
        public void progress(List<Integer> changes) {
            // Show current progress in UI thread
        }
    };
    // Get task handler object and run the task
    BackgroundTaskHandler taskHandler = backgroundWorker.handle(task);
    taskHandler.execute();
}

Detailed information about methods is provided in JavaDocs for BackgroundTask, TaskLifeCycle, BackgroundTaskHandler classes.

Please note the following:

  • BackgroundTask<T, V> is a parameterized class:

    • T − the type of objects displaying task progress. Objects of this type are passed to the task’s progress() method during an invocation of TaskLifeCycle.publish() in the working thread.

    • V − task result type passed to the done() method. It can also be obtained by invoking BackgroundTaskHandler.getResult() method, which will wait for a task to complete.

  • canceled() method is invoked only during a controlled cancelation of a task, i.e. when cancel() is invoked in the TaskHandler.

  • If task timeout expires, or a window where it was running closes, the task is stopped without notifications. In the Web Client block, timeout-based interruption is performed with a delay specified in the cuba.backgroundWorker.maxClientLatencySeconds application property.

  • run() method of a task should support external interruptions. To ensure this, we recommend checking the TaskLifeCycle.isInterrupted() flag periodically during long processes and stopping execution when needed. Additionally, you should not silently discard InterruptedException (or any other exceptions) - instead you should either exit the method correctly or not handle the exception at all.

  • BackgroundTask objects are stateless. If you did not create fields for temporary data when implementing task class, you can start several parallel processes using a single task instance.

  • BackgroundHandler object (its execute() method) can only be started once. If you need to restart a task frequently, use BackgroundTaskWrapper class.

  • Use BackgroundWorkWindow or BackgroundWorkProgressWindow classes with a set of static methods to show a modal window with progress indicator and Cancel button. You can define progress indication type and allow or prohibit cancellation of the background task for the window.

  • If you need to use certain values of visual components in the task thread, you should implement their acquisition in getParams() method, which runs in the UI thread once, when a task starts. In the run() method, these parameters will be accessible via the getParams() method of the TaskLifeCycle object.

  • If any exception occurs, the framework invokes BackgroundTask.handleException() method in the UI thread, which can be used to display the error.