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