Class TaskPlanner


  • public class TaskPlanner
    extends java.lang.Object
    The main class of the taskplanner 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 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

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

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void 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 deactivateTask​(com.inet.id.GUID taskID)
      Deactivate the task with the given ID.
      java.util.concurrent.Future<java.lang.Void> executeTask​(com.inet.id.GUID taskID)
      Execute the task with given ID.
      java.util.concurrent.Future<java.lang.Void> executeTask​(TaskDefinition task, com.inet.id.GUID userId)
      Ad hoc execution of a custom task definition without the requirement to store the task first.
      java.util.List<com.inet.id.GUID> getAllTaskIDs()
      Get a list with the IDs of all Tasks of the TaskPlanner.
      static TaskPlanner getInstance()
      Get the taskPlanner instance, creates one if none was created yet.
      TaskDefinition 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.
      TaskExecution getTaskExecution​(com.inet.id.GUID taskID)
      Retrieve the execution data of an existing and stored task.
      java.util.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.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • 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 Detail

      • getInstance

        public static TaskPlanner 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

        public void registerEventListener​(@Nonnull
                                          TaskEventListener listener)
        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:
        java.lang.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:
        java.lang.IllegalArgumentException - if specified listener is null.
        Since:
        taskplanner 3.0
      • getTaskExecution

        @Nullable
        public TaskExecution getTaskExecution​(@Nonnull
                                              com.inet.id.GUID taskID)
        Retrieve the execution data of an existing and stored task. The returned TaskExecution 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:
        addTask(TaskDefinition, GUID)
      • getTaskDefinition

        @Nullable
        public TaskDefinition getTaskDefinition​(@Nonnull
                                                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. 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 given ID exists.
        Since:
        taskplanner 3.0
        See Also:
        addTask(TaskDefinition, GUID), updateTask(GUID, TaskDefinition)
      • getUserTaskIDs

        @Nonnull
        public java.util.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.

        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:
        java.lang.IllegalArgumentException - if the given userId is null.
        Since:
        taskplanner 3.2
      • getAllTaskIDs

        @Nonnull
        public java.util.List<com.inet.id.GUID> getAllTaskIDs()
        Get a list with the IDs of all Tasks of the TaskPlanner.
        Returns:
        a list with all tasks.
        Since:
        taskplanner 3.0
      • executeTask

        @Nullable
        public java.util.concurrent.Future<java.lang.Void> executeTask​(@Nonnull
                                                                       com.inet.id.GUID taskID)
        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:
        java.lang.IllegalArgumentException - if taskID is null.
        Since:
        taskplanner 3.0
      • executeTask

        public java.util.concurrent.Future<java.lang.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 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 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:
        java.lang.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 task
        userId - 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:
        java.lang.IllegalArgumentException - if task or userId is null
        Since:
        taskplanner 3.0
      • updateTask

        public void updateTask​(@Nonnull
                               com.inet.id.GUID taskID,
                               @Nonnull
                               TaskDefinition taskModel)
        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 update
        taskModel - the new model of the task
        Throws:
        java.lang.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:
        java.lang.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:
        java.lang.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.

        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 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