Class TaskPlanner

java.lang.Object
com.inet.taskplanner.server.api.TaskPlanner
public class TaskPlanner extends Object
The main class of the Task Planner package. This class has only one instance, which can be retrieved by the method getInstance().
The TaskPlanner is in charge of executing any number of scheduled tasks for report execution.

The central element of planned tasks is logically the TaskExecution. A task contains triggers, jobs, and result actions. Triggers define when to execute, jobs generate results, and actions process those results.

Each task always has an owner. When a new task is added, the user passed to addTask(TaskDefinition, GUID) becomes 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 other than through the Task Planner Maintenance page. With active system permissions, users can only see and modify their own tasks unless they have the PERMISSION_TASKPLANNER_ADMIN permission.

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 ZIP file and add it to your application. All methods of TaskPlanner will throw an IllegalStateException if you invoke them before plugin initialization is completed.

Since:
taskplanner 3.0

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final com.inet.permissions.Permission
    PERMISSION_TASKPLANNER
    Permission required for users accessing the taskplanner.
    static final com.inet.permissions.Permission
    PERMISSION_TASKPLANNER_ADMIN
    Permission required when a user must access the tasks of other users.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    activateTask(@Nonnull com.inet.id.GUID taskID)
    Activates the task with the given ID.
    @Nonnull com.inet.id.GUID
    addTask(@Nonnull TaskDefinition task, @Nonnull com.inet.id.GUID userId)
    Adds a new task to the Task Planner.
    void
    cancelTask(@Nonnull com.inet.id.GUID taskID, boolean waitForCancelation)
    Cancels a currently executing task.
    void
    cancelTaskExecution(@Nonnull com.inet.id.GUID taskID, @Nullable com.inet.id.GUID executionID, boolean waitForCancelation)
    Cancels an execution of a currently executing task.
    void
    deactivateTask(@Nonnull com.inet.id.GUID taskID)
    Deactivates the task with the given ID.
    @Nullable CompletableFuture<Void>
    executeTask(@Nonnull com.inet.id.GUID taskID)
    Executes the task with the given ID.
    @Nullable CompletableFuture<Void>
    executeTask(@Nonnull com.inet.id.GUID taskID, @Nullable Map<String,String> placeholders)
    Executes the task with the given ID.
    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.
    @Nonnull List<com.inet.id.GUID>
    getAllTaskIDs()
    Gets a list of the IDs of all tasks in the Task Planner.
    static TaskPlanner
    getInstance()
    Gets the TaskPlanner instance, creating one if none exists yet.
    @Nullable TaskDefinition
    getTaskDefinition(@Nonnull com.inet.id.GUID taskID)
    Retrieves the definition of an existing and stored task.
    Note: The returned instance is a copy of the internal definition.
    @Nullable TaskExecution
    getTaskExecution(@Nonnull com.inet.id.GUID taskID)
    Retrieve the execution data of an existing and stored task.
    @Nonnull List<com.inet.id.GUID>
    getUserTaskIDs(com.inet.id.GUID userId)
    Gets a list of the IDs of all tasks belonging to the specified user.
    void
    registerEventListener(@Nonnull TaskEventListener listener)
    Registers a listener that is to be notified about changes to tasks.
    void
    removeTask(@Nonnull com.inet.id.GUID taskID)
    Removes the task with the given ID.
    void
    unregisterEventListener(@Nonnull TaskEventListener listener)
    Unregister specified event listener.
    void
    updateTask(@Nonnull com.inet.id.GUID taskID, @Nonnull TaskDefinition taskModel)
    Updates an existing task in the Task Planner.

    Methods inherited from class Object

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

  • Field Details

    • PERMISSION_TASKPLANNER

      public static final com.inet.permissions.Permission PERMISSION_TASKPLANNER
      Permission 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_ADMIN
      Permission 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

      public static TaskPlanner getInstance()
      Gets the TaskPlanner instance, creating one if none exists yet.
      Returns:
      an instance of the i-net TaskPlanner.
      Since:
      taskplanner 3.0

    • registerEventListener

      public void registerEventListener(@Nonnull TaskEventListener listener)
      Registers a listener that is to be notified about changes to 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

      public void unregisterEventListener(@Nonnull TaskEventListener listener)
      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

      public @Nullable TaskExecution getTaskExecution(@Nonnull com.inet.id.GUID taskID)
      Retrieve the execution data of an existing and stored task.
      Parameters:
      taskID - the ID of the task
      Returns:
      the desired task execution data, or null if no task with the given ID exists
      Since:
      taskplanner 3.0
      See Also:

    • getTaskDefinition

      public @Nullable TaskDefinition getTaskDefinition(@Nonnull com.inet.id.GUID taskID)
      Retrieves the definition of an 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 unless updateTask(GUID, TaskDefinition) is called.
      Parameters:
      taskID - the ID of the task
      Returns:
      the desired task, or null if no task with the given ID exists
      Since:
      taskplanner 3.0
      See Also:

    • getUserTaskIDs

      public @Nonnull List<com.inet.id.GUID> getUserTaskIDs(com.inet.id.GUID userId)
      Gets a list of the IDs of all tasks belonging to the specified 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 of task IDs for the specified user; can be empty
      Throws:
      IllegalArgumentException - if the given userId is null.
      Since:
      taskplanner 3.2

    • getAllTaskIDs

      public @Nonnull List<com.inet.id.GUID> getAllTaskIDs()
      Gets a list of the IDs of all tasks in the Task Planner.
      Returns:
      a list of all task IDs
      Since:
      taskplanner 3.0

    • executeTask

      public @Nullable CompletableFuture<Void> executeTask(@Nonnull com.inet.id.GUID taskID)
      Executes the task with the given ID.

      This is the same as if a trigger initiated an execution. If the task is already running, then nothing will happen. If no task with the given ID exists, nothing happens.

      Parameters:
      taskID - the ID of the task
      Returns:
      a future that completes when execution of this task is complete, or null if no task is stored for the given taskID
      Throws:
      IllegalArgumentException - if taskID is null.
      Since:
      taskplanner 3.0

    • executeTask

      public @Nullable CompletableFuture<Void> executeTask(@Nonnull com.inet.id.GUID taskID, @Nullable Map<String,String> placeholders)
      Executes the task with the given ID.

      This is the same as if a trigger initiated an execution. If the task is already running, nothing happens. If no task with the given ID exists, nothing happens.

      Parameters:
      taskID - the ID of the task
      placeholders - optional properties of the trigger (values of placeholders)
      Returns:
      a future that completes when execution of this task is complete, or null if no task is 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 only executes the task; no events are emitted and nothing is saved. There is no execution history. An error in the execution is visible via the get method of the returned Future. The Future completes if the execution finished or failed.

      Parameters:
      task - the definition of the task to execute
      userId - the ID of the user who will become this task's owner for the execution
      Returns:
      a future that completes when execution of this task is complete
      Throws:
      IllegalArgumentException - if task or userId is null
      Since:
      taskplanner 3.2

    • addTask

      public @Nonnull com.inet.id.GUID addTask(@Nonnull TaskDefinition task, @Nonnull com.inet.id.GUID userId)
      Adds a new task to the Task Planner.

      The task does not need to be valid or complete. Future changes to the task definition must be saved with updateTask(GUID, TaskDefinition). The user identified by userId becomes the owner of the task. The task will automatically be activated if the given task definition is marked as activated, which is the default setting.

      Parameters:
      task - this contains triggers, jobs and actions of the new task
      userId - ID of the user who will become the new task's 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

      public void updateTask(@Nonnull com.inet.id.GUID taskID, @Nonnull TaskDefinition taskModel)
      Updates an existing task in the Task Planner.

      The task's triggers, jobs, and result actions are replaced with those from the given task model; all previous elements are discarded.

      Parameters:
      taskID - ID of the task to update
      taskModel - the new model of the task
      Throws:
      IllegalArgumentException - if no task with the given ID exists or if the change is not permitted
      Since:
      taskplanner 3.0

    • removeTask

      public void removeTask(@Nonnull com.inet.id.GUID taskID)
      Removes the task with the given ID. If no task with the given ID exists, nothing is 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)
      Activates the task with the given ID. If the task is already activated, nothing is done.
      Parameters:
      taskID - ID of the task to activate
      Throws:
      IllegalArgumentException - if no task with the given ID exists
      Since:
      taskplanner 3.0

    • deactivateTask

      public void deactivateTask(@Nonnull com.inet.id.GUID taskID)
      Deactivates the task with the given ID. If the task is already inactive, this method does nothing.
      Parameters:
      taskID - ID of the task to deactivate
      Throws:
      IllegalArgumentException - if no task with the given ID exists
      Since:
      taskplanner 3.0

    • cancelTask

      public void cancelTask(@Nonnull com.inet.id.GUID taskID, boolean waitForCancelation)
      Cancels a currently executing task. Cancellation can take some time depending on the jobs and actions. This cancels all executions of the given task.

      If the task does not exist, 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 cancel
      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 3.0

    • cancelTaskExecution

      public void cancelTaskExecution(@Nonnull com.inet.id.GUID taskID, @Nullable com.inet.id.GUID executionID, boolean waitForCancelation)
      Cancels an execution of a currently executing task. Cancellation can take some time depending on the jobs and actions.

      If the task does not exist, 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 cancel
      executionID - 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