com.sun.sgs.app
Interface TaskManager


public interface TaskManager

Provides facilities for scheduling tasks. Each task is a serializable object that can be scheduled to be run now, at some time in the future, or periodically. For the methods that run at some delayed point in the future, the delay is taken from the moment when the scheduling method was called.

For all methods on TaskManager, if the instance of Task provided does not implement ManagedObject then the TaskManager will persist the Task until it finishes. This provides durability, and is particularly convenient for simple tasks that the developer doesn't wish to manage and remove manually. However, if the Task does implement ManagedObject, then it's assumed that the Task is already managed, and it is up to the developer to remove it from the DataManager when finished.

If the instance of Task provided to any of these methods is an instance of a class that has the RunWithNewIdentity annotation then that task will be run with a new owning identity. Periodic tasks will use this same owning identity for all recurrences. In practical terms, this means that the system will be able to recognize these tasks as distinct behavior from other tasks in the system.

Note that there is no assumed ordering provided by implementations of this interface. If two tasks are scheduled in a given transaction, it is undefined which task will run or complete first. Likewise, if a task is scheduled and then a second scheduled in a later transaction, there is no guarantee that the task scheduled in the previous transaction will complete first. If any ordering or dependency is required, this should be implemented within the tasks themselves.

See Also:
AppContext.getTaskManager(), Task, RunWithNewIdentity

Method Summary
 PeriodicTaskHandle schedulePeriodicTask(Task task, long delay, long period)
          Schedules a task to run periodically after a delay.
 void scheduleTask(Task task)
          Schedules a task to run now.
 void scheduleTask(Task task, long delay)
          Schedules a task to run after a delay.
 

Method Detail

scheduleTask

void scheduleTask(Task task)
Schedules a task to run now. The TaskManager will call the task's run method as soon as possible after the completion of the task in which this method is called, according to its scheduling algorithm.

If the call to the run method throws an exception, that exception implements ExceptionRetryStatus, and its shouldRetry method returns true, then the TaskManager will make further attempts to run the task. It will continue those attempts until either an attempt succeeds or it notices an exception is thrown that is not retryable. The TaskManager is permitted to treat a non-retryable exception as a hint. In particular, a task that throws a non-retryable exception may be retried if the node running the task crashes.

Parameters:
task - the task to run
Throws:
IllegalArgumentException - if task does not implement Serializable
TaskRejectedException - if the TaskManager refuses to accept the task because of resource limitations
TransactionException - if the operation failed because of a problem with the current transaction

scheduleTask

void scheduleTask(Task task,
                  long delay)
Schedules a task to run after a delay. The TaskManager will wait for the specified number of milliseconds, and then call the task's run method as soon as possible after the completion of the task in which this method is called, according to its scheduling algorithm.

If the call to the run method throws an exception, that exception implements ExceptionRetryStatus, and its shouldRetry method returns true, then the TaskManager will make further attempts to run the task. It will continue those attempts until either an attempt succeeds or it notices an exception is thrown that is not retryable. The TaskManager is permitted to treat a non-retryable exception as a hint. In particular, a task that throws a non-retryable exception may be retried if the node running the task crashes.

Parameters:
task - the task to run
delay - the number of milliseconds to delay before running the task
Throws:
IllegalArgumentException - if task does not implement Serializable, or if delay is less than 0
TaskRejectedException - if the TaskManager refuses to accept the task because of resource limitations
TransactionException - if the operation failed because of a problem with the current transaction

schedulePeriodicTask

PeriodicTaskHandle schedulePeriodicTask(Task task,
                                        long delay,
                                        long period)
Schedules a task to run periodically after a delay. The TaskManager will wait for the specified number of milliseconds, and then call the task's run method as soon as possible after the completion of the task in which this method is called, according to its scheduling algorithm. It will also arrange to run the task periodically at the specified interval following the delay until the PeriodicTaskHandle.cancel method is called on the associated handle. At the start of each period, which occurs period milliseconds after the scheduled start of the previous period, a new task will be scheduled to run. The TaskManager will make a best effort to run a new task in each period, but even if the task cannot be run in one period, a new task will always be scheduled for the following period. The TaskManager will wait until the current attempt to run the task has ended before making another attempt to run it, regardless of whether the attempts are for the same or different periods.

If the call to the run method throws an exception, that exception implements ExceptionRetryStatus, and its shouldRetry method returns true, then the TaskManager will make further attempts to run the task. It will continue those attempts until either an attempt succeeds or it notices an exception is thrown that is not retryable. Note that calls to PeriodicTaskHandle.cancel have no effect on attempts to retry a task after the first attempt. The TaskManager is permitted to treat a non-retryable exception as a hint. In particular, a task that throws a non-retryable exception may be retried if the node running the task crashes.

Parameters:
task - the task to run
delay - the number of milliseconds to delay before running the task
period - the number of milliseconds that should elapse between the starts of periodic attempts to run the task
Returns:
a handle for managing the scheduling of the task
Throws:
IllegalArgumentException - if task does not implement Serializable, if delay is less than 0, or if period is less than 0
TaskRejectedException - if the TaskManager refuses to accept the task because of resource limitations
TransactionException - if the operation failed because of a problem with the current transaction

Project Darkstar, Version 0.9.9.6
2009-05-08 15:39:40

Copyright © 2007-2009 Sun Microsystems, Inc. All rights reserved