Class TaskManager


  • @ThreadSafety(level=COMPLETELY_THREADSAFE)
    public final class TaskManager
    extends java.lang.Object
    This class provides a number of utility methods for interacting with tasks in Ping Identity, UnboundID, or Nokia/Alcatel-Lucent 8661 server instances.
    NOTE: This class, and other classes within the com.unboundid.ldap.sdk.unboundidds package structure, are only supported for use against Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 server products. These classes provide support for proprietary functionality or for external specifications that are not considered stable or mature enough to be guaranteed to work in an interoperable way with other types of LDAP servers.

    It provides methods for the following:
    • Retrieving information about all scheduled, running, and recently-completed tasks in the server.
    • Retrieving a specific task by its task ID.
    • Scheduling a new task.
    • Waiting for a scheduled task to complete.
    • Canceling a scheduled task.
    • Deleting a scheduled task.

    Example

    The following example demonstrates the process for retrieving information about all tasks within the server and printing their contents using the generic API:
     List<Task> allTasks = TaskManager.getTasks(connection);
     for (Task task : allTasks)
     {
       String taskID = task.getTaskID();
       String taskName = task.getTaskName();
       TaskState taskState = task.getState();
       Map<TaskProperty,List<Object>> taskProperties =
            task.getTaskPropertyValues();
     }
     
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void cancelTask​(java.lang.String taskID, LDAPConnection connection)
      Submits a request to cancel the task with the specified task ID.
      static void cancelTask​(java.lang.String taskID, LDAPInterface connection)
      Submits a request to cancel the task with the specified task ID.
      static void deleteTask​(java.lang.String taskID, LDAPConnection connection)
      Attempts to delete the task with the specified task ID.
      static void deleteTask​(java.lang.String taskID, LDAPInterface connection)
      Attempts to delete the task with the specified task ID.
      static Task getTask​(java.lang.String taskID, LDAPConnection connection)
      Retrieves the task with the specified task ID using the given connection.
      static Task getTask​(java.lang.String taskID, LDAPInterface connection)
      Retrieves the task with the specified task ID using the given connection.
      static java.util.List<Task> getTasks​(LDAPConnection connection)
      Retrieves all of the tasks defined in the Directory Server using the provided connection.
      static java.util.List<Task> getTasks​(LDAPInterface connection)
      Retrieves all of the tasks defined in the Directory Server using the provided connection.
      static Task scheduleTask​(Task task, LDAPConnection connection)
      Schedules a new instance of the provided task in the Directory Server.
      static Task scheduleTask​(Task task, LDAPInterface connection)
      Schedules a new instance of the provided task in the Directory Server.
      static Task waitForTask​(java.lang.String taskID, LDAPConnection connection, long pollFrequency, long maxWaitTime)
      Waits for the specified task to complete.
      static Task waitForTask​(java.lang.String taskID, LDAPInterface connection, long pollFrequency, long maxWaitTime)
      Waits for the specified task to complete.
      • Methods inherited from class java.lang.Object

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

      • getTask

        @Nullable
        public static Task getTask​(@NotNull
                                   java.lang.String taskID,
                                   @NotNull
                                   LDAPConnection connection)
                            throws LDAPException,
                                   TaskException
        Retrieves the task with the specified task ID using the given connection.
        Parameters:
        connection - The connection to the Directory Server from which to retrieve the task. It must not be null.
        taskID - The task ID for the task to retrieve. It must not be null.
        Returns:
        The requested task, or null if no such task exists in the server. An attempt will be made to instantiate the task as the most appropriate task type, but if this is not possible then it will be a generic Task object.
        Throws:
        LDAPException - If a problem occurs while communicating with the Directory Server over the provided connection.
        TaskException - If the retrieved entry cannot be parsed as a task.
      • getTask

        @Nullable
        public static Task getTask​(@NotNull
                                   java.lang.String taskID,
                                   @NotNull
                                   LDAPInterface connection)
                            throws LDAPException,
                                   TaskException
        Retrieves the task with the specified task ID using the given connection.
        Parameters:
        connection - The connection to the Directory Server from which to retrieve the task. It must not be null.
        taskID - The task ID for the task to retrieve. It must not be null.
        Returns:
        The requested task, or null if no such task exists in the server. An attempt will be made to instantiate the task as the most appropriate task type, but if this is not possible then it will be a generic Task object.
        Throws:
        LDAPException - If a problem occurs while communicating with the Directory Server over the provided connection.
        TaskException - If the retrieved entry cannot be parsed as a task.
      • getTasks

        @NotNull
        public static java.util.List<TaskgetTasks​(@NotNull
                                                    LDAPConnection connection)
                                             throws LDAPException
        Retrieves all of the tasks defined in the Directory Server using the provided connection.
        Parameters:
        connection - The connection to the Directory Server instance from which to retrieve the defined tasks.
        Returns:
        A list of all tasks defined in the associated Directory Server.
        Throws:
        LDAPException - If a problem occurs while communicating with the Directory Server over the provided connection.
      • getTasks

        @NotNull
        public static java.util.List<TaskgetTasks​(@NotNull
                                                    LDAPInterface connection)
                                             throws LDAPException
        Retrieves all of the tasks defined in the Directory Server using the provided connection.
        Parameters:
        connection - The connection to the Directory Server instance from which to retrieve the defined tasks.
        Returns:
        A list of all tasks defined in the associated Directory Server.
        Throws:
        LDAPException - If a problem occurs while communicating with the Directory Server over the provided connection.
      • scheduleTask

        @NotNull
        public static Task scheduleTask​(@NotNull
                                        Task task,
                                        @NotNull
                                        LDAPConnection connection)
                                 throws LDAPException,
                                        TaskException
        Schedules a new instance of the provided task in the Directory Server.
        Parameters:
        task - The task to be scheduled.
        connection - The connection to the Directory Server in which the task is to be scheduled.
        Returns:
        A Task object representing the task that was scheduled and re-read from the server.
        Throws:
        LDAPException - If a problem occurs while communicating with the Directory Server, or if it rejects the task.
        TaskException - If the entry read back from the server after the task was created could not be parsed as a task.
      • scheduleTask

        @NotNull
        public static Task scheduleTask​(@NotNull
                                        Task task,
                                        @NotNull
                                        LDAPInterface connection)
                                 throws LDAPException,
                                        TaskException
        Schedules a new instance of the provided task in the Directory Server.
        Parameters:
        task - The task to be scheduled.
        connection - The connection to the Directory Server in which the task is to be scheduled.
        Returns:
        A Task object representing the task that was scheduled and re-read from the server.
        Throws:
        LDAPException - If a problem occurs while communicating with the Directory Server, or if it rejects the task.
        TaskException - If the entry read back from the server after the task was created could not be parsed as a task.
      • cancelTask

        public static void cancelTask​(@NotNull
                                      java.lang.String taskID,
                                      @NotNull
                                      LDAPConnection connection)
                               throws LDAPException
        Submits a request to cancel the task with the specified task ID. Note that some tasks may not support being canceled. Further, for tasks that do support being canceled it may take time for the cancel request to be processed and for the task to actually be canceled.
        Parameters:
        taskID - The task ID of the task to be canceled.
        connection - The connection to the Directory Server in which to perform the operation.
        Throws:
        LDAPException - If a problem occurs while communicating with the Directory Server.
      • cancelTask

        public static void cancelTask​(@NotNull
                                      java.lang.String taskID,
                                      @NotNull
                                      LDAPInterface connection)
                               throws LDAPException
        Submits a request to cancel the task with the specified task ID. Note that some tasks may not support being canceled. Further, for tasks that do support being canceled it may take time for the cancel request to be processed and for the task to actually be canceled.
        Parameters:
        taskID - The task ID of the task to be canceled.
        connection - The connection to the Directory Server in which to perform the operation.
        Throws:
        LDAPException - If a problem occurs while communicating with the Directory Server.
      • deleteTask

        public static void deleteTask​(@NotNull
                                      java.lang.String taskID,
                                      @NotNull
                                      LDAPConnection connection)
                               throws LDAPException
        Attempts to delete the task with the specified task ID.
        Parameters:
        taskID - The task ID of the task to be deleted.
        connection - The connection to the Directory Server in which to perform the operation.
        Throws:
        LDAPException - If a problem occurs while communicating with the Directory Server.
      • deleteTask

        public static void deleteTask​(@NotNull
                                      java.lang.String taskID,
                                      @NotNull
                                      LDAPInterface connection)
                               throws LDAPException
        Attempts to delete the task with the specified task ID.
        Parameters:
        taskID - The task ID of the task to be deleted.
        connection - The connection to the Directory Server in which to perform the operation.
        Throws:
        LDAPException - If a problem occurs while communicating with the Directory Server.
      • waitForTask

        @NotNull
        public static Task waitForTask​(@NotNull
                                       java.lang.String taskID,
                                       @NotNull
                                       LDAPConnection connection,
                                       long pollFrequency,
                                       long maxWaitTime)
                                throws LDAPException,
                                       TaskException
        Waits for the specified task to complete.
        Parameters:
        taskID - The task ID of the task to poll.
        connection - The connection to the Directory Server containing the desired task.
        pollFrequency - The minimum length of time in milliseconds between checks to see if the task has completed. A value less than or equal to zero will cause the client to check as quickly as possible.
        maxWaitTime - The maximum length of time in milliseconds to wait for the task to complete before giving up. A value less than or equal to zero indicates that it will keep checking indefinitely until the task has completed.
        Returns:
        Task The decoded task after it has completed, or after the maximum wait time has expired.
        Throws:
        LDAPException - If a problem occurs while communicating with the Directory Server.
        TaskException - If a problem occurs while attempting to parse the task entry as a task, or if the specified task entry could not be found.
      • waitForTask

        @NotNull
        public static Task waitForTask​(@NotNull
                                       java.lang.String taskID,
                                       @NotNull
                                       LDAPInterface connection,
                                       long pollFrequency,
                                       long maxWaitTime)
                                throws LDAPException,
                                       TaskException
        Waits for the specified task to complete.
        Parameters:
        taskID - The task ID of the task to poll.
        connection - The connection to the Directory Server containing the desired task.
        pollFrequency - The minimum length of time in milliseconds between checks to see if the task has completed. A value less than or equal to zero will cause the client to check as quickly as possible.
        maxWaitTime - The maximum length of time in milliseconds to wait for the task to complete before giving up. A value less than or equal to zero indicates that it will keep checking indefinitely until the task has completed.
        Returns:
        Task The decoded task after it has completed, or after the maximum wait time has expired.
        Throws:
        LDAPException - If a problem occurs while communicating with the Directory Server.
        TaskException - If a problem occurs while attempting to parse the task entry as a task, or if the specified task entry could not be found.