org.jtrim2.ui.concurrent

Class BackgroundTaskExecutor<IDType,RightType>

java.lang.Object

org.jtrim2.ui.concurrent.BackgroundTaskExecutor<IDType,RightType>

Type Parameters:

IDType - the type of the request ID of the underlying access manager

RightType - the type of the rights handled by the underlying access manager

public final class BackgroundTaskExecutor<IDType,RightType>
extends Object

Defines an executor to execute background tasks of the GUI application. Background tasks are executed by a TaskExecutor specified at construction time. The background tasks will also have a chance to report their progress (or whatever else they want) and update components on the UI thread (as defined by the provided UiExecutorProvider).

Every BackgroundTaskExecutor has an associated AccessManager and tasks are executed in the context of an AccessToken of this access manager. Therefore these tasks may only execute if a given right is available. This allows for a convenient way to deny executing background tasks if, for example, an other conflicting task is currently being executed or simply allow to disable a button while the task is executing.

In case a background task throws an exception, the exception will be logged in a SEVERE log message (unless the exception is an instance of OperationCanceledException).

Thread safety

All of the methods of this class are allowed to be accessed from multiple threads concurrently.

Synchronization transparency

Methods of this class are not synchronization transparent.

See Also:

BackgroundTask

Constructor Summary

Constructors

Constructor and Description
BackgroundTaskExecutor(AccessManager<IDType,RightType> accessManager, TaskExecutor executor, UiExecutorProvider uiExecutorProvider) Creates a new BackgroundTaskExecutor with the given access manager and TaskExecutor.

Method Summary

Modifier and Type	Method and Description
Collection<AccessToken<IDType>>	scheduleToExecute(AccessRequest<? extends IDType,? extends RightType> request, BackgroundTask task) Submits the given BackgroundTask to the TaskExecutor specified at construction time after all the access tokens currently blocking access has been released.
Collection<AccessToken<IDType>>	scheduleToExecute(CancellationToken cancelToken, AccessRequest<? extends IDType,? extends RightType> request, BackgroundTask task) Submits the given BackgroundTask to the TaskExecutor specified at construction time after all the access tokens currently blocking access has been released.
Collection<AccessToken<IDType>>	tryExecute(AccessRequest<? extends IDType,? extends RightType> request, BackgroundTask task) Submits the given BackgroundTask to the TaskExecutor specified at construction time if the given access rights can successfully acquired from the underlying access manager.
Collection<AccessToken<IDType>>	tryExecute(CancellationToken cancelToken, AccessRequest<? extends IDType,? extends RightType> request, BackgroundTask task) Submits the given BackgroundTask to the TaskExecutor specified at construction time if the given access rights can successfully acquired from the underlying access manager.

Methods inherited from class java.lang.Object

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

Constructor Detail

BackgroundTaskExecutor

public BackgroundTaskExecutor(AccessManager<IDType,RightType> accessManager,
                              TaskExecutor executor,
                              UiExecutorProvider uiExecutorProvider)

Creates a new BackgroundTaskExecutor with the given access manager and TaskExecutor.

The specified TaskExecutor is recommended to execute tasks on a separate thread instead of the calling thread, however for debugging purposes it may be beneficial to use the SyncTaskExecutor. The executor should execute tasks on a separate thread to allow methods of this class to be called from the UI thread without actually blocking the UI.

Parameters:

accessManager - the AccessManager from which access tokens are requested to execute tasks in their context. This argument cannot be null.

executor - the TaskExecutor which actually executes submitted tasks. This argument cannot be null.

uiExecutorProvider - a factory to create executors running tasks on the UI thread of the associated UI framework. This argument cannot be null.

Throws:

NullPointerException - thrown if any of the arguments is null

Method Detail

scheduleToExecute

public Collection<AccessToken<IDType>> scheduleToExecute(AccessRequest<? extends IDType,? extends RightType> request,
                                                         BackgroundTask task)

Submits the given BackgroundTask to the TaskExecutor specified at construction time after all the access tokens currently blocking access has been released. This method differs from the tryExecute method only by invoking the getScheduledAccess method of the underlying access token instead of the tryGetAccess method.

This method will first attempt to acquire an AccessToken from the underlying access manager using the specified AccessRequest. If the request cannot be granted immediately, then the underlying access manager should execute the background task right after the specified request becomes available.

The submitted background task can be canceled by releasing the AccessToken acquired by this method. Releasing the acquired access token will cause the CancellationToken of the submitted task to signal a cancellation request (or it is possible that the task will not even be executed). not necessarily support it). This argument cannot be null.

Parameters:

request - the AccessRequest used to acquire the AccessToken in whose context the task is to be executed. This argument cannot be null.

task - the BackgroundTask to be submitted to the underlying TaskExecutor. This argument cannot be null.

Returns:

the tokens preventing the background task from being executed immediately. This method never returns null and if it returns an empty collection it should mean that the background task is scheduled to be executed.

Throws:

NullPointerException - thrown if any of the arguments is null

scheduleToExecute

public Collection<AccessToken<IDType>> scheduleToExecute(CancellationToken cancelToken,
                                                         AccessRequest<? extends IDType,? extends RightType> request,
                                                         BackgroundTask task)

Submits the given BackgroundTask to the TaskExecutor specified at construction time after all the access tokens currently blocking access has been released. This method differs from the tryExecute method only by invoking the getScheduledAccess method of the underlying access token instead of the tryGetAccess method.

This method will first attempt to acquire an AccessToken from the underlying access manager using the specified AccessRequest. If the request cannot be granted immediately, then the underlying access manager should execute the background task right after the specified request becomes available.

There are in general two ways to cancel the submitted background task: One way is to request cancellation through the specified CancellationToken and the other is to release the AccessToken acquired by this method. Releasing the acquired access token will cause the CancellationToken of the submitted task to signal a cancellation request (or it is possible that the task will not even be executed).

Parameters:

cancelToken - the CancellationToken which is used to signal that the background task should be canceled. If the background task has not yet started, it may not be executed at all (the underlying TaskExecutor may not necessarily support it). This argument cannot be null.

request - the AccessRequest used to acquire the AccessToken in whose context the task is to be executed. This argument cannot be null.

task - the BackgroundTask to be submitted to the underlying TaskExecutor. This argument cannot be null.

Returns:

the tokens preventing the background task from being executed immediately. This method never returns null and if it returns an empty collection it should mean that the background task is scheduled to be executed.

Throws:

NullPointerException - thrown if any of the arguments is null

tryExecute

public Collection<AccessToken<IDType>> tryExecute(AccessRequest<? extends IDType,? extends RightType> request,
                                                  BackgroundTask task)

Submits the given BackgroundTask to the TaskExecutor specified at construction time if the given access rights can successfully acquired from the underlying access manager.

This method will first attempt to acquire an AccessToken from the underlying access manager using the specified AccessRequest. If the access manager refuses this request this method will immediately return null. If access was granted for this method, the specified background task will be submitted to the TaskExecutor specified at construction time in the context of the access token. Therefore the execute method of the task will only be executed while the acquired was not withdrawn.

The submitted background task can be canceled by releasing the AccessToken acquired by this method. Releasing the acquired access token will cause the CancellationToken of the submitted task to signal a cancellation request (or it is possible that the task will not even be executed).

Parameters:

request - the AccessRequest used to acquire the AccessToken in whose context the task is to be executed. This argument cannot be null.

task - the BackgroundTask to be submitted to the underlying TaskExecutor. This argument cannot be null.

Returns:

null if the access was granted to execute the background task and it was submitted to the underlying TaskExecutor or if access was refused, the access tokens blocking access the specified request. Note that if this method returns an empty collection, it means that access was refused but the underlying access manager did not return the reason of refusal.

Throws:

NullPointerException - thrown if any of the arguments is null

tryExecute

public Collection<AccessToken<IDType>> tryExecute(CancellationToken cancelToken,
                                                  AccessRequest<? extends IDType,? extends RightType> request,
                                                  BackgroundTask task)

Submits the given BackgroundTask to the TaskExecutor specified at construction time if the given access rights can successfully acquired from the underlying access manager.

This method will first attempt to acquire an AccessToken from the underlying access manager using the specified AccessRequest. If the access manager refuses this request this method will immediately return null. If access was granted for this method, the specified background task will be submitted to the TaskExecutor specified at construction time in the context of the access token. Therefore the execute method of the task will only be executed while the acquired was not withdrawn.

There are in general two ways to cancel the submitted background task: One way is to request cancellation through the specified CancellationToken and the other is to release the AccessToken acquired by this method. Releasing the acquired access token will cause the CancellationToken of the submitted task to signal a cancellation request (or it is possible that the task will not even be executed).

Parameters:

cancelToken - the CancellationToken which is used to signal that the background task should be canceled. If the background task has not yet started, it may not be executed at all (the underlying TaskExecutor may not necessarily support it). This argument cannot be null.

request - the AccessRequest used to acquire the AccessToken in whose context the task is to be executed. This argument cannot be null.

task - the BackgroundTask to be submitted to the underlying TaskExecutor. This argument cannot be null.

Returns:

null if the access was granted to execute the background task and it was submitted to the underlying TaskExecutor or if access was refused, the access tokens blocking access the specified request. Note that if this method returns an empty collection, it means that access was refused but the underlying access manager did not return the reason of refusal.

Throws:

NullPointerException - thrown if any of the arguments is null