com.unboundid.ldap.sdk.unboundidds.tasks
Class Task

java.lang.Object
  extended by com.unboundid.ldap.sdk.unboundidds.tasks.Task
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
AddSchemaFileTask, AlertTask, AuditDataSecurityTask, BackupTask, DisconnectClientTask, DumpDBDetailsTask, EnterLockdownModeTask, ExportTask, GroovyScriptedTask, ImportTask, LeaveLockdownModeTask, RebuildTask, ReEncodeEntriesTask, RefreshEncryptionSettingsTask, ReloadGlobalIndexTask, RestoreTask, SearchTask, ShutdownTask, ThirdPartyTask

@NotExtensible
@ThreadSafety(level=COMPLETELY_THREADSAFE)
public class Task
extends java.lang.Object
implements java.io.Serializable

NOTE: This class is part of the Commercial Edition of the UnboundID LDAP SDK for Java. It is not available for use in applications that include only the Standard Edition of the LDAP SDK, and is not supported for use in conjunction with non-UnboundID products.
This class defines a data structure for holding information about scheduled tasks as used by the UnboundID Directory Server. Subclasses be used to provide additional functionality when dealing with certain types of tasks.

All types of tasks can include the following information: 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.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:
Serialized Form

Constructor Summary
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.
  Task(Entry entry)
          Creates a new task from the provided entry.
  Task(java.lang.String taskClassName, java.util.Map<TaskProperty,java.util.List<java.lang.Object>> properties)
          Creates a new task from the provided set of task properties.
  Task(java.lang.String taskID, java.lang.String taskClassName)
          Creates a new unscheduled task with the specified task ID and class name.
  Task(java.lang.String taskID, java.lang.String taskClassName, java.util.Date scheduledStartTime, java.util.List<java.lang.String> dependencyIDs, FailedDependencyAction failedDependencyAction, java.util.List<java.lang.String> notifyOnCompletion, java.util.List<java.lang.String> notifyOnError)
          Creates a new unscheduled task with the provided information.
 
Method Summary
 Entry createTaskEntry()
          Creates an entry that may be added to the Directory Server to create a new instance of this task.
static Task decodeTask(Entry entry)
          Decodes the provided entry as a scheduled task.
 java.util.Date getActualStartTime()
          Retrieves the time that this task actually started running.
protected  java.util.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.
protected  java.util.List<java.lang.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.
static java.util.List<Task> getAvailableTaskTypes()
          Retrieves a list containing instances of the available task types.
static java.util.List<TaskProperty> getCommonTaskProperties()
          Retrieves a list of task properties that may be provided when scheduling any type of task.
 java.util.Date getCompletionTime()
          Retrieves the time that this task completed.
 java.util.List<java.lang.String> getDependencyIDs()
          Retrieves a list of the task IDs for tasks that must complete before this task will be eligible to start.
 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.
 java.util.List<java.lang.String> getLogMessages()
          Retrieves the log messages for this task.
 java.util.List<java.lang.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.
 java.util.List<java.lang.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).
 java.util.Date getScheduledStartTime()
          Retrieves the time that this task is/was scheduled to start running.
 TaskState getState()
          Retrieves the current state for this task.
 java.lang.String getTaskClassName()
          Retrieves the fully-qualified name of the Java class that provides the logic for this class.
 java.lang.String getTaskDescription()
          Retrieves a human-readable description for this task.
protected  Entry getTaskEntry()
          Retrieves the entry from which this task was decoded, if available.
 java.lang.String getTaskEntryDN()
          Retrieves the DN of the entry in which this scheduled task is defined.
 java.lang.String getTaskID()
          Retrieves the task ID for this task.
 java.lang.String getTaskName()
          Retrieves a human-readable name for this task.
 java.util.Map<TaskProperty,java.util.List<java.lang.Object>> getTaskPropertyValues()
          Retrieves the values of the task properties for this task.
 java.util.List<TaskProperty> getTaskSpecificProperties()
          Retrieves a list of task-specific properties that may be provided when scheduling a task of this type.
 boolean isCompleted()
          Indicates whether this task has completed execution.
 boolean isPending()
          Indicates whether this task is currently pending execution.
 boolean isRunning()
          Indicates whether this task is currently running.
protected static java.lang.Boolean parseBoolean(TaskProperty p, java.util.List<java.lang.Object> values, java.lang.Boolean defaultValue)
          Parses the provided set of values for the associated task property as a Boolean.
protected static boolean parseBooleanValue(Entry taskEntry, java.lang.String attributeName, boolean defaultValue)
          Parses the value of the specified attribute as a boolean value, or throws an exception if the value cannot be decoded as a boolean.
protected static java.util.Date parseDate(TaskProperty p, java.util.List<java.lang.Object> values, java.util.Date defaultValue)
          Parses the provided set of values for the associated task property as a Date.
protected static java.lang.Long parseLong(TaskProperty p, java.util.List<java.lang.Object> values, java.lang.Long defaultValue)
          Parses the provided set of values for the associated task property as a Long.
protected static java.lang.String parseString(TaskProperty p, java.util.List<java.lang.Object> values, java.lang.String defaultValue)
          Parses the provided set of values for the associated task property as a String.
protected static java.util.List<java.lang.String> parseStringList(Entry taskEntry, java.lang.String attributeName)
          Parses the values of the specified attribute as a list of strings.
protected static java.lang.String[] parseStrings(TaskProperty p, java.util.List<java.lang.Object> values, java.lang.String[] defaultValues)
          Parses the provided set of values for the associated task property as a String array.
 java.lang.String toString()
          Retrieves a string representation of this task.
 void toString(java.lang.StringBuilder buffer)
          Appends a string representation of this task to the provided buffer.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

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(java.lang.String taskID,
            java.lang.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(java.lang.String taskID,
            java.lang.String taskClassName,
            java.util.Date scheduledStartTime,
            java.util.List<java.lang.String> dependencyIDs,
            FailedDependencyAction failedDependencyAction,
            java.util.List<java.lang.String> notifyOnCompletion,
            java.util.List<java.lang.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(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(java.lang.String taskClassName,
            java.util.Map<TaskProperty,java.util.List<java.lang.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 Detail

getAvailableTaskTypes

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

public java.lang.String getTaskName()
Retrieves a human-readable name for this task.

Returns:
A human-readable name for this task.

getTaskDescription

public java.lang.String getTaskDescription()
Retrieves a human-readable description for this task.

Returns:
A human-readable description for this task.

getTaskEntry

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

public final java.lang.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

public final java.lang.String getTaskID()
Retrieves the task ID for this task.

Returns:
The task ID for this task.

getTaskClassName

public final java.lang.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

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

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

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

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

public final java.util.List<java.lang.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

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

public final java.util.List<java.lang.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.

getNotifyOnCompletionAddresses

public final java.util.List<java.lang.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.

getNotifyOnErrorAddresses

public final java.util.List<java.lang.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.

createTaskEntry

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(Entry taskEntry,
                                           java.lang.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

protected static java.util.List<java.lang.String> parseStringList(Entry taskEntry,
                                                                  java.lang.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

protected static java.lang.Boolean parseBoolean(TaskProperty p,
                                                java.util.List<java.lang.Object> values,
                                                java.lang.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

protected static java.util.Date parseDate(TaskProperty p,
                                          java.util.List<java.lang.Object> values,
                                          java.util.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

protected static java.lang.Long parseLong(TaskProperty p,
                                          java.util.List<java.lang.Object> values,
                                          java.lang.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

protected static java.lang.String parseString(TaskProperty p,
                                              java.util.List<java.lang.Object> values,
                                              java.lang.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

protected static java.lang.String[] parseStrings(TaskProperty p,
                                                 java.util.List<java.lang.Object> values,
                                                 java.lang.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

protected java.util.List<java.lang.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

protected java.util.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

public static Task decodeTask(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

public static java.util.List<TaskProperty> getCommonTaskProperties()
Retrieves a list of task properties that may be provided when scheduling any type of task. This includes:

Returns:
A list of task properties that may be provided when scheduling any type of task.

getTaskSpecificProperties

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

public java.util.Map<TaskProperty,java.util.List<java.lang.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

public final java.lang.String toString()
Retrieves a string representation of this task.

Overrides:
toString in class java.lang.Object
Returns:
A string representation of this task.

toString

public final void toString(java.lang.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.