org.dellroad.stuff.spring

Class DelayedAction

java.lang.Object

org.dellroad.stuff.spring.DelayedAction

All Implemented Interfaces:

Runnable

public abstract class DelayedAction
extends Object
implements Runnable

Manages a delayed action without race conditions.

A "delayed action" is a some action that needs to get done by some time in the future.

This class does two things:

• It collapses multiple attempts to schedule the action into a single scheduled action, i.e., at most one outstanding scheduled action can exist at a time.
• It provides a race-free and 100% reliable way to cancel() a future scheduled action, if any.

The action itself is defined by the subclass' implementation of run().

To avoid races, this class requires the user to supply a locking object. This may either be a normal Java object, in which case normal Java synchronization is used, or a Lock object. The locking object is used to serialize scheduling activity and action invocation. In other words, the locking object is locked during the execution of schedule(), cancel(), and run().

Therefore, any time the locking object is locked, the state of this DelayedAction instance is "frozen" in one of three states: not scheduled, scheduled, or executing (in the latter case, of course the thread doing the executing is the one holding the lock). Therefore, to completely avoid race conditions, user code must itself lock the locking object itself prior to invoking any methods in this class.

Typically the most convenient locking object to use is the user's own this object, which can be locked using a synchronized method or block.

Note: in the case that run() invokes Object.wait() on the locking object, thereby temporarily releasing the lock, to any other methods in this class it will appear as if that execution has already completed.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DelayedAction(Lock lock, ScheduledExecutorService executorService) Constructor utitilizing a ScheduledExecutorService and a Lock for locking.
protected	DelayedAction(Lock lock, TaskScheduler taskScheduler) Constructor utitilizing a TaskScheduler and a Lock for locking.
protected	DelayedAction(Object lock, ScheduledExecutorService executorService) Constructor utitilizing a ScheduledExecutorService and normal Java object locking.
protected	DelayedAction(Object lock, TaskScheduler taskScheduler) Constructor utitilizing a TaskScheduler and normal Java object locking.

Method Summary

Modifier and Type	Method and Description
void	cancel() Cancel the future scheduled action, if any.
Date	getScheduledTime() Get the scheduled time for the outstanding scheduled action, if any.
boolean	isScheduled() Determine whether there is currently an outstanding scheduled action.
void	schedule(Date date) Schedule the delayed action for the given time.
protected ScheduledFuture<?>	schedule(Runnable action, Date date) Schedule the given action using the task scheduler passed to the constructor.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.lang.Runnable

run

Constructor Detail

DelayedAction

protected DelayedAction(Object lock,
                        TaskScheduler taskScheduler)

Constructor utitilizing a TaskScheduler and normal Java object locking.

Parameters:

lock - locking object used to serialize activity, or null for this

taskScheduler - scheduler object

Throws:

IllegalArgumentException - if taskScheduler is null

DelayedAction

protected DelayedAction(Object lock,
                        ScheduledExecutorService executorService)

Constructor utitilizing a ScheduledExecutorService and normal Java object locking.

Parameters:

lock - locking object used to serialize activity, or null for this

executorService - scheduler object

Throws:

IllegalArgumentException - if executorService is null

DelayedAction

protected DelayedAction(Lock lock,
                        TaskScheduler taskScheduler)

Constructor utitilizing a TaskScheduler and a Lock for locking.

Parameters:

lock - locking object used to serialize activity

taskScheduler - scheduler object

Throws:

IllegalArgumentException - if lock is null

IllegalArgumentException - if taskScheduler is null

DelayedAction

protected DelayedAction(Lock lock,
                        ScheduledExecutorService executorService)

Constructor utitilizing a ScheduledExecutorService and a Lock for locking.

Parameters:

lock - locking object used to serialize activity

executorService - scheduler object

Throws:

IllegalArgumentException - if lock is null

IllegalArgumentException - if executorService is null

Method Detail

schedule

public void schedule(Date date)

Schedule the delayed action for the given time.

More precisely:

• If an action currently executing, before doing anything else this method blocks until it completes; if this behavior is undesirable, the caller can avoid this behavior by synchronizing on the locking object prior to invoking this method.
• If no action is scheduled, one is scheduled for the given time.
• If an action is already scheduled, and the given time is on or after the scheduled time, nothing changes.
• If an action is already scheduled, and the given time is prior to the scheduled time, the action is rescheduled for the earlier time.

The net result is that, for any invocation, this method guarantees exactly one execution of the action will occur approximately on or before the given date; however, multiple invocations of this method prior to action execution can only ever result in a single "shared" action.

Parameters:

date - scheduled execution time (at the latest)

Throws:

IllegalArgumentException - if date is null

TaskRejectedException - if the given task was not accepted for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)

cancel

public void cancel()

Cancel the future scheduled action, if any.

More precisely:

• If an action currently executing, before doing anything else this method blocks until it completes; if this behavior is undesirable, the caller can avoid this behavior by synchronizing on the locking object prior to invoking this method.
• If an action is scheduled but has not started yet, it is guaranteed not to run.
• If no action is scheduled or executing, nothing changes.

isScheduled

public boolean isScheduled()

Determine whether there is currently an outstanding scheduled action.

Returns:

true if an action is pending

getScheduledTime

public Date getScheduledTime()

Get the scheduled time for the outstanding scheduled action, if any.

Returns:

oustanding action scheduled time, or null if there is no scheduled action

schedule

protected ScheduledFuture<?> schedule(Runnable action,
                                      Date date)

Schedule the given action using the task scheduler passed to the constructor. Use of this method does not change the state of this instance.

Parameters:

action - action to perform

date - when to perform it

Returns:

future for completion of action

Throws:

IllegalArgumentException - if either parameter is null

RejectedExecutionException - if the given task was not accepted for internal reasons (e.g. a pool overload handling policy or a pool shutdown in progress)