org.opends.server.backends.task
Class Task

java.lang.Object
  extended by org.opends.server.backends.task.Task
All Implemented Interfaces:
java.lang.Comparable<Task>
Direct Known Subclasses:
AddSchemaFileTask, BackupTask, DisconnectClientTask, EnterLockdownModeTask, ExportTask, ImportTask, InitializeTargetTask, InitializeTask, LeaveLockdownModeTask, RebuildTask, RestoreTask, SetGenerationIdTask, ShutdownTask

public abstract class Task
extends java.lang.Object
implements java.lang.Comparable<Task>

This class defines a task that may be executed by the task backend within the Directory Server.


Constructor Summary
Task()
           
 
Method Summary
 void addLogMessage(Message message)
          Adds a log message to the set of messages logged by this task.
 int compareTo(Task task)
          Compares this task with the provided task for the purposes of ordering in a sorted list.
 TaskState execute()
          Begins execution for this task.
 long getActualStartTime()
          Retrieves the time that this task actually started running, if it has started.
 Message getAttributeDisplayName(java.lang.String name)
          Given an attribute type name returns and locale sensitive representation.
 long getCompletionTime()
          Retrieves the time that this task completed all of its associated processing (regardless of whether it was successful), if it has completed.
 java.util.LinkedList<java.lang.String> getDependencyIDs()
          Retrieves the set of task IDs for any tasks on which this task is dependent.
 Message getDisplayName()
          Gets a message that identifies this type of task suitable for presentation to humans in monitoring tools.
 FailedDependencyAction getFailedDependencyAction()
          Retrieves the action that should be taken if any of the dependencies for this task do not complete successfully.
protected  TaskState getFinalTaskState()
          Returns a state for this task after processing has completed.
 java.util.List<Message> getLogMessages()
          Retrieves the set of messages that were logged by this task.
 java.util.LinkedList<java.lang.String> getNotifyOnCompletionAddresses()
          Retrieves the set of e-mail addresses for the users that should receive a notification message when processing for this task has completed.
 java.util.LinkedList<java.lang.String> getNotifyOnErrorAddresses()
          Retrieves the set of e-mail addresses for the users that should receive a notification message if processing for this task does not complete successfully.
 Operation getOperation()
          Retrieves the operation used to create this task in the server.
 java.lang.String getRecurringTaskID()
          Retrieves the unique identifier assigned to the recurring task that is associated with this task, if there is one.
 long getScheduledStartTime()
          Retrieves the scheduled start time for this task, if there is one.
 Entry getTaskEntry()
          Retrieves the entry containing the definition for this task.
 DN getTaskEntryDN()
          Retrieves the DN of the entry containing the definition for this task.
 java.lang.String getTaskID()
          Retrieves the unique identifier assigned to this task.
protected  TaskState getTaskInterruptState()
          Gets the interrupt state for this task that was set as a result of a call to interruptTask(TaskState, org.opends.messages.Message).
 TaskState getTaskState()
          Retrieves the current state for this task.
 void initializeTask()
          Performs any task-specific initialization that may be required before processing can start.
 void initializeTaskInternal(TaskScheduler taskScheduler, Entry taskEntry)
          Performs generic initialization for this task based on the information in the provided task entry.
 void interruptTask(TaskState interruptState, Message interruptReason)
          Performs any necessary processing to prematurely interrupt the execution of this task.
 boolean isCancelled()
          Indicates whether or not this task has been cancelled.
 boolean isInterruptable()
          Indicates whether or not this task is interruptable or not.
protected  void logError(Message message)
          Writes a message to the error log using the provided information.
protected  void replaceAttributeValue(java.lang.String name, java.lang.String value)
          Replaces an attribute values of the task entry.
protected abstract  TaskState runTask()
          Performs the actual core processing for this task.
 void setOperation(Operation operation)
          Specifies the operation used to create this task in the server.
protected  void setTaskInterruptState(TaskState state)
          Sets a state for this task that is the result of a call to interruptTask(TaskState, org.opends.messages.Message).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Task

public Task()
Method Detail

getDisplayName

public Message getDisplayName()
Gets a message that identifies this type of task suitable for presentation to humans in monitoring tools.

Returns:
name of task

getAttributeDisplayName

public Message getAttributeDisplayName(java.lang.String name)
Given an attribute type name returns and locale sensitive representation.

Parameters:
name - of an attribute type associated with the object class that represents this entry in the directory
Returns:
Message diaplay name

initializeTaskInternal

public final void initializeTaskInternal(TaskScheduler taskScheduler,
                                         Entry taskEntry)
                                  throws InitializationException
Performs generic initialization for this task based on the information in the provided task entry.

Parameters:
taskScheduler - The scheduler with which this task is associated.
taskEntry - The entry containing the task configuration.
Throws:
InitializationException - If a problem occurs while performing the initialization.

getTaskEntryDN

public final DN getTaskEntryDN()
Retrieves the DN of the entry containing the definition for this task.

Returns:
The DN of the entry containing the definition for this task.

getTaskEntry

public final Entry getTaskEntry()
Retrieves the entry containing the definition for this task.

Returns:
The entry containing the definition for this task.

getOperation

public final Operation getOperation()
Retrieves the operation used to create this task in the server. Note that this will only be available when the task is first added to the scheduler, and it should only be accessed from within the initializeTask method (and even that method should not depend on it always being available, since it will not be available if the server is restarted and the task needs to be reinitialized).

Returns:
The operation used to create this task in the server, or null if it is not available.

setOperation

public final void setOperation(Operation operation)
Specifies the operation used to create this task in the server.

Parameters:
operation - The operation used to create this task in the server.

getTaskID

public final java.lang.String getTaskID()
Retrieves the unique identifier assigned to this task.

Returns:
The unique identifier assigned to this task.

getRecurringTaskID

public final java.lang.String getRecurringTaskID()
Retrieves the unique identifier assigned to the recurring task that is associated with this task, if there is one.

Returns:
The unique identifier assigned to the recurring task that is associated with this task, or null if it is not associated with any recurring task.

getTaskState

public final TaskState getTaskState()
Retrieves the current state for this task.

Returns:
The current state for this task.

isCancelled

public boolean isCancelled()
Indicates whether or not this task has been cancelled.

Returns:
boolean where true indicates that this task was cancelled either before or during execution

setTaskInterruptState

protected void setTaskInterruptState(TaskState state)
Sets a state for this task that is the result of a call to interruptTask(TaskState, org.opends.messages.Message). It may take this task some time to actually cancel to that actual state may differ until quiescence.

Parameters:
state - for this task once it has canceled whatever it is doing

getTaskInterruptState

protected TaskState getTaskInterruptState()
Gets the interrupt state for this task that was set as a result of a call to interruptTask(TaskState, org.opends.messages.Message).

Returns:
interrupt state for this task

getFinalTaskState

protected TaskState getFinalTaskState()
Returns a state for this task after processing has completed. If the task was interrupted with a call to interruptTask(TaskState, org.opends.messages.Message) then that method's interruptState is returned here. Otherwse this method returns TaskState.COMPLETED_SUCCESSFULLY. It is assumed that if there were errors during task processing that task state will have been derived in some other way.

Returns:
state for this task after processing has completed

replaceAttributeValue

protected void replaceAttributeValue(java.lang.String name,
                                     java.lang.String value)
                              throws DirectoryException
Replaces an attribute values of the task entry.

Parameters:
name - The name of the attribute that must be replaced.
value - The value that must replace the previous values of the attribute.
Throws:
DirectoryException - When an error occurs.

getScheduledStartTime

public final long getScheduledStartTime()
Retrieves the scheduled start time for this task, if there is one. The value returned will be in the same format as the return value for System.currentTimeMillis(). Any value representing a time in the past, or any negative value, should be taken to mean that the task should be considered eligible for immediate execution.

Returns:
The scheduled start time for this task.

getActualStartTime

public final long getActualStartTime()
Retrieves the time that this task actually started running, if it has started. The value returned will be in the same format as the return value for System.currentTimeMillis().

Returns:
The time that this task actually started running, or -1 if it has not yet been started.

getCompletionTime

public final long getCompletionTime()
Retrieves the time that this task completed all of its associated processing (regardless of whether it was successful), if it has completed. The value returned will be in the same format as the return value for System.currentTimeMillis().

Returns:
The time that this task actually completed running, or -1 if it has not yet completed.

getDependencyIDs

public final java.util.LinkedList<java.lang.String> getDependencyIDs()
Retrieves the set of task IDs for any tasks on which this task is dependent. This list must not be directly modified by the caller.

Returns:
The set of task IDs for any tasks on which this task is dependent.

getFailedDependencyAction

public final FailedDependencyAction getFailedDependencyAction()
Retrieves the action that should be taken if any of the dependencies for this task do not complete successfully.

Returns:
The action that should be taken if any of the dependencies for this task do not complete successfully.

getNotifyOnCompletionAddresses

public final java.util.LinkedList<java.lang.String> getNotifyOnCompletionAddresses()
Retrieves the set of e-mail addresses for the users that should receive a notification message when processing for this task has completed. This notification will be sent to these users regardless of whether the task completed successfully. This list must not be directly modified by the caller.

Returns:
The set of e-mail addresses for the users that should receive a notification message when processing for this task has completed.

getNotifyOnErrorAddresses

public final java.util.LinkedList<java.lang.String> getNotifyOnErrorAddresses()
Retrieves the set of e-mail addresses for the users that should receive a notification message if processing for this task does not complete successfully. This list must not be directly modified by the caller.

Returns:
The set of e-mail addresses for the users that should receive a notification message if processing for this task does not complete successfully.

getLogMessages

public final java.util.List<Message> getLogMessages()
Retrieves the set of messages that were logged by this task. This list must not be directly modified by the caller.

Returns:
The set of messages that were logged by this task.

logError

protected void logError(Message message)
Writes a message to the error log using the provided information. Tasks should use this method to log messages to the error log instead of the one in org.opends.server.loggers.Error to ensure the messages are included in the ds-task-log-message attribute.

Parameters:
message - The message to be logged.

addLogMessage

public void addLogMessage(Message message)
Adds a log message to the set of messages logged by this task. This method should not be called directly by tasks, but rather will be called indirectly through the ErrorLog.logError methods. It does not automatically persist the updated task information to disk.

Parameters:
message - he log message

compareTo

public final int compareTo(Task task)
Compares this task with the provided task for the purposes of ordering in a sorted list. Any completed task will always be ordered before an uncompleted task. If both tasks are completed, then they will be ordered by completion time. If both tasks are uncompleted, then a running task will always be ordered before one that has not started. If both are running, then they will be ordered by actual start time. If neither have started, then they will be ordered by scheduled start time. If all else fails, they will be ordered lexicographically by task ID.

Specified by:
compareTo in interface java.lang.Comparable<Task>
Parameters:
task - The task to compare with this task.
Returns:
A negative value if the provided task should come before this task, a positive value if the provided task should come after this task, or zero if there is no difference with regard to their order.

execute

public final TaskState execute()
Begins execution for this task. This is a wrapper around the runTask method that performs the appropriate set-up and tear-down. It should only be invoked by a task thread.

Returns:
The final state to use for the task.

initializeTask

public void initializeTask()
                    throws DirectoryException
Performs any task-specific initialization that may be required before processing can start. This default implementation does not do anything, but subclasses may override it as necessary. This method will be called at the time the task is scheduled, and therefore any failure in this method will be returned to the client.

Throws:
DirectoryException - If a problem occurs during initialization that should be returned to the client.

runTask

protected abstract TaskState runTask()
Performs the actual core processing for this task. This method should not return until all processing associated with this task has completed.

Returns:
The final state to use for the task.

interruptTask

public void interruptTask(TaskState interruptState,
                          Message interruptReason)
Performs any necessary processing to prematurely interrupt the execution of this task. By default no action is performed, but if it is feasible to gracefully interrupt a task, then subclasses should override this method to do so. Implementations of this method are exprected to call setTaskInterruptState(TaskState) if the interruption is accepted by this task.

Parameters:
interruptState - The state to use for the task if it is successfully interrupted.
interruptReason - A human-readable explanation for the cancellation.

isInterruptable

public boolean isInterruptable()
Indicates whether or not this task is interruptable or not.

Returns:
boolean where true indicates that this task can be interrupted.