jaroslav@1890: /* jaroslav@1890: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. jaroslav@1890: * jaroslav@1890: * This code is free software; you can redistribute it and/or modify it jaroslav@1890: * under the terms of the GNU General Public License version 2 only, as jaroslav@1890: * published by the Free Software Foundation. Oracle designates this jaroslav@1890: * particular file as subject to the "Classpath" exception as provided jaroslav@1890: * by Oracle in the LICENSE file that accompanied this code. jaroslav@1890: * jaroslav@1890: * This code is distributed in the hope that it will be useful, but WITHOUT jaroslav@1890: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or jaroslav@1890: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License jaroslav@1890: * version 2 for more details (a copy is included in the LICENSE file that jaroslav@1890: * accompanied this code). jaroslav@1890: * jaroslav@1890: * You should have received a copy of the GNU General Public License version jaroslav@1890: * 2 along with this work; if not, write to the Free Software Foundation, jaroslav@1890: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. jaroslav@1890: * jaroslav@1890: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA jaroslav@1890: * or visit www.oracle.com if you need additional information or have any jaroslav@1890: * questions. jaroslav@1890: */ jaroslav@1890: jaroslav@1890: /* jaroslav@1890: * This file is available under and governed by the GNU General Public jaroslav@1890: * License version 2 only, as published by the Free Software Foundation. jaroslav@1890: * However, the following notice accompanied the original version of this jaroslav@1890: * file: jaroslav@1890: * jaroslav@1890: * Written by Doug Lea with assistance from members of JCP JSR-166 jaroslav@1890: * Expert Group and released to the public domain, as explained at jaroslav@1890: * http://creativecommons.org/publicdomain/zero/1.0/ jaroslav@1890: */ jaroslav@1890: jaroslav@1890: package java.util.concurrent; jaroslav@1890: import java.util.concurrent.atomic.*; jaroslav@1890: import java.util.*; jaroslav@1890: jaroslav@1890: /** jaroslav@1890: * An {@link ExecutorService} that can schedule commands to run after a given jaroslav@1890: * delay, or to execute periodically. jaroslav@1890: * jaroslav@1890: *

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

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

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

Usage Example

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