/* * Written by Doug Lea with assistance from members of JCP JSR-166 * Expert Group and released to the public domain, as explained at * http://creativecommons.org/licenses/publicdomain */ package java.util.concurrent; import java.util.concurrent.atomic.*; import java.util.*; /** * An {@link ExecutorService} that can schedule commands to run after a given * delay, or to execute periodically. * *

The schedule methods create tasks with various delays * and return a task object that can be used to cancel or check * execution. The scheduleAtFixedRate and * scheduleWithFixedDelay methods create and execute tasks * that run periodically until cancelled. * *

Commands submitted using the {@link Executor#execute} and * {@link ExecutorService} submit methods are scheduled with * a requested delay of zero. Zero and negative delays (but not * periods) are also allowed in schedule methods, and are * treated as requests for immediate execution. * *

All schedule methods accept relative delays and * periods as arguments, not absolute times or dates. It is a simple * matter to transform an absolute time represented as a {@link * java.util.Date} to the required form. For example, to schedule at * a certain future date, you can use: schedule(task, * date.getTime() - System.currentTimeMillis(), * TimeUnit.MILLISECONDS). Beware however that expiration of a * relative delay need not coincide with the current Date at * which the task is enabled due to network time synchronization * protocols, clock drift, or other factors. * * The {@link Executors} class provides convenient factory methods for * the ScheduledExecutorService implementations provided in this package. * *

Usage Example

* * Here is a class with a method that sets up a ScheduledExecutorService * to beep every ten seconds for an hour: * * 
 {@code
 * import static java.util.concurrent.TimeUnit.*;
 * class BeeperControl {
 *   private final ScheduledExecutorService scheduler =
 *     Executors.newScheduledThreadPool(1);
 *
 *   public void beepForAnHour() {
 *     final Runnable beeper = new Runnable() {
 *       public void run() { System.out.println("beep"); }
 *     };
 *     final ScheduledFuture beeperHandle =
 *       scheduler.scheduleAtFixedRate(beeper, 10, 10, SECONDS);
 *     scheduler.schedule(new Runnable() {
 *       public void run() { beeperHandle.cancel(true); }
 *     }, 60 * 60, SECONDS);
 *   }
 * }}
* * @since 1.5 * @author Doug Lea */ public interface ScheduledExecutorService extends ExecutorService { /** * Creates and executes a one-shot action that becomes enabled * after the given delay. * * @param command the task to execute * @param delay the time from now to delay execution * @param unit the time unit of the delay parameter * @return a ScheduledFuture representing pending completion of * the task and whose get() method will return * null upon completion * @throws RejectedExecutionException if the task cannot be * scheduled for execution * @throws NullPointerException if command is null */ public ScheduledFuture schedule(Runnable command, long delay, TimeUnit unit); /** * Creates and executes a ScheduledFuture that becomes enabled after the * given delay. * * @param callable the function to execute * @param delay the time from now to delay execution * @param unit the time unit of the delay parameter * @return a ScheduledFuture that can be used to extract result or cancel * @throws RejectedExecutionException if the task cannot be * scheduled for execution * @throws NullPointerException if callable is null */ public ScheduledFuture schedule(Callable callable, long delay, TimeUnit unit); /** * Creates and executes a periodic action that becomes enabled first * after the given initial delay, and subsequently with the given * period; that is executions will commence after * initialDelay then initialDelay+period, then * initialDelay + 2 * period, and so on. * If any execution of the task * encounters an exception, subsequent executions are suppressed. * Otherwise, the task will only terminate via cancellation or * termination of the executor. If any execution of this task * takes longer than its period, then subsequent executions * may start late, but will not concurrently execute. * * @param command the task to execute * @param initialDelay the time to delay first execution * @param period the period between successive executions * @param unit the time unit of the initialDelay and period parameters * @return a ScheduledFuture representing pending completion of * the task, and whose get() method will throw an * exception upon cancellation * @throws RejectedExecutionException if the task cannot be * scheduled for execution * @throws NullPointerException if command is null * @throws IllegalArgumentException if period less than or equal to zero */ public ScheduledFuture scheduleAtFixedRate(Runnable command, long initialDelay, long period, TimeUnit unit); /** * Creates and executes a periodic action that becomes enabled first * after the given initial delay, and subsequently with the * given delay between the termination of one execution and the * commencement of the next. If any execution of the task * encounters an exception, subsequent executions are suppressed. * Otherwise, the task will only terminate via cancellation or * termination of the executor. * * @param command the task to execute * @param initialDelay the time to delay first execution * @param delay the delay between the termination of one * execution and the commencement of the next * @param unit the time unit of the initialDelay and delay parameters * @return a ScheduledFuture representing pending completion of * the task, and whose get() method will throw an * exception upon cancellation * @throws RejectedExecutionException if the task cannot be * scheduled for execution * @throws NullPointerException if command is null * @throws IllegalArgumentException if delay less than or equal to zero */ public ScheduledFuture scheduleWithFixedDelay(Runnable command, long initialDelay, long delay, TimeUnit unit); }