001: /*
002: * Written by Doug Lea with assistance from members of JCP JSR-166
003: * Expert Group and released to the public domain, as explained at
004: * http://creativecommons.org/licenses/publicdomain
005: */
006:
007: package java.util.concurrent;
008:
009: import java.util.concurrent.atomic.*;
010: import java.util.*;
011:
012: /**
013: * An {@link ExecutorService} that can schedule commands to run after a given
014: * delay, or to execute periodically.
015: *
016: * <p> The <tt>schedule</tt> methods create tasks with various delays
017: * and return a task object that can be used to cancel or check
018: * execution. The <tt>scheduleAtFixedRate</tt> and
019: * <tt>scheduleWithFixedDelay</tt> methods create and execute tasks
020: * that run periodically until cancelled.
021: *
022: * <p> Commands submitted using the {@link Executor#execute} and
023: * {@link ExecutorService} <tt>submit</tt> methods are scheduled with
024: * a requested delay of zero. Zero and negative delays (but not
025: * periods) are also allowed in <tt>schedule</tt> methods, and are
026: * treated as requests for immediate execution.
027: *
028: * <p>All <tt>schedule</tt> methods accept <em>relative</em> delays and
029: * periods as arguments, not absolute times or dates. It is a simple
030: * matter to transform an absolute time represented as a {@link
031: * java.util.Date} to the required form. For example, to schedule at
032: * a certain future <tt>date</tt>, you can use: <tt>schedule(task,
033: * date.getTime() - System.currentTimeMillis(),
034: * TimeUnit.MILLISECONDS)</tt>. Beware however that expiration of a
035: * relative delay need not coincide with the current <tt>Date</tt> at
036: * which the task is enabled due to network time synchronization
037: * protocols, clock drift, or other factors.
038: *
039: * The {@link Executors} class provides convenient factory methods for
040: * the ScheduledExecutorService implementations provided in this package.
041: *
042: * <h3>Usage Example</h3>
043: *
044: * Here is a class with a method that sets up a ScheduledExecutorService
045: * to beep every ten seconds for an hour:
046: *
047: * <pre>
048: * import static java.util.concurrent.TimeUnit;
049: * class BeeperControl {
050: * private final ScheduledExecutorService scheduler =
051: * Executors.newScheduledThreadPool(1);
052: *
053: * public void beepForAnHour() {
054: * final Runnable beeper = new Runnable() {
055: * public void run() { System.out.println("beep"); }
056: * };
057: * final ScheduledFuture<?> beeperHandle =
058: * scheduler.scheduleAtFixedRate(beeper, 10, 10, SECONDS);
059: * scheduler.schedule(new Runnable() {
060: * public void run() { beeperHandle.cancel(true); }
061: * }, 60 * 60, SECONDS);
062: * }
063: * }
064: * </pre>
065: *
066: * @since 1.5
067: * @author Doug Lea
068: */
069: public interface ScheduledExecutorService extends ExecutorService {
070:
071: /**
072: * Creates and executes a one-shot action that becomes enabled
073: * after the given delay.
074: * @param command the task to execute.
075: * @param delay the time from now to delay execution.
076: * @param unit the time unit of the delay parameter.
077: * @return a Future representing pending completion of the task,
078: * and whose <tt>get()</tt> method will return <tt>null</tt>
079: * upon completion.
080: * @throws RejectedExecutionException if task cannot be scheduled
081: * for execution.
082: * @throws NullPointerException if command is null
083: */
084: public ScheduledFuture<?> schedule(Runnable command, long delay,
085: TimeUnit unit);
086:
087: /**
088: * Creates and executes a ScheduledFuture that becomes enabled after the
089: * given delay.
090: * @param callable the function to execute.
091: * @param delay the time from now to delay execution.
092: * @param unit the time unit of the delay parameter.
093: * @return a ScheduledFuture that can be used to extract result or cancel.
094: * @throws RejectedExecutionException if task cannot be scheduled
095: * for execution.
096: * @throws NullPointerException if callable is null
097: */
098: public <V> ScheduledFuture<V> schedule(Callable<V> callable,
099: long delay, TimeUnit unit);
100:
101: /**
102: * Creates and executes a periodic action that becomes enabled first
103: * after the given initial delay, and subsequently with the given
104: * period; that is executions will commence after
105: * <tt>initialDelay</tt> then <tt>initialDelay+period</tt>, then
106: * <tt>initialDelay + 2 * period</tt>, and so on.
107: * If any execution of the task
108: * encounters an exception, subsequent executions are suppressed.
109: * Otherwise, the task will only terminate via cancellation or
110: * termination of the executor.
111: * @param command the task to execute.
112: * @param initialDelay the time to delay first execution.
113: * @param period the period between successive executions.
114: * @param unit the time unit of the initialDelay and period parameters
115: * @return a Future representing pending completion of the task,
116: * and whose <tt>get()</tt> method will throw an exception upon
117: * cancellation.
118: * @throws RejectedExecutionException if task cannot be scheduled
119: * for execution.
120: * @throws NullPointerException if command is null
121: * @throws IllegalArgumentException if period less than or equal to zero.
122: */
123: public ScheduledFuture<?> scheduleAtFixedRate(Runnable command,
124: long initialDelay, long period, TimeUnit unit);
125:
126: /**
127: * Creates and executes a periodic action that becomes enabled first
128: * after the given initial delay, and subsequently with the
129: * given delay between the termination of one execution and the
130: * commencement of the next. If any execution of the task
131: * encounters an exception, subsequent executions are suppressed.
132: * Otherwise, the task will only terminate via cancellation or
133: * termination of the executor.
134: * @param command the task to execute.
135: * @param initialDelay the time to delay first execution.
136: * @param delay the delay between the termination of one
137: * execution and the commencement of the next.
138: * @param unit the time unit of the initialDelay and delay parameters
139: * @return a Future representing pending completion of the task,
140: * and whose <tt>get()</tt> method will throw an exception upon
141: * cancellation.
142: * @throws RejectedExecutionException if task cannot be scheduled
143: * for execution.
144: * @throws NullPointerException if command is null
145: * @throws IllegalArgumentException if delay less than or equal to zero.
146: */
147: public ScheduledFuture<?> scheduleWithFixedDelay(Runnable command,
148: long initialDelay, long delay, TimeUnit unit);
149:
150: }
|