Class TaskPlanner
getInstance()
.The TaskPlanner is in charge of executing any number of
ScheduleTasks
for report execution.
The central element of planned tasks is logically the TaskExecution
. A task contains triggers
, jobs
and resultActions
. Triggers define when to
execute, Jobs generates some result and Actions will process the results somehow.
Each task always has an owner. When a new task is added the currently logged in user will become the task's owner automatically. You cannot add or modify tasks if you are not logged in. The owner of a task cannot be changed afterwards. With active systempermissions users can only see and touch their own tasks.
All operations on TaskPlanner such as add or update will immediately save the changes to the persistent storage. There is no need (or possibility) to call a save or load mechanism.
As a result, the method getTaskDefinition(GUID)
will return a snapshot of the currently saved task definition.
Any modifications to this instance will not affect the task unless updateTask(GUID, TaskDefinition)
is called.
Taskplanner requires the i-net plugin system to be active, this means you cannot extract only the jar from the
taskPlanner plugin zipfile and add it to your application. All methods of taskPlanner with throw an
IllegalStateException
if you invoke them before plugin initialization is completed.
- Since:
- taskplanner 3.0
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final com.inet.permissions.Permission
Permission required for users accessing the taskplanner.static final com.inet.permissions.Permission
Permission required when a user must access the tasks of other users. -
Method Summary
Modifier and TypeMethodDescriptionvoid
activateTask
(com.inet.id.GUID taskID) Activate the task with given ID.com.inet.id.GUID
addTask
(TaskDefinition task, com.inet.id.GUID userId) Add a new task to the TaskPlanner.void
cancelTask
(com.inet.id.GUID taskID, boolean waitForCancelation) Cancel a currently executing task.void
cancelTaskExecution
(com.inet.id.GUID taskID, com.inet.id.GUID executionID, boolean waitForCancelation) Cancel a currently executing task's execution.void
deactivateTask
(com.inet.id.GUID taskID) Deactivate the task with the given ID.executeTask
(com.inet.id.GUID taskID) Execute the task with given ID.executeTask
(TaskDefinition task, com.inet.id.GUID userId) Ad hoc execution of a custom task definition without the requirement to store the task first.List<com.inet.id.GUID>
Get a list with the IDs of all Tasks of the TaskPlanner.static TaskPlanner
Get the taskPlanner instance, creates one if none was created yet.getTaskDefinition
(com.inet.id.GUID taskID) Retrieve the definition of and existing and stored task.
Note: The returned instance is a copy of the internal definition.getTaskExecution
(com.inet.id.GUID taskID) Retrieve the execution data of an existing and stored task.List<com.inet.id.GUID>
getUserTaskIDs
(com.inet.id.GUID userId) Get a list with the IDs of all Tasks belonging to the current user.void
registerEventListener
(TaskEventListener listener) Register a listener which is to be notified about changes of tasks.void
removeTask
(com.inet.id.GUID taskID) Removes the task which has the given ID.void
unregisterEventListener
(TaskEventListener listener) Unregister specified event listener.void
updateTask
(com.inet.id.GUID taskID, TaskDefinition taskModel) Update an existing task in the TaskPlanner.
-
Field Details
-
PERMISSION_TASKPLANNER
public static final com.inet.permissions.Permission PERMISSION_TASKPLANNERPermission required for users accessing the taskplanner. When using pure API, then no permission is required.- Since:
- taskplanner 3.0
-
PERMISSION_TASKPLANNER_ADMIN
public static final com.inet.permissions.Permission PERMISSION_TASKPLANNER_ADMINPermission required when a user must access the tasks of other users. When using pure API, then no permission is required.- Since:
- taskplanner 3.0
-
-
Method Details
-
getInstance
Get the taskPlanner instance, creates one if none was created yet.- Returns:
- An instance of the i-net TaskPlanner.
- Since:
- taskplanner 3.0
-
registerEventListener
Register a listener which is to be notified about changes of tasks. Changes can result from users creating, modifying or deleting tasks or the execution of tasks.- Parameters:
listener
- the event listener to be registered.- Throws:
IllegalArgumentException
- if specified listener is null.- Since:
- taskplanner 3.0
-
unregisterEventListener
Unregister specified event listener. It will do nothing, if listener is not registered.- Parameters:
listener
- the event listener to be unregistered.- Throws:
IllegalArgumentException
- if specified listener is null.- Since:
- taskplanner 3.0
-
getTaskExecution
Retrieve the execution data of an existing and stored task. The returnedTaskExecution
is a live object and may update internally to reflect the recent executions.- Parameters:
taskID
- the ID of the task- Returns:
- the desired task execution data or
null
if no task with given ID exists. - Since:
- taskplanner 3.0
- See Also:
-
getTaskDefinition
Retrieve the definition of and existing and stored task.
Note: The returned instance is a copy of the internal definition. Therefore changes to the instance will have no effect on the stored task unlessupdateTask(GUID, TaskDefinition)
is called.- Parameters:
taskID
- the ID of the task- Returns:
- the desired task or null if no task with given ID exists.
- Since:
- taskplanner 3.0
- See Also:
-
getUserTaskIDs
Get a list with the IDs of all Tasks belonging to the current user.When using the API (and not the i-net TaskPlanner web interface) then you should use
getAllTaskIDs()
unless you really have many users.- Parameters:
userId
- ID of the user to get tasks for- Returns:
- a list with tasks for the current user. Can be empty.
- Throws:
IllegalArgumentException
- if the given userId is null.- Since:
- taskplanner 3.2
-
getAllTaskIDs
Get a list with the IDs of all Tasks of the TaskPlanner.- Returns:
- a list with all tasks.
- Since:
- taskplanner 3.0
-
executeTask
Execute the task with given ID.This is the same as if a Trigger would initiate an execution. If the tasks is already running, then nothing will happen. When no task for given ID exists, nothing will happen.
- Parameters:
taskID
- the ID of the task- Returns:
- a Future which can be used to be notified when the execution of this 'Task' is done. Will be
null
if there is no task stored for the given taskID - Throws:
IllegalArgumentException
- if taskID is null.- Since:
- taskplanner 3.0
-
executeTask
public CompletableFuture<Void> executeTask(@Nonnull TaskDefinition task, @Nonnull com.inet.id.GUID userId) Ad hoc execution of a custom task definition without the requirement to store the task first. There will be no history for this execution.This will only execute, no events are coming and nothing is saved. There is no execution history. An error in the execution is visible via the
get
method of the returnedFuture
. The Future completes if the execution finished or failed.- Parameters:
task
- the definition of the task to executeuserId
- the ID of the user who will be come this tasks owner for the execution- Returns:
- a Future which can be used to be notified when the execution of this 'Task' is done.
- Throws:
IllegalArgumentException
- if task or owner is null- Since:
- taskplanner 3.2
-
addTask
@Nonnull public com.inet.id.GUID addTask(@Nonnull TaskDefinition task, @Nonnull com.inet.id.GUID userId) Add a new task to the TaskPlanner.The task does not need to be valid nor need to be complete. Future changes to the taskModel must be saved with
updateTask(GUID, TaskDefinition)
. The currently logged in user will become the owner of the task. The task will automatically be activated if the given model was marked as activated, which is the default setting.- Parameters:
task
- this contains triggers, jobs and actions of the new taskuserId
- ID of the user which will become the new tasks owner- Returns:
- a generated unique ID for the task which can later be used to read, update or delete this task
- Throws:
IllegalArgumentException
- if task or userId is null- Since:
- taskplanner 3.0
-
updateTask
Update an existing task in the TaskPlanner.The task's triggers, jobs and resultActions will be changed to the given taskModel, all previous elements will be discarded.
- Parameters:
taskID
- ID of the task to updatetaskModel
- the new model of the task- Throws:
IllegalArgumentException
- if no task with given ID exists- Since:
- taskplanner 3.0
-
removeTask
public void removeTask(@Nonnull com.inet.id.GUID taskID) Removes the task which has the given ID. If no task with given ID exists, then nothing will be done.The removal of a task will not cancel an already started execution of this task.
- Parameters:
taskID
- ID of the task to remove- Since:
- taskplanner 3.0
-
activateTask
public void activateTask(@Nonnull com.inet.id.GUID taskID) Activate the task with given ID. If the task was already activated, then nothing will be done.- Parameters:
taskID
- ID of the task to activate- Throws:
IllegalArgumentException
- if no task with given ID exists- Since:
- taskplanner 3.0
-
deactivateTask
public void deactivateTask(@Nonnull com.inet.id.GUID taskID) Deactivate the task with the given ID. If the task is already inactive, then this method does nothing.- Parameters:
taskID
- ID of the task to deactivate- Throws:
IllegalArgumentException
- if no task with given ID exists- Since:
- taskplanner 3.0
-
cancelTask
public void cancelTask(@Nonnull com.inet.id.GUID taskID, boolean waitForCancelation) Cancel a currently executing task. The cancellation can take some time depending on the Jobs and Actions. This cancels all executions on the given task.If the task does not exists, then nothing is done.
If the task is not running, then nothing is done.
It does not matter if the task was already requested to stop (via Statistics or this method).- Parameters:
taskID
- the ID of the task to cancelwaitForCancelation
- if true then this method will wait until the execution of the task was stopped. Otherwise this method will return immediately without waiting.- Since:
- taskplanner 3.0
-
cancelTaskExecution
public void cancelTaskExecution(@Nonnull com.inet.id.GUID taskID, @Nullable com.inet.id.GUID executionID, boolean waitForCancelation) Cancel a currently executing task's execution. The cancellation can take some time depending on the Jobs and Actions.If the task does not exists, then nothing is done.
If the task is not running, then nothing is done.
It does not matter if the task was already requested to stop (via Statistics or this method).- Parameters:
taskID
- the ID of the task to cancelexecutionID
- the ID of the execution to stop, when passing null, then all executions of given task will be stopped.waitForCancelation
- if true then this method will wait until the execution of the task was stopped. Otherwise this method will return immediately without waiting.- Since:
- taskplanner 22.10
-