ScheduledExecutorService


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