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