1 /*
2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3  *
4  * This code is free software; you can redistribute it and/or modify it
5  * under the terms of the GNU General Public License version 2 only, as
6  * published by the Free Software Foundation.  Oracle designates this
7  * particular file as subject to the "Classpath" exception as provided
8  * by Oracle in the LICENSE file that accompanied this code.
9  *
10  * This code is distributed in the hope that it will be useful, but WITHOUT
11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
13  * version 2 for more details (a copy is included in the LICENSE file that
14  * accompanied this code).
15  *
16  * You should have received a copy of the GNU General Public License version
17  * 2 along with this work; if not, write to the Free Software Foundation,
18  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
19  *
20  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21  * or visit www.oracle.com if you need additional information or have any
22  * questions.
23  */
24 
25 /*
26  * This file is available under and governed by the GNU General Public
27  * License version 2 only, as published by the Free Software Foundation.
28  * However, the following notice accompanied the original version of this
29  * file:
30  *
31  * Written by Doug Lea with assistance from members of JCP JSR-166
32  * Expert Group and released to the public domain, as explained at
33  * http://creativecommons.org/publicdomain/zero/1.0/
34  */
35 
36 package java.util.concurrent;
37 
38 /**
39  * An {@link ExecutorService} that can schedule commands to run after a given
40  * delay, or to execute periodically.
41  *
42  * <p>The {@code schedule} methods create tasks with various delays
43  * and return a task object that can be used to cancel or check
44  * execution. The {@code scheduleAtFixedRate} and
45  * {@code scheduleWithFixedDelay} methods create and execute tasks
46  * that run periodically until cancelled.
47  *
48  * <p>Commands submitted using the {@link Executor#execute(Runnable)}
49  * and {@link ExecutorService} {@code submit} methods are scheduled
50  * with a requested delay of zero. Zero and negative delays (but not
51  * periods) are also allowed in {@code schedule} methods, and are
52  * treated as requests for immediate execution.
53  *
54  * <p>All {@code schedule} methods accept <em>relative</em> delays and
55  * periods as arguments, not absolute times or dates. It is a simple
56  * matter to transform an absolute time represented as a {@link
57  * java.util.Date} to the required form. For example, to schedule at
58  * a certain future {@code date}, you can use: {@code schedule(task,
59  * date.getTime() - System.currentTimeMillis(),
60  * TimeUnit.MILLISECONDS)}. Beware however that expiration of a
61  * relative delay need not coincide with the current {@code Date} at
62  * which the task is enabled due to network time synchronization
63  * protocols, clock drift, or other factors.
64  *
65  * <p>The {@link Executors} class provides convenient factory methods for
66  * the ScheduledExecutorService implementations provided in this package.
67  *
68  * <h3>Usage Example</h3>
69  *
70  * Here is a class with a method that sets up a ScheduledExecutorService
71  * to beep every ten seconds for an hour:
72  *
73  * <pre> {@code
74  * import static java.util.concurrent.TimeUnit.*;
75  * class BeeperControl {
76  *   private final ScheduledExecutorService scheduler =
77  *     Executors.newScheduledThreadPool(1);
78  *
79  *   public void beepForAnHour() {
80  *     final Runnable beeper = new Runnable() {
81  *       public void run() { System.out.println("beep"); }
82  *     };
83  *     final ScheduledFuture<?> beeperHandle =
84  *       scheduler.scheduleAtFixedRate(beeper, 10, 10, SECONDS);
85  *     scheduler.schedule(new Runnable() {
86  *       public void run() { beeperHandle.cancel(true); }
87  *     }, 60 * 60, SECONDS);
88  *   }
89  * }}</pre>
90  *
91  * @since 1.5
92  * @author Doug Lea
93  */
94 public interface ScheduledExecutorService extends ExecutorService {
95 
96     /**
97      * Creates and executes a one-shot action that becomes enabled
98      * after the given delay.
99      *
100      * @param command the task to execute
101      * @param delay the time from now to delay execution
102      * @param unit the time unit of the delay parameter
103      * @return a ScheduledFuture representing pending completion of
104      *         the task and whose {@code get()} method will return
105      *         {@code null} upon completion
106      * @throws RejectedExecutionException if the task cannot be
107      *         scheduled for execution
108      * @throws NullPointerException if command is null
109      */
schedule(Runnable command, long delay, TimeUnit unit)110     public ScheduledFuture<?> schedule(Runnable command,
111                                        long delay, TimeUnit unit);
112 
113     /**
114      * Creates and executes a ScheduledFuture that becomes enabled after the
115      * given delay.
116      *
117      * @param callable the function to execute
118      * @param delay the time from now to delay execution
119      * @param unit the time unit of the delay parameter
120      * @param <V> the type of the callable's result
121      * @return a ScheduledFuture that can be used to extract result or cancel
122      * @throws RejectedExecutionException if the task cannot be
123      *         scheduled for execution
124      * @throws NullPointerException if callable is null
125      */
schedule(Callable<V> callable, long delay, TimeUnit unit)126     public <V> ScheduledFuture<V> schedule(Callable<V> callable,
127                                            long delay, 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 given
132      * period; that is, executions will commence after
133      * {@code initialDelay}, then {@code initialDelay + period}, then
134      * {@code initialDelay + 2 * period}, and so on.
135      *
136      * <p>The sequence of task executions continues indefinitely until
137      * one of the following exceptional completions occur:
138      * <ul>
139      * <li>The task is {@linkplain Future#cancel explicitly cancelled}
140      * via the returned future.
141      * <li>The executor terminates, also resulting in task cancellation.
142      * <li>An execution of the task throws an exception.  In this case
143      * calling {@link Future#get() get} on the returned future will
144      * throw {@link ExecutionException}.
145      * </ul>
146      * Subsequent executions are suppressed.  Subsequent calls to
147      * {@link Future#isDone isDone()} on the returned future will
148      * return {@code true}.
149      *
150      * <p>If any execution of this task takes longer than its period, then
151      * subsequent executions may start late, but will not concurrently
152      * execute.
153      *
154      * @param command the task to execute
155      * @param initialDelay the time to delay first execution
156      * @param period the period between successive executions
157      * @param unit the time unit of the initialDelay and period parameters
158      * @return a ScheduledFuture representing pending completion of
159      *         the series of repeated tasks.  The future's {@link
160      *         Future#get() get()} method will never return normally,
161      *         and will throw an exception upon task cancellation or
162      *         abnormal termination of a task execution.
163      * @throws RejectedExecutionException if the task cannot be
164      *         scheduled for execution
165      * @throws NullPointerException if command is null
166      * @throws IllegalArgumentException if period less than or equal to zero
167      */
scheduleAtFixedRate(Runnable command, long initialDelay, long period, TimeUnit unit)168     public ScheduledFuture<?> scheduleAtFixedRate(Runnable command,
169                                                   long initialDelay,
170                                                   long period,
171                                                   TimeUnit unit);
172 
173     /**
174      * Creates and executes a periodic action that becomes enabled first
175      * after the given initial delay, and subsequently with the
176      * given delay between the termination of one execution and the
177      * commencement of the next.
178      *
179      * <p>The sequence of task executions continues indefinitely until
180      * one of the following exceptional completions occur:
181      * <ul>
182      * <li>The task is {@linkplain Future#cancel explicitly cancelled}
183      * via the returned future.
184      * <li>The executor terminates, also resulting in task cancellation.
185      * <li>An execution of the task throws an exception.  In this case
186      * calling {@link Future#get() get} on the returned future will
187      * throw {@link ExecutionException}.
188      * </ul>
189      * Subsequent executions are suppressed.  Subsequent calls to
190      * {@link Future#isDone isDone()} on the returned future will
191      * return {@code true}.
192      *
193      * @param command the task to execute
194      * @param initialDelay the time to delay first execution
195      * @param delay the delay between the termination of one
196      * execution and the commencement of the next
197      * @param unit the time unit of the initialDelay and delay parameters
198      * @return a ScheduledFuture representing pending completion of
199      *         the series of repeated tasks.  The future's {@link
200      *         Future#get() get()} method will never return normally,
201      *         and will throw an exception upon task cancellation or
202      *         abnormal termination of a task execution.
203      * @throws RejectedExecutionException if the task cannot be
204      *         scheduled for execution
205      * @throws NullPointerException if command is null
206      * @throws IllegalArgumentException if delay less than or equal to zero
207      */
scheduleWithFixedDelay(Runnable command, long initialDelay, long delay, TimeUnit unit)208     public ScheduledFuture<?> scheduleWithFixedDelay(Runnable command,
209                                                      long initialDelay,
210                                                      long delay,
211                                                      TimeUnit unit);
212 
213 }
214