sk.baka.ambient
Class BackgroundOpExecutor

java.lang.Object
  sk.baka.ambient.BackgroundOpExecutor

All Implemented Interfaces:

ThreadFactory, IBackgroundTask

public final class BackgroundOpExecutor
extends Object
implements ThreadFactory, IBackgroundTask

Able to execute multiple long operations running simultaneously in the background. Accepts Runnable task implementations. The tasks will run in low-priority daemon thread. Thread-safe.

Tasks are differentiated based on a task type object. At most a single instance of a task of given type may be submitted - multiple submissions of tasks having the same task type will do nothing unless there is no such task in executor's queue or already being executed. The task type object must comply the contract for a Map key.

A task must periodically check for its interrupt status. If it is interrupted, it should terminate ASAP. It may do so by throwing an Exception - exceptions are not reported when the process is interrupted.

Uncaught exceptions thrown by tasks are reported using AmbientApplication.error(Class, boolean, String, Throwable).

The executor initially starts in offline mode. Use setOffline(boolean) to change the mode.

There is no support for mutually exclusive tasks. If you need this functionality you have to implement it yourself, for example by synchronizing on the same object instance.

Author:

Martin Vysny

Constructor Summary

BackgroundOpExecutor()

Method Summary

void	backgroundTask(int taskCount, String name, int progress, int maxProgress) Sets a progress of the current task.
void	cancel(Object taskType) Cancels given task.
boolean	isScheduledOrExecuted(Object taskType) Checks if this task is already scheduled.
Thread	newThread(Runnable r)
boolean	schedule(Runnable task, Object taskType, boolean online, String name) Schedules given task for execution.
void	setOffline(boolean offline) Sets the online/offline state of the executor.
void	stopAllTasks() Immediately stops all running/pending tasks.
void	terminate() Immediately terminates the executor and all pending tasks.

Methods inherited from class java.lang.Object

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

Constructor Detail

BackgroundOpExecutor

public BackgroundOpExecutor()

Method Detail

schedule

public boolean schedule(Runnable task,
                        Object taskType,
                        boolean online,
                        String name)

Schedules given task for execution. Does nothing if the task is rejected to be submitted. Task may be rejected for these reasons:

• it is already scheduled for execution or executed
• Processing of online task was requested while in offline mode

Parameters:

task - the task to schedule, must not be null.

taskType - the task type, must not be null.

online - if true then this task processes some online content.

name - the displayable task name. A grammar construct of name + "failed" should be a meaningful text.

Returns:

true if the task was scheduled, false if it was rejected.

isScheduledOrExecuted

public boolean isScheduledOrExecuted(Object taskType)

Checks if this task is already scheduled.

Parameters:

taskType - the task handle to check, must not be null.

Returns:

true if it is scheduled.

setOffline

public void setOffline(boolean offline)

Sets the online/offline state of the executor. During the offline period the executor rejects online tasks.

Parameters:

offline - if true then the executor sets itself as offline and all pending online tasks are terminated.

newThread

public Thread newThread(Runnable r)

Specified by:

newThread in interface ThreadFactory

stopAllTasks

public void stopAllTasks()

Immediately stops all running/pending tasks.

terminate

public void terminate()

Immediately terminates the executor and all pending tasks. The executor will reject all submitted tasks from now on.

backgroundTask

public void backgroundTask(int taskCount,
                           String name,
                           int progress,
                           int maxProgress)

Sets a progress of the current task. Must be invoked from a task Runnable.

Specified by:

backgroundTask in interface IBackgroundTask

Parameters:

taskCount - unused, ignored.

name - a new name for the task.

progress - current task progress.

maxProgress - maximum progress.

cancel

public void cancel(Object taskType)

Cancels given task. Does nothing if no such task is running.

Parameters:

taskType - the task type, must not be null.