1 /*
2  * Written by Doug Lea with assistance from members of JCP JSR-166
3  * Expert Group and released to the public domain, as explained at
4  * http://creativecommons.org/publicdomain/zero/1.0/
5  */
6 
7 package java.util.concurrent;
8 
9 /**
10  * An {@link ExecutorService} that can schedule commands to run after a given
11  * delay, or to execute periodically.
12  *
13  * <p>The {@code schedule} methods create tasks with various delays
14  * and return a task object that can be used to cancel or check
15  * execution. The {@code scheduleAtFixedRate} and
16  * {@code scheduleWithFixedDelay} methods create and execute tasks
17  * that run periodically until cancelled.
18  *
19  * <p>Commands submitted using the {@link Executor#execute} and
20  * {@link ExecutorService} {@code submit} methods are scheduled with
21  * a requested delay of zero. Zero and negative delays (but not
22  * periods) are also allowed in {@code schedule} methods, and are
23  * treated as requests for immediate execution.
24  *
25  * <p>All {@code schedule} methods accept <em>relative</em> delays and
26  * periods as arguments, not absolute times or dates. It is a simple
27  * matter to transform an absolute time represented as a {@link
28  * java.util.Date} to the required form. For example, to schedule at
29  * a certain future {@code date}, you can use: {@code schedule(task,
30  * date.getTime() - System.currentTimeMillis(),
31  * TimeUnit.MILLISECONDS)}. Beware however that expiration of a
32  * relative delay need not coincide with the current {@code Date} at
33  * which the task is enabled due to network time synchronization
34  * protocols, clock drift, or other factors.
35  *
36  * The {@link Executors} class provides convenient factory methods for
37  * the ScheduledExecutorService implementations provided in this package.
38  *
39  * <h3>Usage Example</h3>
40  *
41  * Here is a class with a method that sets up a ScheduledExecutorService
42  * to beep every ten seconds for an hour:
43  *
44  *  <pre> {@code
45  * import static java.util.concurrent.TimeUnit.*;
46  * class BeeperControl {
47  *   private final ScheduledExecutorService scheduler =
48  *     Executors.newScheduledThreadPool(1);
49  *
50  *   public void beepForAnHour() {
51  *     final Runnable beeper = new Runnable() {
52  *       public void run() { System.out.println("beep"); }
53  *     };
54  *     final ScheduledFuture<?> beeperHandle =
55  *       scheduler.scheduleAtFixedRate(beeper, 10, 10, SECONDS);
56  *     scheduler.schedule(new Runnable() {
57  *       public void run() { beeperHandle.cancel(true); }
58  *     }, 60 * 60, SECONDS);
59  *   }
60  * }}</pre>
61  *
62  * @since 1.5
63  * @author Doug Lea
64  */
65 public interface ScheduledExecutorService extends ExecutorService {
66 
67     /**
68      * Creates and executes a one-shot action that becomes enabled
69      * after the given delay.
70      *
71      * @param command the task to execute
72      * @param delay the time from now to delay execution
73      * @param unit the time unit of the delay parameter
74      * @return a ScheduledFuture representing pending completion of
75      *         the task and whose {@code get()} method will return
76      *         {@code null} upon completion
77      * @throws RejectedExecutionException if the task cannot be
78      *         scheduled for execution
79      * @throws NullPointerException if command is null
80      */
schedule(Runnable command, long delay, TimeUnit unit)81     public ScheduledFuture<?> schedule(Runnable command,
82                                        long delay, TimeUnit unit);
83 
84     /**
85      * Creates and executes a ScheduledFuture that becomes enabled after the
86      * given delay.
87      *
88      * @param callable the function to execute
89      * @param delay the time from now to delay execution
90      * @param unit the time unit of the delay parameter
91      * @return a ScheduledFuture that can be used to extract result or cancel
92      * @throws RejectedExecutionException if the task cannot be
93      *         scheduled for execution
94      * @throws NullPointerException if callable is null
95      */
schedule(Callable<V> callable, long delay, TimeUnit unit)96     public <V> ScheduledFuture<V> schedule(Callable<V> callable,
97                                            long delay, TimeUnit unit);
98 
99     /**
100      * Creates and executes a periodic action that becomes enabled first
101      * after the given initial delay, and subsequently with the given
102      * period; that is executions will commence after
103      * {@code initialDelay} then {@code initialDelay+period}, then
104      * {@code initialDelay + 2 * period}, and so on.
105      * If any execution of the task
106      * encounters an exception, subsequent executions are suppressed.
107      * Otherwise, the task will only terminate via cancellation or
108      * termination of the executor.  If any execution of this task
109      * takes longer than its period, then subsequent executions
110      * may start late, but will not concurrently execute.
111      *
112      * @param command the task to execute
113      * @param initialDelay the time to delay first execution
114      * @param period the period between successive executions
115      * @param unit the time unit of the initialDelay and period parameters
116      * @return a ScheduledFuture representing pending completion of
117      *         the task, and whose {@code get()} method will throw an
118      *         exception upon cancellation
119      * @throws RejectedExecutionException if the task cannot be
120      *         scheduled for execution
121      * @throws NullPointerException if command is null
122      * @throws IllegalArgumentException if period less than or equal to zero
123      */
scheduleAtFixedRate(Runnable command, long initialDelay, long period, TimeUnit unit)124     public ScheduledFuture<?> scheduleAtFixedRate(Runnable command,
125                                                   long initialDelay,
126                                                   long period,
127                                                   TimeUnit unit);
128 
129     /**
130      * Creates and executes a periodic action that becomes enabled first
131      * after the given initial delay, and subsequently with the
132      * given delay between the termination of one execution and the
133      * commencement of the next.  If any execution of the task
134      * encounters an exception, subsequent executions are suppressed.
135      * Otherwise, the task will only terminate via cancellation or
136      * termination of the executor.
137      *
138      * @param command the task to execute
139      * @param initialDelay the time to delay first execution
140      * @param delay the delay between the termination of one
141      * execution and the commencement of the next
142      * @param unit the time unit of the initialDelay and delay parameters
143      * @return a ScheduledFuture representing pending completion of
144      *         the task, and whose {@code get()} method will throw an
145      *         exception upon cancellation
146      * @throws RejectedExecutionException if the task cannot be
147      *         scheduled for execution
148      * @throws NullPointerException if command is null
149      * @throws IllegalArgumentException if delay less than or equal to zero
150      */
scheduleWithFixedDelay(Runnable command, long initialDelay, long delay, TimeUnit unit)151     public ScheduledFuture<?> scheduleWithFixedDelay(Runnable command,
152                                                      long initialDelay,
153                                                      long delay,
154                                                      TimeUnit unit);
155 
156 }
157