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
7package 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 */
65public 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     */
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     */
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     */
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     */
151    public ScheduledFuture<?> scheduleWithFixedDelay(Runnable command,
152                                                     long initialDelay,
153                                                     long delay,
154                                                     TimeUnit unit);
155
156}
157