DelayedAction (DellRoad Stuff Spring Classes 2.0.3 API)

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

Methods
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
    
    org.springframework.core.task.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)

Class DelayedAction

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Runnable

Constructor Detail

DelayedAction

DelayedAction

DelayedAction

DelayedAction

Method Detail

schedule

cancel

isScheduled

getScheduledTime

schedule