com.haulmont.cuba.gui.executors

Class BackgroundTask<T,V>

java.lang.Object

com.haulmont.cuba.gui.executors.BackgroundTask<T,V>

Type Parameters:

T - task progress measurement unit

V - result type

Direct Known Subclasses:

CubaFoldersPane.AppFolderUpdateBackgroundTask, LocalizedTaskWrapper

public abstract class BackgroundTask<T,V>
extends java.lang.Object

Background task for execute by BackgroundWorker.
If the task is associated with a screen through ownerFrame constructor parameter, it will be canceled when the screen is closed.
If timeout passed to constructor is exceeded, the task is canceled by special WatchDog thread.
Simplest usage example:

    BackgroundTask<Integer, Void> task = new BackgroundTask<Integer, Void>(10, this) {
        public Void run(TaskLifeCycle<Integer> taskLifeCycle) throws Exception {
            for (int i = 0; i < 5; i++) {
                TimeUnit.SECONDS.sleep(1);
            }
            return null;
        }
    };
    BackgroundTaskHandler taskHandler = backgroundWorker.handle(task);
    taskHandler.execute();
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	BackgroundTask.ProgressListener<T,V> Listener of the task life cycle events, complementary to the tasks own methods: progress(java.util.List), done(Object), canceled().
static class	BackgroundTask.ProgressListenerAdapter<T,V>

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	BackgroundTask(long timeoutSeconds) Create a task with timeout in default SECONDS unit.
protected	BackgroundTask(long timeoutSeconds, Screen screen) Create a task with timeout in default SECONDS unit.
protected	BackgroundTask(long timeout, java.util.concurrent.TimeUnit timeUnit) Create a task with timeout.
protected	BackgroundTask(long timeout, java.util.concurrent.TimeUnit timeUnit, Screen screen) Create a task with timeout.

Method Summary

Modifier and Type	Method and Description
void	addProgressListener(BackgroundTask.ProgressListener<T,V> progressListener) Add additional progress listener.
void	canceled() Called by the execution environment in UI thread if the task is canceled by BackgroundTaskHandler.cancel() invocation.
void	done(V result) Called by the execution environment in UI thread when the task is completed.
Screen	getOwnerFrame() Deprecated. Use getOwnerScreen()
Screen	getOwnerScreen()
java.util.Map<java.lang.String,java.lang.Object>	getParams() Called by the execution environment in UI thread to prepare some execution parameters.
java.util.List<BackgroundTask.ProgressListener<T,V>>	getProgressListeners() Additional progress listeners.
long	getTimeoutMilliseconds()
long	getTimeoutSeconds()
boolean	handleException(java.lang.Exception ex) Called by the execution environment in UI thread if the task run(TaskLifeCycle) method raised an exception.
boolean	handleTimeoutException() Called by the execution environment in UI thread if the task timeout is exceeded.
void	progress(java.util.List<T> changes) Called by the execution environment in UI thread on progress change.
void	removeProgressListener(BackgroundTask.ProgressListener<T,V> progressListener) Remove a progress listener.
abstract V	run(TaskLifeCycle<T> taskLifeCycle) Main method that performs a task.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BackgroundTask

protected BackgroundTask(long timeout,
                         java.util.concurrent.TimeUnit timeUnit,
                         Screen screen)

Create a task with timeout.

Parameters:

timeout - timeout

timeUnit - timeout time unit

screen - owner frame

BackgroundTask

protected BackgroundTask(long timeout,
                         java.util.concurrent.TimeUnit timeUnit)

Create a task with timeout.
The task will not be associated with any window.

Parameters:

timeout - timeout

timeUnit - timeout time unit

BackgroundTask

protected BackgroundTask(long timeoutSeconds)

Create a task with timeout in default SECONDS unit.
The task will not be associated with any window.

Parameters:

timeoutSeconds - timeout in seconds

BackgroundTask

protected BackgroundTask(long timeoutSeconds,
                         Screen screen)

Create a task with timeout in default SECONDS unit.

Parameters:

timeoutSeconds - timeout in seconds

screen - owner frame

Method Detail

run

public abstract V run(TaskLifeCycle<T> taskLifeCycle)
               throws java.lang.Exception

Main method that performs a task.
Called by the execution environment in a separate working thread.
Implementation of this method should support interruption:

• In long loops check TaskLifeCycle.isInterrupted() and return if it is true
• Don't swallow InterruptedException - return from the method or don't catch it at all

Parameters:

taskLifeCycle - lifecycle object that allows the main method to interact with the execution environment

Returns:

task result

Throws:

java.lang.Exception - exception in working thread

done

public void done(V result)

Called by the execution environment in UI thread when the task is completed.

Parameters:

result - result of execution returned by run(TaskLifeCycle) method

canceled

public void canceled()

Called by the execution environment in UI thread if the task is canceled by BackgroundTaskHandler.cancel() invocation.
This method is not called in case of timeout expiration or owner window closing.

handleTimeoutException

public boolean handleTimeoutException()

Called by the execution environment in UI thread if the task timeout is exceeded.

Returns:

true if this method implementation actually handles this event. Used for chaining handlers.

handleException

public boolean handleException(java.lang.Exception ex)

Called by the execution environment in UI thread if the task run(TaskLifeCycle) method raised an exception.

Parameters:

ex - exception

Returns:

true if this method implementation actually handles the exception. Used for chaining handlers.

progress

public void progress(java.util.List<T> changes)

Called by the execution environment in UI thread on progress change.

Parameters:

changes - list of changes since previous invocation

getParams

public java.util.Map<java.lang.String,java.lang.Object> getParams()

Called by the execution environment in UI thread to prepare some execution parameters. These parameters can be requested by the working thread inside the run(TaskLifeCycle) method by calling TaskLifeCycle.getParams().

Returns:

parameters map or null if parameters are not needed

getOwnerFrame

@Nullable
 @Deprecated
public final Screen getOwnerFrame()

Deprecated. Use getOwnerScreen()

Returns:

owner screen

getOwnerScreen

@Nullable
public final Screen getOwnerScreen()

Returns:

owner screen

getTimeoutMilliseconds

public final long getTimeoutMilliseconds()

Returns:

timeout in ms

getTimeoutSeconds

public final long getTimeoutSeconds()

Returns:

timeout in sec

addProgressListener

public final void addProgressListener(BackgroundTask.ProgressListener<T,V> progressListener)

Add additional progress listener.

Parameters:

progressListener - listener

getProgressListeners

public final java.util.List<BackgroundTask.ProgressListener<T,V>> getProgressListeners()

Additional progress listeners.

Returns:

copy of the progress listeners collection

removeProgressListener

public final void removeProgressListener(BackgroundTask.ProgressListener<T,V> progressListener)

Remove a progress listener.

Parameters:

progressListener - listener