com.communote.server.api.core.task

Interface TaskManagement

All Known Implementing Classes:

TaskManagementImpl

public interface TaskManagement

Service for managing tasks. If Communote is clustered there will be more than one instance on which a task can be executed. The different instances or nodes are identified by their name as defined in the StartupProperties.

Author:

Communote GmbH - http://www.communote.com/

Method Summary

Modifier and Type	Method and Description
Long	addTask(String uniqueTaskName, boolean active, Long interval, Date nextExecutionDate, Class<? extends TaskHandler> handlerClass) Add a new task.
Long	addTask(String uniqueTaskName, boolean active, Long interval, Date nextExecutionDate, Map<String,String> properties, Class<? extends TaskHandler> handlerClass) Add a new task.
Long	addTask(String uniqueTaskName, boolean active, Long interval, Date nextExecutionDate, Map<String,String> properties, String handlerClass) Add a new task.
Long	addTask(String uniqueTaskName, boolean active, Long interval, Date nextExecutionDate, String handlerClass) Add a new task.
void	addTaskHandler(Class<? extends TaskHandler> taskHandler) Add a handler for tasks.
void	addTaskHandler(String handlerName, Class<? extends TaskHandler> taskHandler) Add a handler for tasks with the given name.
void	addTaskHandlerWithTask(String handlerName, Class<? extends TaskHandler> taskHandlerClazz, Map<String,String> properties, long startOffset, boolean resetFailed) Add a task handler and create a task for it.
void	failTaskExecution(String uniqueTaskName) Mark the execution of a task as failed.
TaskTO	findTask(String uniqueTaskName) Get the details of a task.
TaskTO	getNextScheduledTask() Return the next task to be scheduled.
TaskTO	getNextScheduledTask(Date upperBound) Return the next task to be scheduled.
Collection<TaskTO>	getNextScheduledTasks(Date upperBound, int maxTasks, Collection<Long> taskIdsToExclude) Get the tasks to schedule next
Collection<TaskExecution>	getTaskExecutions(String instanceName) Return all task executions running on the Communote with the given name.
boolean	isTaskRunningOnCurrentInstance(String uniqueTaskName) Return whether the given task is running on the current instance.
String	killTaskExecution(Long executionId) Kill the task with given execution ID by removing the execution and setting the task back to pending.
void	removeTask(String uniqueTaskName) Remove a task if it is not RUNNING.
boolean	removeTaskHandler(String handlerName) Remove the task handler class from the list of known handlers.
void	rescheduleTask(String uniqueTaskName, Date nextExecutionDate) Reschedule a pending task.
void	resetTask(String uniqueTaskName) Reset a task back from failed to pending.
Long	startTaskExecution(String uniqueTaskName) Mark a task as running on this instance by creating an execution for it and setting the status to RUNNING.
Long	startTaskExecutionTx(String uniqueTaskName) Same as startTaskExecution(String) but can throw DatabaseIntegrityViolationException.
void	stopAllTaskExecutions() Calls stopAllTaskExecutions(true,now).
void	stopAllTaskExecutions(boolean resetFailed, Date rescheduleDate) End all task executions of this instance and schedules them again.
void	stopTaskExecution(String uniqueTaskName) End the execution of the given task.
void	stopTaskExecution(String uniqueTaskName, Date rescheduleDate) End the execution of the given task.

Method Detail

addTask

Long addTask(String uniqueTaskName,
             boolean active,
             Long interval,
             Date nextExecutionDate,
             Class<? extends TaskHandler> handlerClass)
      throws TaskAlreadyExistsException

Add a new task.

Parameters:

uniqueTaskName - Unique name for this task.

active - True, if active.

interval - Interval for the execution.

nextExecutionDate - The next execution date.

handlerClass - Class of the handler.

Returns:

The id of the Task.

Throws:

TaskAlreadyExistsException - Thrown, when there is already a task with this name.

addTask

Long addTask(String uniqueTaskName,
             boolean active,
             Long interval,
             Date nextExecutionDate,
             Map<String,String> properties,
             Class<? extends TaskHandler> handlerClass)
      throws TaskAlreadyExistsException

Add a new task.

Parameters:

uniqueTaskName - Unique name for this task.

active - True, if active.

interval - Interval for the execution.

nextExecutionDate - The next execution date.

properties - Properties of this task.

handlerClass - Class of the handler.

Returns:

The id of the Task.

Throws:

TaskAlreadyExistsException - Thrown, when there is already a task with this name.

addTask

Long addTask(String uniqueTaskName,
             boolean active,
             Long interval,
             Date nextExecutionDate,
             Map<String,String> properties,
             String handlerClass)
      throws TaskAlreadyExistsException

Add a new task.

Parameters:

uniqueTaskName - Unique name for this task.

active - True, if active.

interval - Interval for the execution.

nextExecutionDate - The next execution date.

properties - Properties of this task.

handlerClass - Full qualified class name for the handler.

Returns:

The id of the Task.

Throws:

TaskAlreadyExistsException - Thrown, when there is already a task with this name.

addTask

Long addTask(String uniqueTaskName,
             boolean active,
             Long interval,
             Date nextExecutionDate,
             String handlerClass)
      throws TaskAlreadyExistsException

Add a new task.

Parameters:

uniqueTaskName - Unique name for this task.

active - True, if active.

interval - Interval for the execution.

nextExecutionDate - The next execution date.

handlerClass - Full qualified class name for the handler.

Returns:

The id of the Task.

Throws:

TaskAlreadyExistsException - Thrown, when there is already a task with this name.

addTaskHandler

void addTaskHandler(Class<? extends TaskHandler> taskHandler)

Add a handler for tasks. The handler will be registered under its full class name. If a handler with the same name already exists it will be overwritten.

Parameters:

taskHandler - the task handler to add

addTaskHandler

void addTaskHandler(String handlerName,
                    Class<? extends TaskHandler> taskHandler)

Add a handler for tasks with the given name. If a handler with the same name already exists it will be overwritten.

Parameters:

handlerName - the name of the handler to be used

taskHandler - the task handler to add

addTaskHandlerWithTask

void addTaskHandlerWithTask(String handlerName,
                            Class<? extends TaskHandler> taskHandlerClazz,
                            Map<String,String> properties,
                            long startOffset,
                            boolean resetFailed)

Add a task handler and create a task for it. If a task already exists which has an execution time before now + startOffset, the task will be rescheduled to run with the new start time (now + startOffset).

Parameters:

handlerName - the name of the handler. The name will also be used as unique name for the task.

taskHandlerClazz - the TaskHandler class

properties - Properties for the task (if one is added).

startOffset - the offset in milliseconds to add to the current time to delay the execution of the task

resetFailed - if true and the status of an existing task is failed the task will be always rescheduled.

failTaskExecution

void failTaskExecution(String uniqueTaskName)
                throws InvalidInstanceException

Mark the execution of a task as failed.

Parameters:

uniqueTaskName - Name of the task.

Throws:

InvalidInstanceException - Thrown, when the task is not running on this instance.

findTask

TaskTO findTask(String uniqueTaskName)

Get the details of a task.

Parameters:

uniqueTaskName - The name of the task

Returns:

the TO containing the details of the task or null if there is no task for that name. The handler of the task won't be set

getNextScheduledTask

TaskTO getNextScheduledTask()

Return the next task to be scheduled.

Returns:

TaskTO or null if there is none.

getNextScheduledTask

TaskTO getNextScheduledTask(Date upperBound)

Return the next task to be scheduled.

Parameters:

upperBound - The upper bound of the task's next execution (exclusive).

Returns:

TaskTO or null if there is none.

getNextScheduledTasks

Collection<TaskTO> getNextScheduledTasks(Date upperBound,
                                         int maxTasks,
                                         Collection<Long> taskIdsToExclude)

Get the tasks to schedule next

Parameters:

upperBound - NextExecution < UpperBound.

maxTasks - maximum number of tasks to return

taskIdsToExclude - the IDs of the task to exclude from the query. Can be null.

Returns:

List all tasks, which can be executed.

getTaskExecutions

Collection<TaskExecution> getTaskExecutions(String instanceName)

Return all task executions running on the Communote with the given name.

Parameters:

instanceName - Name of the instance

Returns:

List of task executions of the instance

isTaskRunningOnCurrentInstance

boolean isTaskRunningOnCurrentInstance(String uniqueTaskName)

Return whether the given task is running on the current instance.

Parameters:

uniqueTaskName - the unique name of the task

Returns:

true if the task is running on the current instance, false otherwise

killTaskExecution

String killTaskExecution(Long executionId)

Kill the task with given execution ID by removing the execution and setting the task back to pending.

Parameters:

executionId - The execution ID

Returns:

The unique name of the task, which was killed, or null if there was none.

removeTask

void removeTask(String uniqueTaskName)
         throws TaskAlreadyRunningException

Remove a task if it is not RUNNING.

Parameters:

uniqueTaskName - The task to remove.

Throws:

TaskAlreadyRunningException - Thrown, when the task is currently running.

removeTaskHandler

boolean removeTaskHandler(String handlerName)

Remove the task handler class from the list of known handlers.

Parameters:

handlerName - the handler name

Returns:

true if something has actually been removed

rescheduleTask

void rescheduleTask(String uniqueTaskName,
                    Date nextExecutionDate)
             throws TaskStatusException

Reschedule a pending task.

Parameters:

uniqueTaskName - the unique name of task. If there is no task with the given name the call will be ignored.

nextExecutionDate - the new execution date

Throws:

TaskStatusException - in case the task is not pending

resetTask

void resetTask(String uniqueTaskName)

Reset a task back from failed to pending. Also removes an existing execution.

Parameters:

uniqueTaskName - The name of the task to reset

startTaskExecution

Long startTaskExecution(String uniqueTaskName)
                 throws TaskAlreadyRunningException,
                        TaskNotActiveException,
                        TaskManagementException

Mark a task as running on this instance by creating an execution for it and setting the status to RUNNING. This call is ignored if the next execution timestamp of the task is in the future.

Parameters:

uniqueTaskName - Name of the task to start.

Returns:

the ID of the created execution or null if the task does not exist or next execution timestamp is in the future

Throws:

TaskAlreadyRunningException - in case the task is already running.

TaskNotActiveException - in case the task is not activated.

TaskManagementException - in case of an unexpected error

startTaskExecutionTx

Long startTaskExecutionTx(String uniqueTaskName)
                   throws TaskNotActiveException,
                          TaskAlreadyRunningException

Same as startTaskExecution(String) but can throw DatabaseIntegrityViolationException. Therefore this method should never be called directly and startTaskExecution(String) should be used instead.

Parameters:

uniqueTaskName - Name of the task to start.

Returns:

the ID of the created execution or null if the task does not exist or next execution timestamp is in the future

Throws:

TaskAlreadyRunningException - in case the task is already running.

TaskNotActiveException - In case if the task is not activated.

stopAllTaskExecutions

void stopAllTaskExecutions()

Calls stopAllTaskExecutions(true,now).

stopAllTaskExecutions

void stopAllTaskExecutions(boolean resetFailed,
                           Date rescheduleDate)

End all task executions of this instance and schedules them again.

Parameters:

rescheduleDate - If set, this will be the new date the task will be executed.

resetFailed - If set, all failed tasks will be reset.

stopTaskExecution

void stopTaskExecution(String uniqueTaskName)
                throws InvalidInstanceException

End the execution of the given task.

Parameters:

uniqueTaskName - Name of the task.

Throws:

InvalidInstanceException - in case the task is not executed on this instance

stopTaskExecution

void stopTaskExecution(String uniqueTaskName,
                       Date rescheduleDate)
                throws InvalidInstanceException

End the execution of the given task.

Parameters:

uniqueTaskName - Unique name of the task.

rescheduleDate - If set, this will be the new date the task will be executed.

Throws:

InvalidInstanceException - in case the task is not running on this instance