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 * Runnable beeper = () -> System.out.println("beep"); 81 * ScheduledFuture<?> beeperHandle = 82 * scheduler.scheduleAtFixedRate(beeper, 10, 10, SECONDS); 83 * Runnable canceller = () -> beeperHandle.cancel(false); 84 * scheduler.schedule(canceller, 1, HOURS); 85 * } 86 * }}</pre> 87 * 88 * @since 1.5 89 * @author Doug Lea 90 */ 91 public interface ScheduledExecutorService extends ExecutorService { 92 93 /** 94 * Submits a one-shot task that becomes enabled after the given delay. 95 * 96 * @param command the task to execute 97 * @param delay the time from now to delay execution 98 * @param unit the time unit of the delay parameter 99 * @return a ScheduledFuture representing pending completion of 100 * the task and whose {@code get()} method will return 101 * {@code null} upon completion 102 * @throws RejectedExecutionException if the task cannot be 103 * scheduled for execution 104 * @throws NullPointerException if command or unit is null 105 */ schedule(Runnable command, long delay, TimeUnit unit)106 public ScheduledFuture<?> schedule(Runnable command, 107 long delay, TimeUnit unit); 108 109 /** 110 * Submits a value-returning one-shot task that becomes enabled 111 * after the given delay. 112 * 113 * @param callable the function to execute 114 * @param delay the time from now to delay execution 115 * @param unit the time unit of the delay parameter 116 * @param <V> the type of the callable's result 117 * @return a ScheduledFuture that can be used to extract result or cancel 118 * @throws RejectedExecutionException if the task cannot be 119 * scheduled for execution 120 * @throws NullPointerException if callable or unit is null 121 */ schedule(Callable<V> callable, long delay, TimeUnit unit)122 public <V> ScheduledFuture<V> schedule(Callable<V> callable, 123 long delay, TimeUnit unit); 124 125 /** 126 * Submits a periodic action that becomes enabled first after the 127 * given initial delay, and subsequently with the given period; 128 * that is, executions will commence after 129 * {@code initialDelay}, then {@code initialDelay + period}, then 130 * {@code initialDelay + 2 * period}, and so on. 131 * 132 * <p>The sequence of task executions continues indefinitely until 133 * one of the following exceptional completions occur: 134 * <ul> 135 * <li>The task is {@linkplain Future#cancel explicitly cancelled} 136 * via the returned future. 137 * <li>The executor terminates, also resulting in task cancellation. 138 * <li>An execution of the task throws an exception. In this case 139 * calling {@link Future#get() get} on the returned future will throw 140 * {@link ExecutionException}, holding the exception as its cause. 141 * </ul> 142 * Subsequent executions are suppressed. Subsequent calls to 143 * {@link Future#isDone isDone()} on the returned future will 144 * return {@code true}. 145 * 146 * <p>If any execution of this task takes longer than its period, then 147 * subsequent executions may start late, but will not concurrently 148 * execute. 149 * 150 * @param command the task to execute 151 * @param initialDelay the time to delay first execution 152 * @param period the period between successive executions 153 * @param unit the time unit of the initialDelay and period parameters 154 * @return a ScheduledFuture representing pending completion of 155 * the series of repeated tasks. The future's {@link 156 * Future#get() get()} method will never return normally, 157 * and will throw an exception upon task cancellation or 158 * abnormal termination of a task execution. 159 * @throws RejectedExecutionException if the task cannot be 160 * scheduled for execution 161 * @throws NullPointerException if command or unit is null 162 * @throws IllegalArgumentException if period less than or equal to zero 163 */ scheduleAtFixedRate(Runnable command, long initialDelay, long period, TimeUnit unit)164 public ScheduledFuture<?> scheduleAtFixedRate(Runnable command, 165 long initialDelay, 166 long period, 167 TimeUnit unit); 168 169 /** 170 * Submits a periodic action that becomes enabled first after the 171 * given initial delay, and subsequently with the given delay 172 * between the termination of one execution and the commencement of 173 * the next. 174 * 175 * <p>The sequence of task executions continues indefinitely until 176 * one of the following exceptional completions occur: 177 * <ul> 178 * <li>The task is {@linkplain Future#cancel explicitly cancelled} 179 * via the returned future. 180 * <li>The executor terminates, also resulting in task cancellation. 181 * <li>An execution of the task throws an exception. In this case 182 * calling {@link Future#get() get} on the returned future will throw 183 * {@link ExecutionException}, holding the exception as its cause. 184 * </ul> 185 * Subsequent executions are suppressed. Subsequent calls to 186 * {@link Future#isDone isDone()} on the returned future will 187 * return {@code true}. 188 * 189 * @param command the task to execute 190 * @param initialDelay the time to delay first execution 191 * @param delay the delay between the termination of one 192 * execution and the commencement of the next 193 * @param unit the time unit of the initialDelay and delay parameters 194 * @return a ScheduledFuture representing pending completion of 195 * the series of repeated tasks. The future's {@link 196 * Future#get() get()} method will never return normally, 197 * and will throw an exception upon task cancellation or 198 * abnormal termination of a task execution. 199 * @throws RejectedExecutionException if the task cannot be 200 * scheduled for execution 201 * @throws NullPointerException if command or unit is null 202 * @throws IllegalArgumentException if delay less than or equal to zero 203 */ scheduleWithFixedDelay(Runnable command, long initialDelay, long delay, TimeUnit unit)204 public ScheduledFuture<?> scheduleWithFixedDelay(Runnable command, 205 long initialDelay, 206 long delay, 207 TimeUnit unit); 208 209 } 210