Package com.unboundid.ldap.sdk.unboundidds.tasks

Class Task

java.lang.Object
com.unboundid.ldap.sdk.unboundidds.tasks.Task
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
AddSchemaFileTask, AlertTask, AuditDataSecurityTask, BackupTask, CollectSupportDataTask, DelayTask, DisconnectClientTask, DumpDBDetailsTask, EnterLockdownModeTask, ExecTask, ExportTask, FileRetentionTask, GenerateServerProfileTask, GroovyScriptedTask, ImportTask, LeaveLockdownModeTask, PopulateComposedAttributeValuesTask, RebuildTask, ReEncodeEntriesTask, RefreshCertificateMonitorTask, RefreshEncryptionSettingsTask, ReloadGlobalIndexTask, ReloadHTTPConnectionHandlerCertificatesTask, RemoveAttributeTypeTask, RemoveObjectClassTask, RestoreTask, RotateLogTask, SearchTask, ShutdownTask, SynchronizeEncryptionSettingsTask, ThirdPartyTask
@NotExtensible @ThreadSafety(level=COMPLETELY_THREADSAFE) public class Task extends Object implements Serializable
This class defines a data structure for holding information about scheduled tasks as used by the Ping Identity, UnboundID, or Nokia/Alcatel-Lucent 8661 Directory Server. Subclasses will be used to provide additional functionality when dealing with certain types of tasks.
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.

All types of tasks can include the following information:
  • Task ID -- Uniquely identifies the task in the server. It may be omitted when scheduling a new task in order to have a task ID generated for the task.
  • Task Class Name -- The fully-qualified name of the Task subclass that provides the logic for the task. This does not need to be provided when creating a new task from one of the task-specific subclasses.
  • Task State -- The current state of the task. See the TaskState enum for information about the possible states that a task may have.
  • Scheduled Start Time -- The earliest time that the task should be eligible to start. It may be omitted when scheduling a new task in order to use the current time.
  • Actual Start Time -- The time that server started processing the task.
  • Actual Start Time -- The time that server completed processing for the task.
  • Dependency IDs -- A list of task IDs for tasks that must complete before this task may be considered eligible to start.
  • Failed Dependency Action -- Specifies how the server should treat this task if any of the tasks on which it depends failed. See the FailedDependencyAction enum for the failed dependency action values that may be used.
  • Notify on Completion -- A list of e-mail addresses for users that should be notified when the task completes, regardless of whether it was successful.
  • Notify On Error -- A list of e-mail addresses for users that should be notified if the task fails.
  • Log Messages -- A list of the messages logged by the task while it was running.
Each of these elements can be retrieving using specific methods within this class (e.g., the getTaskID() method can be used to retrieve the task ID), but task properties (including those specific to the particular type to task) may also be accessed using a generic API. For example, the getTaskPropertyValues() method retrieves a map that correlates the TaskProperty objects for the task with the values that have been set for those properties. See the documentation for the TaskManager class for an example that demonstrates accessing task information using the generic API.

Also note that it is possible to create new tasks using information obtained from the generic API, but that is done on a per-class basis. For example, in order to create a new BackupTask instance using the generic API, you would use the BackupTask(Map) constructor, in which the provided map contains a mapping between the properties and their values for that task. The getTaskSpecificProperties() method may be used to retrieve a list of the task-specific properties that may be provided when scheduling a task, and the getCommonTaskProperties() method may be used to retrieve a list of properties that can be provided when scheduling any type of task.
See Also:

  • Constructor Details

    • Task

      protected Task()
      Creates a new uninitialized task instance which should only be used for obtaining general information about this task, including the task name, description, and supported properties. Attempts to use a task created with this constructor for any other reason will likely fail.

    • Task

      public Task(@Nullable String taskID, @NotNull String taskClassName)
      Creates a new unscheduled task with the specified task ID and class name.
      Parameters:
      taskID - The task ID to use for this task. If it is null then a UUID will be generated for use as the task ID.
      taskClassName - The fully-qualified name of the Java class that provides the logic for the task. It must not be null.

    • Task

      public Task(@Nullable String taskID, @NotNull String taskClassName, @Nullable Date scheduledStartTime, @Nullable List<String> dependencyIDs, @Nullable FailedDependencyAction failedDependencyAction, @Nullable List<String> notifyOnCompletion, @Nullable List<String> notifyOnError)
      Creates a new unscheduled task with the provided information.
      Parameters:
      taskID - The task ID to use for this task.
      taskClassName - The fully-qualified name of the Java class that provides the logic for the task. It must not be null.
      scheduledStartTime - The time that this task should start running.
      dependencyIDs - The list of task IDs that will be required to complete before this task will be eligible to start.
      failedDependencyAction - Indicates what action should be taken if any of the dependencies for this task do not complete successfully.
      notifyOnCompletion - The list of e-mail addresses of individuals that should be notified when this task completes.
      notifyOnError - The list of e-mail addresses of individuals that should be notified if this task does not complete successfully.

    • Task

      public Task(@Nullable String taskID, @NotNull String taskClassName, @Nullable Date scheduledStartTime, @Nullable List<String> dependencyIDs, @Nullable FailedDependencyAction failedDependencyAction, @Nullable List<String> notifyOnStart, @Nullable List<String> notifyOnCompletion, @Nullable List<String> notifyOnSuccess, @Nullable List<String> notifyOnError, @Nullable Boolean alertOnStart, @Nullable Boolean alertOnSuccess, @Nullable Boolean alertOnError)
      Creates a new unscheduled task with the provided information.
      Parameters:
      taskID - The task ID to use for this task.
      taskClassName - The fully-qualified name of the Java class that provides the logic for the task. It must not be null.
      scheduledStartTime - The time that this task should start running.
      dependencyIDs - The list of task IDs that will be required to complete before this task will be eligible to start.
      failedDependencyAction - Indicates what action should be taken if any of the dependencies for this task do not complete successfully.
      notifyOnStart - The list of e-mail addresses of individuals that should be notified when this task starts running.
      notifyOnCompletion - The list of e-mail addresses of individuals that should be notified when this task completes.
      notifyOnSuccess - The list of e-mail addresses of individuals that should be notified if this task completes successfully.
      notifyOnError - The list of e-mail addresses of individuals that should be notified if this task does not complete successfully.
      alertOnStart - Indicates whether the server should send an alert notification when this task starts.
      alertOnSuccess - Indicates whether the server should send an alert notification if this task completes successfully.
      alertOnError - Indicates whether the server should send an alert notification if this task fails to complete successfully.

    • Task

      public Task(@NotNull Entry entry) throws TaskException
      Creates a new task from the provided entry.
      Parameters:
      entry - The entry to use to create this task.
      Throws:
      TaskException - If the provided entry cannot be parsed as a scheduled task.

    • Task

      public Task(@NotNull String taskClassName, @NotNull Map<TaskProperty,List<Object>> properties) throws TaskException
      Creates a new task from the provided set of task properties.
      Parameters:
      taskClassName - The fully-qualified name of the Java class that provides the logic for the task. It must not be null.
      properties - The set of task properties and their corresponding values to use for the task. It must not be null.
      Throws:
      TaskException - If the provided set of properties cannot be used to create a valid scheduled task.

  • Method Details

    • getAvailableTaskTypes

      @NotNull public static List<Task> getAvailableTaskTypes()
      Retrieves a list containing instances of the available task types. The provided task instances will may only be used for obtaining general information about the task (e.g., name, description, and supported properties).
      Returns:
      A list containing instances of the available task types.

    • getTaskName

      @NotNull public String getTaskName()
      Retrieves a human-readable name for this task.
      Returns:
      A human-readable name for this task.

    • getTaskDescription

      @NotNull public String getTaskDescription()
      Retrieves a human-readable description for this task.
      Returns:
      A human-readable description for this task.

    • getTaskEntry

      @Nullable protected final Entry getTaskEntry()
      Retrieves the entry from which this task was decoded, if available. Note that although the entry is not immutable, changes made to it will not be reflected in this task.
      Returns:
      The entry from which this task was decoded, or null if this task was not created from an existing entry.

    • getTaskEntryDN

      @NotNull public final String getTaskEntryDN()
      Retrieves the DN of the entry in which this scheduled task is defined.
      Returns:
      The DN of the entry in which this scheduled task is defined.

    • getTaskID

      @NotNull public final String getTaskID()
      Retrieves the task ID for this task.
      Returns:
      The task ID for this task.

    • getTaskClassName

      @NotNull public final String getTaskClassName()
      Retrieves the fully-qualified name of the Java class that provides the logic for this class.
      Returns:
      The fully-qualified name of the Java class that provides the logic for this task.

    • getState

      @NotNull public final TaskState getState()
      Retrieves the current state for this task.
      Returns:
      The current state for this task.

    • isPending

      public final boolean isPending()
      Indicates whether this task is currently pending execution.
      Returns:
      true if this task is currently pending execution, or false if not.

    • isRunning

      public final boolean isRunning()
      Indicates whether this task is currently running.
      Returns:
      true if this task is currently running, or false if not.

    • isCompleted

      public final boolean isCompleted()
      Indicates whether this task has completed execution.
      Returns:
      true if this task has completed execution, or false if not.

    • getScheduledStartTime

      @Nullable public final Date getScheduledStartTime()
      Retrieves the time that this task is/was scheduled to start running.
      Returns:
      The time that this task is/was scheduled to start running, or null if that is not available and therefore the task should start running as soon as all dependencies have been met.

    • getActualStartTime

      @Nullable public final Date getActualStartTime()
      Retrieves the time that this task actually started running.
      Returns:
      The time that this task actually started running, or null if that is not available (e.g., because the task has not yet started).

    • getCompletionTime

      @Nullable public final Date getCompletionTime()
      Retrieves the time that this task completed.
      Returns:
      The time that this task completed, or null if it has not yet completed.

    • getDependencyIDs

      @NotNull public final List<String> getDependencyIDs()
      Retrieves a list of the task IDs for tasks that must complete before this task will be eligible to start.
      Returns:
      A list of the task IDs for tasks that must complete before this task will be eligible to start, or an empty list if this task does not have any dependencies.

    • getFailedDependencyAction

      @Nullable public final FailedDependencyAction getFailedDependencyAction()
      Retrieves the failed dependency action for this task, which indicates the behavior that it should exhibit if any of its dependencies encounter a failure.
      Returns:
      The failed dependency action for this task, or null if it is not available.

    • getLogMessages

      @NotNull public final List<String> getLogMessages()
      Retrieves the log messages for this task. Note that if the task has generated a very large number of log messages, then only a portion of the most recent messages may be available.
      Returns:
      The log messages for this task, or an empty list if this task does not have any log messages.

    • getNotifyOnStartAddresses

      @NotNull public final List<String> getNotifyOnStartAddresses()
      Retrieves a list of the e-mail addresses of the individuals that should be notified whenever this task starts running.
      Returns:
      A list of the e-mail addresses of the individuals that should be notified whenever this task starts running, or an empty list if there are none.

    • getNotifyOnCompletionAddresses

      @NotNull public final List<String> getNotifyOnCompletionAddresses()
      Retrieves a list of the e-mail addresses of the individuals that should be notified whenever this task completes processing, regardless of whether it was successful.
      Returns:
      A list of the e-mail addresses of the individuals that should be notified whenever this task completes processing, or an empty list if there are none.

    • getNotifyOnSuccessAddresses

      @NotNull public final List<String> getNotifyOnSuccessAddresses()
      Retrieves a list of the e-mail addresses of the individuals that should be notified if this task completes successfully.
      Returns:
      A list of the e-mail addresses of the individuals that should be notified if this task completes successfully, or an empty list if there are none.

    • getNotifyOnErrorAddresses

      @NotNull public final List<String> getNotifyOnErrorAddresses()
      Retrieves a list of the e-mail addresses of the individuals that should be notified if this task stops processing prematurely due to an error or other external action (e.g., server shutdown or administrative cancel).
      Returns:
      A list of the e-mail addresses of the individuals that should be notified if this task stops processing prematurely, or an empty list if there are none.

    • getAlertOnStart

      @Nullable public final Boolean getAlertOnStart()
      Retrieves the flag that indicates whether the server should generate an administrative alert when this task starts running.
      Returns:
      true if the server should send an alert when this task starts running, false if the server should not send an alert, or null if it is not available.

    • getAlertOnSuccess

      @Nullable public final Boolean getAlertOnSuccess()
      Retrieves the flag that indicates whether the server should generate an administrative alert if this task completes successfully.
      Returns:
      true if the server should send an alert if this task completes successfully, false if the server should not send an alert, or null if it is not available.

    • getAlertOnError

      @Nullable public final Boolean getAlertOnError()
      Retrieves the flag that indicates whether the server should generate an administrative alert if this task fails to complete successfully.
      Returns:
      true if the server should send an alert if this task fails to complete successfully, false if the server should not send an alert, or null if it is not available.

    • createTaskEntry

      @NotNull public final Entry createTaskEntry()
      Creates an entry that may be added to the Directory Server to create a new instance of this task.
      Returns:
      An entry that may be added to the Directory Server to create a new instance of this task.

    • parseBooleanValue

      protected static boolean parseBooleanValue(@NotNull Entry taskEntry, @NotNull String attributeName, boolean defaultValue) throws TaskException
      Parses the value of the specified attribute as a boolean value, or throws an exception if the value cannot be decoded as a boolean.
      Parameters:
      taskEntry - The entry containing the attribute to be parsed.
      attributeName - The name of the attribute from which the value was taken.
      defaultValue - The default value to use if the provided value string is null.
      Returns:
      true if the value string represents a boolean value of true, false if the value string represents a boolean value of false, or the default value if the value string is null.
      Throws:
      TaskException - If the provided value string cannot be parsed as a boolean value.

    • parseStringList

      @NotNull protected static List<String> parseStringList(@NotNull Entry taskEntry, @NotNull String attributeName)
      Parses the values of the specified attribute as a list of strings.
      Parameters:
      taskEntry - The entry containing the attribute to be parsed.
      attributeName - The name of the attribute from which the value was taken.
      Returns:
      A list of strings containing the values of the specified attribute, or an empty list if the specified attribute does not exist in the target entry. The returned list will be unmodifiable.

    • parseBoolean

      @Nullable protected static Boolean parseBoolean(@NotNull TaskProperty p, @NotNull List<Object> values, @Nullable Boolean defaultValue) throws TaskException
      Parses the provided set of values for the associated task property as a Boolean.
      Parameters:
      p - The task property with which the values are associated.
      values - The provided values for the task property.
      defaultValue - The default value to use if the provided object array is empty.
      Returns:
      The parsed Boolean value.
      Throws:
      TaskException - If there is a problem with the provided values.

    • parseDate

      @Nullable protected static Date parseDate(@NotNull TaskProperty p, @NotNull List<Object> values, @Nullable Date defaultValue) throws TaskException
      Parses the provided set of values for the associated task property as a Date.
      Parameters:
      p - The task property with which the values are associated.
      values - The provided values for the task property.
      defaultValue - The default value to use if the provided object array is empty.
      Returns:
      The parsed Date value.
      Throws:
      TaskException - If there is a problem with the provided values.

    • parseLong

      @Nullable protected static Long parseLong(@NotNull TaskProperty p, @NotNull List<Object> values, @Nullable Long defaultValue) throws TaskException
      Parses the provided set of values for the associated task property as a Long.
      Parameters:
      p - The task property with which the values are associated.
      values - The provided values for the task property.
      defaultValue - The default value to use if the provided object array is empty.
      Returns:
      The parsed Long value.
      Throws:
      TaskException - If there is a problem with the provided values.

    • parseString

      @Nullable protected static String parseString(@NotNull TaskProperty p, @NotNull List<Object> values, @Nullable String defaultValue) throws TaskException
      Parses the provided set of values for the associated task property as a String.
      Parameters:
      p - The task property with which the values are associated.
      values - The provided values for the task property.
      defaultValue - The default value to use if the provided object array is empty.
      Returns:
      The parsed String value.
      Throws:
      TaskException - If there is a problem with the provided values.

    • parseStrings

      @Nullable protected static String[] parseStrings(@NotNull TaskProperty p, @NotNull List<Object> values, @Nullable String[] defaultValues) throws TaskException
      Parses the provided set of values for the associated task property as a String array.
      Parameters:
      p - The task property with which the values are associated.
      values - The provided values for the task property.
      defaultValues - The set of default values to use if the provided object array is empty.
      Returns:
      The parsed String values.
      Throws:
      TaskException - If there is a problem with the provided values.

    • getAdditionalObjectClasses

      @NotNull protected List<String> getAdditionalObjectClasses()
      Retrieves a list of the additional object classes (other than the base "top" and "ds-task" classes) that should be included when creating new task entries of this type.
      Returns:
      A list of the additional object classes that should be included in new task entries of this type, or an empty list if there do not need to be any additional classes.

    • getAdditionalAttributes

      @NotNull protected List<Attribute> getAdditionalAttributes()
      Retrieves a list of the additional attributes (other than attributes common to all task types) that should be included when creating new task entries of this type.
      Returns:
      A list of the additional attributes that should be included in new task entries of this type, or an empty list if there do not need to be any additional attributes.

    • decodeTask

      @NotNull public static Task decodeTask(@NotNull Entry entry) throws TaskException
      Decodes the provided entry as a scheduled task. An attempt will be made to decode the entry as an appropriate subclass if possible, but it will fall back to a generic task if it is not possible to decode as a more specific task type.
      Parameters:
      entry - The entry to be decoded.
      Returns:
      The decoded task.
      Throws:
      TaskException - If the provided entry cannot be parsed as a scheduled task.

    • getCommonTaskProperties

      @NotNull public static List<TaskProperty> getCommonTaskProperties()
      Retrieves a list of task properties that may be provided when scheduling any type of task. This includes:
      • The task ID
      • The scheduled start time
      • The task IDs of any tasks on which this task is dependent
      • The action to take for this task if any of its dependencies fail
      • The addresses of users to notify when this task starts
      • The addresses of users to notify when this task completes
      • The addresses of users to notify if this task succeeds
      • The addresses of users to notify if this task fails
      • A flag indicating whether to generate an alert when the task starts
      • A flag indicating whether to generate an alert when the task succeeds
      • A flag indicating whether to generate an alert when the task fails
      Returns:
      A list of task properties that may be provided when scheduling any type of task.

    • getTaskSpecificProperties

      @NotNull public List<TaskProperty> getTaskSpecificProperties()
      Retrieves a list of task-specific properties that may be provided when scheduling a task of this type. This method should be overridden by subclasses in order to provide an appropriate set of properties.
      Returns:
      A list of task-specific properties that may be provided when scheduling a task of this type.

    • getTaskPropertyValues

      @NotNull public Map<TaskProperty,List<Object>> getTaskPropertyValues()
      Retrieves the values of the task properties for this task. The data type of the values will vary based on the data type of the corresponding task property and may be one of the following types: Boolean, Date, Long, or String. Task properties which do not have any values will be included in the map with an empty value list.

      Note that subclasses which have additional task properties should override this method and return a map which contains both the property values from this class (obtained from super.getTaskPropertyValues() and the values of their own task-specific properties.
      Returns:
      A map of the task property values for this task.

    • toString

      @NotNull public final String toString()
      Retrieves a string representation of this task.
      Overrides:
      toString in class Object
      Returns:
      A string representation of this task.

    • toString

      public final void toString(@NotNull StringBuilder buffer)
      Appends a string representation of this task to the provided buffer.
      Parameters:
      buffer - The buffer to which the string representation should be provided.