org.opends.server.backends.task
Class TaskScheduler

java.lang.Object
  extended by java.lang.Thread
      extended by org.opends.server.api.DirectoryThread
          extended by org.opends.server.backends.task.TaskScheduler
All Implemented Interfaces:
java.lang.Runnable, AlertGenerator

public class TaskScheduler
extends DirectoryThread
implements AlertGenerator

This class defines a task scheduler for the Directory Server that will control the execution of scheduled tasks and other administrative functions that need to occur on a regular basis.


Nested Class Summary
 
Nested classes/interfaces inherited from class java.lang.Thread
java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler
 
Field Summary
 
Fields inherited from class java.lang.Thread
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY
 
Constructor Summary
TaskScheduler(TaskBackend taskBackend)
          Creates a new task scheduler that will be used to ensure that tasks are invoked at the appropriate times.
 
Method Summary
 void addCompletedTask(Task completedTask)
          Adds the provided task to the set of completed tasks associated with the scheduler.
 void addRecurringTask(RecurringTask recurringTask, boolean scheduleIteration)
          Adds a recurring task to the scheduler, optionally scheduling the first iteration for processing.
 Task cancelTask(java.lang.String taskID)
          Attempts to cancel the task with the given task ID.
 RecurringTask entryToRecurringTask(Entry entry)
          Decodes the contents of the provided entry as a recurring task.
 Task entryToScheduledTask(Entry entry, Operation operation)
          Decodes the contents of the provided entry as a scheduled task.
 java.util.LinkedHashMap<java.lang.String,java.lang.String> getAlerts()
          Retrieves information about the set of alerts that this generator may produce.
 java.lang.String getClassName()
          Retrieves the fully-qualified name of the Java class for this alert generator implementation.
 DN getComponentEntryDN()
          Retrieves the DN of the configuration entry with which this alert generator is associated.
 long getEntryCount()
          Retrieves the total number of entries in the task backend.
 RecurringTask getRecurringTask(DN recurringTaskEntryDN)
          Retrieves the recurring task with the given recurring task ID.
 RecurringTask getRecurringTask(java.lang.String recurringTaskID)
          Retrieves the recurring task with the given recurring task ID.
 long getRecurringTaskCount()
          Retrieves the number of recurring tasks in the task backend.
 Entry getRecurringTaskEntry(DN recurringTaskEntryDN)
          Retrieves the recurring task entry with the provided DN.
 Entry getRecurringTaskParentEntry()
          Retrieves the entry that is the immediate parent for all recurring task entries in the task backend.
 Task getScheduledTask(DN taskEntryDN)
          Retrieves the scheduled task created from the specified entry.
 Task getScheduledTask(java.lang.String taskID)
          Retrieves the scheduled task with the given task ID.
 long getScheduledTaskCount()
          Retrieves the number of scheduled tasks in the task backend.
 Entry getScheduledTaskEntry(DN scheduledTaskEntryDN)
          Retrieves the scheduled task entry with the provided DN.
 Entry getScheduledTaskParentEntry()
          Retrieves the entry that is the immediate parent for all scheduled task entries in the task backend.
 TaskBackend getTaskBackend()
          Retrieves the task backend with which this scheduler is associated.
 Entry getTaskRootEntry()
          Retrieves the root entry that is the common ancestor for all entries in the task backend.
 void interruptRunningTasks(TaskState interruptState, Message interruptReason, boolean waitForStop)
          Attempts to interrupt any tasks that are actively running.
 Task removeCompletedTask(java.lang.String taskID)
          Removes the specified completed task.
 Task removePendingTask(java.lang.String taskID)
          Removes the specified pending task.
 RecurringTask removeRecurringTask(java.lang.String recurringTaskID)
          Removes the recurring task with the given ID.
 void run()
          Operates in a loop, launching tasks at the appropriate time and performing any necessary periodic cleanup.
 void scheduleTask(Task task, boolean writeState)
          Schedules the provided task for execution.
 boolean searchRecurringTasks(SearchOperation searchOperation)
          Compares the filter in the provided search operation against each of the recurring task entries, returning any that match.
 boolean searchScheduledTasks(SearchOperation searchOperation)
          Compares the filter in the provided search operation against each of the task entries, returning any that match.
 void stopScheduler()
          Stops the scheduler so that it will not start any scheduled tasks.
 boolean threadDone(TaskThread taskThread, Task completedTask)
          Indicates that processing has completed on the provided task thread and that it is now available for processing other tasks.
 void writeState()
          Writes state information about all tasks and recurring tasks to disk.
 
Methods inherited from class org.opends.server.api.DirectoryThread
getAssociatedTask, getCreationStackTrace, getDebugProperties, getParentThread, setAssociatedTask
 
Methods inherited from class java.lang.Thread
activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

TaskScheduler

public TaskScheduler(TaskBackend taskBackend)
              throws InitializationException
Creates a new task scheduler that will be used to ensure that tasks are invoked at the appropriate times.

Parameters:
taskBackend - The task backend with which this scheduler is associated.
Throws:
InitializationException - If a problem occurs while initializing the scheduler from the backing file.
Method Detail

addRecurringTask

public void addRecurringTask(RecurringTask recurringTask,
                             boolean scheduleIteration)
                      throws DirectoryException
Adds a recurring task to the scheduler, optionally scheduling the first iteration for processing.

Parameters:
recurringTask - The recurring task to add to the scheduler.
scheduleIteration - Indicates whether to schedule an iteration of the recurring task.
Throws:
DirectoryException - If a problem occurs while trying to add the recurring task (e.g., there's already another recurring task defined with the same ID).

removeRecurringTask

public RecurringTask removeRecurringTask(java.lang.String recurringTaskID)
                                  throws DirectoryException
Removes the recurring task with the given ID.

Parameters:
recurringTaskID - The ID of the recurring task to remove.
Returns:
The recurring task that was removed, or null if there was no such recurring task.
Throws:
DirectoryException - If there is currently a pending or running iteration of the associated recurring task.

scheduleTask

public void scheduleTask(Task task,
                         boolean writeState)
                  throws DirectoryException
Schedules the provided task for execution. If the scheduler is active and the start time has arrived, then the task will begin execution immediately. Otherwise, it will be placed in the pending queue to be started at the appropriate time.

Parameters:
task - The task to be scheduled.
writeState - Indicates whether the current state information for the scheduler should be persisted to disk once the task is scheduled.
Throws:
DirectoryException - If a problem occurs while trying to schedule the task (e.g., there's already another task defined with the same ID).

cancelTask

public Task cancelTask(java.lang.String taskID)
Attempts to cancel the task with the given task ID. This will only cancel the task if it has not yet started running. If it has started, then it will not be interrupted.

Parameters:
taskID - The task ID of the task to cancel.
Returns:
The requested task, which may or may not have actually been cancelled (the task state should make it possible to determine whether it was cancelled), or null if there is no such task.

removePendingTask

public Task removePendingTask(java.lang.String taskID)
                       throws DirectoryException
Removes the specified pending task. It will be completely removed rather than moving it to the set of completed tasks.

Parameters:
taskID - The task ID of the pending task to remove.
Returns:
The task that was removed.
Throws:
DirectoryException - If the requested task is not in the pending queue.

removeCompletedTask

public Task removeCompletedTask(java.lang.String taskID)
                         throws DirectoryException
Removes the specified completed task.

Parameters:
taskID - The task ID of the completed task to remove.
Returns:
The task that was removed.
Throws:
DirectoryException - If the requested task could not be found.

threadDone

public boolean threadDone(TaskThread taskThread,
                          Task completedTask)
Indicates that processing has completed on the provided task thread and that it is now available for processing other tasks. The thread may be immediately used for processing another task if appropriate.

Parameters:
taskThread - The thread that has completed processing on its previously-assigned task.
completedTask - The task for which processing has been completed.
Returns:
true if the thread should continue running and wait for the next task to process, or false if it should exit immediately.

addCompletedTask

public void addCompletedTask(Task completedTask)
Adds the provided task to the set of completed tasks associated with the scheduler. It will be automatically removed after the appropriate retention time has elapsed.

Parameters:
completedTask - The task for which processing has completed.

stopScheduler

public void stopScheduler()
Stops the scheduler so that it will not start any scheduled tasks. It will not attempt to interrupt any tasks that are already running. Note that once the scheduler has been stopped, it cannot be restarted and it will be necessary to restart the task backend to start a new scheduler instance.


interruptRunningTasks

public void interruptRunningTasks(TaskState interruptState,
                                  Message interruptReason,
                                  boolean waitForStop)
Attempts to interrupt any tasks that are actively running. This will not make any attempt to stop the scheduler.

Parameters:
interruptState - The state that should be assigned to the tasks if they are successfully interrupted.
interruptReason - A message indicating the reason that the tasks are to be interrupted.
waitForStop - Indicates whether this method should wait until all active tasks have stopped before returning.

run

public void run()
Operates in a loop, launching tasks at the appropriate time and performing any necessary periodic cleanup.

Specified by:
run in interface java.lang.Runnable
Overrides:
run in class java.lang.Thread

writeState

public void writeState()
Writes state information about all tasks and recurring tasks to disk.


getEntryCount

public long getEntryCount()
Retrieves the total number of entries in the task backend.

Returns:
The total number of entries in the task backend.

getScheduledTaskCount

public long getScheduledTaskCount()
Retrieves the number of scheduled tasks in the task backend.

Returns:
The total number of entries in the task backend.

getRecurringTaskCount

public long getRecurringTaskCount()
Retrieves the number of recurring tasks in the task backend.

Returns:
The total number of entries in the task backend.

getTaskBackend

public TaskBackend getTaskBackend()
Retrieves the task backend with which this scheduler is associated.

Returns:
The task backend with which this scheduler is associated.

getTaskRootEntry

public Entry getTaskRootEntry()
Retrieves the root entry that is the common ancestor for all entries in the task backend.

Returns:
The root entry that is the common ancestor for all entries in the task backend.

getScheduledTaskParentEntry

public Entry getScheduledTaskParentEntry()
Retrieves the entry that is the immediate parent for all scheduled task entries in the task backend.

Returns:
The entry that is the immediate parent for all scheduled task entries in the task backend.

getRecurringTaskParentEntry

public Entry getRecurringTaskParentEntry()
Retrieves the entry that is the immediate parent for all recurring task entries in the task backend.

Returns:
The entry that is the immediate parent for all recurring task entries in the task backend.

getScheduledTask

public Task getScheduledTask(java.lang.String taskID)
Retrieves the scheduled task with the given task ID.

Parameters:
taskID - The task ID for the scheduled task to retrieve.
Returns:
The requested scheduled task, or null if there is no such task.

getScheduledTask

public Task getScheduledTask(DN taskEntryDN)
Retrieves the scheduled task created from the specified entry.

Parameters:
taskEntryDN - The DN of the task configuration entry associated with the task to retrieve.
Returns:
The requested scheduled task, or null if there is no such task.

getScheduledTaskEntry

public Entry getScheduledTaskEntry(DN scheduledTaskEntryDN)
Retrieves the scheduled task entry with the provided DN. The caller should hold a read lock on the target entry.

Parameters:
scheduledTaskEntryDN - The entry DN that indicates which scheduled task entry to retrieve.
Returns:
The scheduled task entry with the provided DN, or null if no scheduled task has the provided DN.

searchScheduledTasks

public boolean searchScheduledTasks(SearchOperation searchOperation)
                             throws DirectoryException
Compares the filter in the provided search operation against each of the task entries, returning any that match. Note that only the search filter will be used -- the base and scope will be ignored, so the caller must ensure that they are correct for scheduled tasks.

Parameters:
searchOperation - The search operation to use when performing the search.
Returns:
true if processing should continue on the search operation, or false if it should not for some reason (e.g., a size or time limit was reached).
Throws:
DirectoryException - If a problem occurs while processing the search operation against the scheduled tasks.

getRecurringTask

public RecurringTask getRecurringTask(java.lang.String recurringTaskID)
Retrieves the recurring task with the given recurring task ID.

Parameters:
recurringTaskID - The recurring task ID for the recurring task to retrieve.
Returns:
The requested recurring task, or null if there is no such recurring task.

getRecurringTask

public RecurringTask getRecurringTask(DN recurringTaskEntryDN)
Retrieves the recurring task with the given recurring task ID.

Parameters:
recurringTaskEntryDN - The recurring task ID for the recurring task to retrieve.
Returns:
The requested recurring task, or null if there is no such recurring task.

getRecurringTaskEntry

public Entry getRecurringTaskEntry(DN recurringTaskEntryDN)
Retrieves the recurring task entry with the provided DN. The caller should hold a read lock on the target entry.

Parameters:
recurringTaskEntryDN - The entry DN that indicates which recurring task entry to retrieve.
Returns:
The recurring task entry with the provided DN, or null if no recurring task has the provided DN.

searchRecurringTasks

public boolean searchRecurringTasks(SearchOperation searchOperation)
                             throws DirectoryException
Compares the filter in the provided search operation against each of the recurring task entries, returning any that match. Note that only the search filter will be used -- the base and scope will be ignored, so the caller must ensure that they are correct for recurring tasks.

Parameters:
searchOperation - The search operation to use when performing the search.
Returns:
true if processing should continue on the search operation, or false if it should not for some reason (e.g., a size or time limit was reached).
Throws:
DirectoryException - If a problem occurs while processing the search operation against the recurring tasks.

entryToScheduledTask

public Task entryToScheduledTask(Entry entry,
                                 Operation operation)
                          throws DirectoryException
Decodes the contents of the provided entry as a scheduled task. The resulting task will not actually be scheduled for processing.

Parameters:
entry - The entry to decode as a scheduled task.
operation - The operation used to create this task in the server, or null if the operation is not available.
Returns:
The scheduled task decoded from the provided entry.
Throws:
DirectoryException - If the provided entry cannot be decoded as a scheduled task.

entryToRecurringTask

public RecurringTask entryToRecurringTask(Entry entry)
                                   throws DirectoryException
Decodes the contents of the provided entry as a recurring task. The resulting recurring task will not actually be added to the scheduler.

Parameters:
entry - The entry to decode as a recurring task.
Returns:
The recurring task decoded from the provided entry.
Throws:
DirectoryException - If the provided entry cannot be decoded as a recurring task.

getComponentEntryDN

public DN getComponentEntryDN()
Retrieves the DN of the configuration entry with which this alert generator is associated.

Specified by:
getComponentEntryDN in interface AlertGenerator
Returns:
The DN of the configuration entry with which this alert generator is associated.

getClassName

public java.lang.String getClassName()
Retrieves the fully-qualified name of the Java class for this alert generator implementation.

Specified by:
getClassName in interface AlertGenerator
Returns:
The fully-qualified name of the Java class for this alert generator implementation.

getAlerts

public java.util.LinkedHashMap<java.lang.String,java.lang.String> getAlerts()
Retrieves information about the set of alerts that this generator may produce. The map returned should be between the notification type for a particular notification and the human-readable description for that notification. This alert generator must not generate any alerts with types that are not contained in this list.

Specified by:
getAlerts in interface AlertGenerator
Returns:
Information about the set of alerts that this generator may produce.