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(Runnable)} 20 * and {@link ExecutorService} {@code submit} methods are scheduled 21 * with 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 * <p>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 * @param <V> the type of the callable's result 92 * @return a ScheduledFuture that can be used to extract result or cancel 93 * @throws RejectedExecutionException if the task cannot be 94 * scheduled for execution 95 * @throws NullPointerException if callable is null 96 */ schedule(Callable<V> callable, long delay, TimeUnit unit)97 public <V> ScheduledFuture<V> schedule(Callable<V> callable, 98 long delay, TimeUnit unit); 99 100 /** 101 * Creates and executes a periodic action that becomes enabled first 102 * after the given initial delay, and subsequently with the given 103 * period; that is, executions will commence after 104 * {@code initialDelay}, then {@code initialDelay + period}, then 105 * {@code initialDelay + 2 * period}, and so on. 106 * 107 * <p>The sequence of task executions continues indefinitely until 108 * one of the following exceptional completions occur: 109 * <ul> 110 * <li>The task is {@linkplain Future#cancel explicitly cancelled} 111 * via the returned future. 112 * <li>The executor terminates, also resulting in task cancellation. 113 * <li>An execution of the task throws an exception. In this case 114 * calling {@link Future#get() get} on the returned future will 115 * throw {@link ExecutionException}. 116 * </ul> 117 * Subsequent executions are suppressed. Subsequent calls to 118 * {@link Future#isDone isDone()} on the returned future will 119 * return {@code true}. 120 * 121 * <p>If any execution of this task takes longer than its period, then 122 * subsequent executions may start late, but will not concurrently 123 * execute. 124 * 125 * @param command the task to execute 126 * @param initialDelay the time to delay first execution 127 * @param period the period between successive executions 128 * @param unit the time unit of the initialDelay and period parameters 129 * @return a ScheduledFuture representing pending completion of 130 * the series of repeated tasks. The future's {@link 131 * Future#get() get()} method will never return normally, 132 * and will throw an exception upon task cancellation or 133 * abnormal termination of a task execution. 134 * @throws RejectedExecutionException if the task cannot be 135 * scheduled for execution 136 * @throws NullPointerException if command is null 137 * @throws IllegalArgumentException if period less than or equal to zero 138 */ scheduleAtFixedRate(Runnable command, long initialDelay, long period, TimeUnit unit)139 public ScheduledFuture<?> scheduleAtFixedRate(Runnable command, 140 long initialDelay, 141 long period, 142 TimeUnit unit); 143 144 /** 145 * Creates and executes a periodic action that becomes enabled first 146 * after the given initial delay, and subsequently with the 147 * given delay between the termination of one execution and the 148 * commencement of the next. 149 * 150 * <p>The sequence of task executions continues indefinitely until 151 * one of the following exceptional completions occur: 152 * <ul> 153 * <li>The task is {@linkplain Future#cancel explicitly cancelled} 154 * via the returned future. 155 * <li>The executor terminates, also resulting in task cancellation. 156 * <li>An execution of the task throws an exception. In this case 157 * calling {@link Future#get() get} on the returned future will 158 * throw {@link ExecutionException}. 159 * </ul> 160 * Subsequent executions are suppressed. Subsequent calls to 161 * {@link Future#isDone isDone()} on the returned future will 162 * return {@code true}. 163 * 164 * @param command the task to execute 165 * @param initialDelay the time to delay first execution 166 * @param delay the delay between the termination of one 167 * execution and the commencement of the next 168 * @param unit the time unit of the initialDelay and delay parameters 169 * @return a ScheduledFuture representing pending completion of 170 * the series of repeated tasks. The future's {@link 171 * Future#get() get()} method will never return normally, 172 * and will throw an exception upon task cancellation or 173 * abnormal termination of a task execution. 174 * @throws RejectedExecutionException if the task cannot be 175 * scheduled for execution 176 * @throws NullPointerException if command is null 177 * @throws IllegalArgumentException if delay less than or equal to zero 178 */ scheduleWithFixedDelay(Runnable command, long initialDelay, long delay, TimeUnit unit)179 public ScheduledFuture<?> scheduleWithFixedDelay(Runnable command, 180 long initialDelay, 181 long delay, 182 TimeUnit unit); 183 184 } 185