001 /*
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
003 *
004 * This code is free software; you can redistribute it and/or modify it
005 * under the terms of the GNU General Public License version 2 only, as
006 * published by the Free Software Foundation. Sun designates this
007 * particular file as subject to the "Classpath" exception as provided
008 * by Sun in the LICENSE file that accompanied this code.
009 *
010 * This code is distributed in the hope that it will be useful, but WITHOUT
011 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
012 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
013 * version 2 for more details (a copy is included in the LICENSE file that
014 * accompanied this code).
015 *
016 * You should have received a copy of the GNU General Public License version
017 * 2 along with this work; if not, write to the Free Software Foundation,
018 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
019 *
020 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
021 * CA 95054 USA or visit www.sun.com if you need additional information or
022 * have any questions.
023 */
024
025 /*
026 * This file is available under and governed by the GNU General Public
027 * License version 2 only, as published by the Free Software Foundation.
028 * However, the following notice accompanied the original version of this
029 * file:
030 *
031 * Written by Doug Lea with assistance from members of JCP JSR-166
032 * Expert Group and released to the public domain, as explained at
033 * http://creativecommons.org/licenses/publicdomain
034 */
035
036 package java.util.concurrent;
037
038 import java.util.concurrent.atomic.*;
039 import java.util.*;
040
041 /**
042 * An {@link ExecutorService} that can schedule commands to run after a given
043 * delay, or to execute periodically.
044 *
045 * <p> The <tt>schedule</tt> methods create tasks with various delays
046 * and return a task object that can be used to cancel or check
047 * execution. The <tt>scheduleAtFixedRate</tt> and
048 * <tt>scheduleWithFixedDelay</tt> methods create and execute tasks
049 * that run periodically until cancelled.
050 *
051 * <p> Commands submitted using the {@link Executor#execute} and
052 * {@link ExecutorService} <tt>submit</tt> methods are scheduled with
053 * a requested delay of zero. Zero and negative delays (but not
054 * periods) are also allowed in <tt>schedule</tt> methods, and are
055 * treated as requests for immediate execution.
056 *
057 * <p>All <tt>schedule</tt> methods accept <em>relative</em> delays and
058 * periods as arguments, not absolute times or dates. It is a simple
059 * matter to transform an absolute time represented as a {@link
060 * java.util.Date} to the required form. For example, to schedule at
061 * a certain future <tt>date</tt>, you can use: <tt>schedule(task,
062 * date.getTime() - System.currentTimeMillis(),
063 * TimeUnit.MILLISECONDS)</tt>. Beware however that expiration of a
064 * relative delay need not coincide with the current <tt>Date</tt> at
065 * which the task is enabled due to network time synchronization
066 * protocols, clock drift, or other factors.
067 *
068 * The {@link Executors} class provides convenient factory methods for
069 * the ScheduledExecutorService implementations provided in this package.
070 *
071 * <h3>Usage Example</h3>
072 *
073 * Here is a class with a method that sets up a ScheduledExecutorService
074 * to beep every ten seconds for an hour:
075 *
076 * <pre>
077 * import static java.util.concurrent.TimeUnit.*;
078 * class BeeperControl {
079 * private final ScheduledExecutorService scheduler =
080 * Executors.newScheduledThreadPool(1);
081 *
082 * public void beepForAnHour() {
083 * final Runnable beeper = new Runnable() {
084 * public void run() { System.out.println("beep"); }
085 * };
086 * final ScheduledFuture<?> beeperHandle =
087 * scheduler.scheduleAtFixedRate(beeper, 10, 10, SECONDS);
088 * scheduler.schedule(new Runnable() {
089 * public void run() { beeperHandle.cancel(true); }
090 * }, 60 * 60, SECONDS);
091 * }
092 * }
093 * </pre>
094 *
095 * @since 1.5
096 * @author Doug Lea
097 */
098 public interface ScheduledExecutorService extends ExecutorService {
099
100 /**
101 * Creates and executes a one-shot action that becomes enabled
102 * after the given delay.
103 *
104 * @param command the task to execute
105 * @param delay the time from now to delay execution
106 * @param unit the time unit of the delay parameter
107 * @return a ScheduledFuture representing pending completion of
108 * the task and whose <tt>get()</tt> method will return
109 * <tt>null</tt> upon completion
110 * @throws RejectedExecutionException if the task cannot be
111 * scheduled for execution
112 * @throws NullPointerException if command is null
113 */
114 public ScheduledFuture<?> schedule(Runnable command, long delay,
115 TimeUnit unit);
116
117 /**
118 * Creates and executes a ScheduledFuture that becomes enabled after the
119 * given delay.
120 *
121 * @param callable the function to execute
122 * @param delay the time from now to delay execution
123 * @param unit the time unit of the delay parameter
124 * @return a ScheduledFuture that can be used to extract result or cancel
125 * @throws RejectedExecutionException if the task cannot be
126 * scheduled for execution
127 * @throws NullPointerException if callable is null
128 */
129 public <V> ScheduledFuture<V> schedule(Callable<V> callable,
130 long delay, 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 given
135 * period; that is executions will commence after
136 * <tt>initialDelay</tt> then <tt>initialDelay+period</tt>, then
137 * <tt>initialDelay + 2 * period</tt>, and so on.
138 * If any execution of the task
139 * encounters an exception, subsequent executions are suppressed.
140 * Otherwise, the task will only terminate via cancellation or
141 * termination of the executor. If any execution of this task
142 * takes longer than its period, then subsequent executions
143 * may start late, but will not concurrently execute.
144 *
145 * @param command the task to execute
146 * @param initialDelay the time to delay first execution
147 * @param period the period between successive executions
148 * @param unit the time unit of the initialDelay and period parameters
149 * @return a ScheduledFuture representing pending completion of
150 * the task, and whose <tt>get()</tt> method will throw an
151 * exception upon cancellation
152 * @throws RejectedExecutionException if the task cannot be
153 * scheduled for execution
154 * @throws NullPointerException if command is null
155 * @throws IllegalArgumentException if period less than or equal to zero
156 */
157 public ScheduledFuture<?> scheduleAtFixedRate(Runnable command,
158 long initialDelay, long period, 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, long delay, TimeUnit unit);
184
185 }
|