com.sun.sgs.kernel
Interface TransactionScheduler

public interface TransactionScheduler

This interface is used to schedule transactional tasks for immediate, delayed, or periodic execution. Transactional tasks are short-lived: typically on the order of a few 10s of milliseconds) and not longer than the value of the property com.sun.sgs.txn.timeout. All tasks run through an implementation of TransactionScheduler will run transactionally, and may be re-tried in the event of failure.

Many methods will make a best effort to schedule a given task to run, but based on the policy of the implementation, the task and its owner, may be unable to accept the given task. In this case TaskRejectedException is thrown. To ensure that a task will be accepted, methods are provided to get a TaskReservation. This is especially useful for Service methods working within a transaction that need to ensure that a task will be accepted before they can commit.

If the result of running a task via the reserveTask or scheduleTask methods is an Exception which implements ExceptionRetryStatus, then its shouldRetry method is called to decide if the task should be re-tried. It is up to the scheduler implementation's policy to decide how and when tasks are re-run, but all failing tasks run through a TransactionScheduler that wish to be re-tried will eventually be re-run given available resources.

Note that re-try is handled slightly differently for runTask. See the documentation on that method for more details.

Method Summary

TaskQueue	createTaskQueue() Creates a new TaskQueue to use in scheduling dependent tasks.
TaskReservation	reserveTask(KernelRunnable task, Identity owner) Reserves the ability to run the given task.
TaskReservation	reserveTask(KernelRunnable task, Identity owner, long startTime) Reserves the ability to run the given task at a specified point in the future.
void	runTask(KernelRunnable task, Identity owner) Runs the given task synchronously, returning when the task has completed or throwing an exception if the task fails.
RecurringTaskHandle	scheduleRecurringTask(KernelRunnable task, Identity owner, long startTime, long period) Schedules a task to start running at a specified point in the future, and continuing running on a regular period starting from that initial point.
void	scheduleTask(KernelRunnable task, Identity owner) Schedules a task to run as soon as possible based on the specific scheduler implementation.
void	scheduleTask(KernelRunnable task, Identity owner, long startTime) Schedules a task to run at a specified point in the future.

Method Detail

reserveTask

TaskReservation reserveTask(KernelRunnable task,
                            Identity owner)

Reserves the ability to run the given task.

Parameters:

task - the KernelRunnable to execute

owner - the entity on who's behalf this task is run

Returns:

a TaskReservation for the task

Throws:

TaskRejectedException - if a reservation cannot be made

reserveTask

TaskReservation reserveTask(KernelRunnable task,
                            Identity owner,
                            long startTime)

Reserves the ability to run the given task at a specified point in the future. The startTime is a value in milliseconds measured from 1/1/1970.

Parameters:

task - the KernelRunnable to execute

owner - the entity on who's behalf this task is run

startTime - the time at which to start the task

Returns:

a TaskReservation for the task

Throws:

TaskRejectedException - if a reservation cannot be made

scheduleTask

void scheduleTask(KernelRunnable task,
                  Identity owner)

Schedules a task to run as soon as possible based on the specific scheduler implementation.

Parameters:

task - the KernelRunnable to execute

owner - the entity on who's behalf this task is run

Throws:

TaskRejectedException - if the given task is not accepted

scheduleTask

void scheduleTask(KernelRunnable task,
                  Identity owner,
                  long startTime)

Schedules a task to run at a specified point in the future. The startTime is a value in milliseconds measured from 1/1/1970. If the starting time has already passed, then the task is run immediately.

Parameters:

task - the KernelRunnable to execute

owner - the entity on who's behalf this task is run

startTime - the time at which to start the task

Throws:

TaskRejectedException - if the given task is not accepted

scheduleRecurringTask

RecurringTaskHandle scheduleRecurringTask(KernelRunnable task,
                                          Identity owner,
                                          long startTime,
                                          long period)

Schedules a task to start running at a specified point in the future, and continuing running on a regular period starting from that initial point. Unlike the other scheduleTask methods, this method will never fail to accept to the task so there is no need for a reservation. Note, however, that the task will not actually start executing until start is called on the returned RecurringTaskHandle.

At each execution point the scheduler will make a best effort to run the task, but based on available resources scheduling the task may fail. Regardless, the scheduler will always try again at the next execution time.

Parameters:

task - the KernelRunnable to execute

owner - the entity on who's behalf this task is run

startTime - the time at which to start the task

period - the length of time in milliseconds between each recurring task execution

Returns:

a RecurringTaskHandle used to manage the recurring task

Throws:

IllegalArgumentException - if period is less than or equal to zero

runTask

void runTask(KernelRunnable task,
             Identity owner)
             throws Exception

Runs the given task synchronously, returning when the task has completed or throwing an exception if the task fails. It is up to the TransactionScheduler implementation to decide when to run this task, so the task may be run immediately or it might be queued behind waiting tasks. The task may be handed off to another thread of control for execution. In all cases, the caller will block until the task completes or fails permanently.

As with all methods of TransactionScheduler, tasks run with runTask will be run transactionally. If the caller is not in an active transaction, then a transaction is created to run the task. If the caller is already part of an active transaction, then the task is run as part of that transaction, and the owner paramater is ignored.

When the caller is not part of an active transaction, then when the given task completes it will also attempt to commit. If committing the transaction fails, normal re-try behavior is applied. If the task requests to be re-tried, then it will be re-run according to the scheduler implementation's policy. In this case, runTask will not return until the task finally succeeds, or is no longer re-tried.

In the event that the caller is part of an active transaction, then there is no re-try applied in the case of a failure, and the transaction is not committed if the task completes successfully. This is because the system does not support nested transactions, and so the decision to commit or re-try is left to the active transaction.

Parameters:

task - the KernelRunnable to execute

owner - the entity on who's behalf this task is run

Throws:

TaskRejectedException - if the given task is not accepted

InterruptedException - if the calling thread is interrupted and the associated task does not complete

Exception - if the task fails and is not re-tried

createTaskQueue

TaskQueue createTaskQueue()

Creates a new TaskQueue to use in scheduling dependent tasks. Each task added to the queue will be run in a separate transaction. Re-try is applied to each transaction, and the next task in the queue is run only after the current task either completes successfully or fails permanently.

Returns:

a new TaskQueue