001    package org.bukkit.scheduler;
002    
003    import org.bukkit.plugin.Plugin;
004    import java.util.concurrent.Callable;
005    import java.util.concurrent.Future;
006    import java.util.List;
007    
008    public interface BukkitScheduler {
009    
010        /**
011         * Schedules a once off task to occur after a delay.
012         * <p>
013         * This task will be executed by the main server thread.
014         *
015         * @param plugin Plugin that owns the task
016         * @param task Task to be executed
017         * @param delay Delay in server ticks before executing task
018         * @return Task id number (-1 if scheduling failed)
019         */
020        public int scheduleSyncDelayedTask(Plugin plugin, Runnable task, long delay);
021    
022        /**
023         * @deprecated Use {@link BukkitRunnable#runTaskLater(Plugin, long)}
024         */
025        @Deprecated
026        public int scheduleSyncDelayedTask(Plugin plugin, BukkitRunnable task, long delay);
027    
028        /**
029         * Schedules a once off task to occur as soon as possible.
030         * <p>
031         * This task will be executed by the main server thread.
032         *
033         * @param plugin Plugin that owns the task
034         * @param task Task to be executed
035         * @return Task id number (-1 if scheduling failed)
036         */
037        public int scheduleSyncDelayedTask(Plugin plugin, Runnable task);
038    
039        /**
040         * @deprecated Use {@link BukkitRunnable#runTask(Plugin)}
041         */
042        @Deprecated
043        public int scheduleSyncDelayedTask(Plugin plugin, BukkitRunnable task);
044    
045        /**
046         * Schedules a repeating task.
047         * <p>
048         * This task will be executed by the main server thread.
049         *
050         * @param plugin Plugin that owns the task
051         * @param task Task to be executed
052         * @param delay Delay in server ticks before executing first repeat
053         * @param period Period in server ticks of the task
054         * @return Task id number (-1 if scheduling failed)
055         */
056        public int scheduleSyncRepeatingTask(Plugin plugin, Runnable task, long delay, long period);
057    
058        /**
059         * @deprecated Use {@link BukkitRunnable#runTaskTimer(Plugin, long, long)}
060         */
061        @Deprecated
062        public int scheduleSyncRepeatingTask(Plugin plugin, BukkitRunnable task, long delay, long period);
063    
064        /**
065         * <b>Asynchronous tasks should never access any API in Bukkit. Great care
066         * should be taken to assure the thread-safety of asynchronous tasks.</b>
067         * <p>
068         * Schedules a once off task to occur after a delay. This task will be
069         * executed by a thread managed by the scheduler.
070         *
071         * @param plugin Plugin that owns the task
072         * @param task Task to be executed
073         * @param delay Delay in server ticks before executing task
074         * @return Task id number (-1 if scheduling failed)
075         * @deprecated This name is misleading, as it does not schedule "a sync"
076         *     task, but rather, "an async" task
077         */
078        @Deprecated
079        public int scheduleAsyncDelayedTask(Plugin plugin, Runnable task, long delay);
080    
081        /**
082         * <b>Asynchronous tasks should never access any API in Bukkit. Great care
083         * should be taken to assure the thread-safety of asynchronous tasks.</b>
084         * <p>
085         * Schedules a once off task to occur as soon as possible. This task will
086         * be executed by a thread managed by the scheduler.
087         *
088         * @param plugin Plugin that owns the task
089         * @param task Task to be executed
090         * @return Task id number (-1 if scheduling failed)
091         * @deprecated This name is misleading, as it does not schedule "a sync"
092         *     task, but rather, "an async" task
093         */
094        @Deprecated
095        public int scheduleAsyncDelayedTask(Plugin plugin, Runnable task);
096    
097        /**
098         * <b>Asynchronous tasks should never access any API in Bukkit. Great care
099         * should be taken to assure the thread-safety of asynchronous tasks.</b>
100         * <p>
101         * Schedules a repeating task. This task will be executed by a thread
102         * managed by the scheduler.
103         *
104         * @param plugin Plugin that owns the task
105         * @param task Task to be executed
106         * @param delay Delay in server ticks before executing first repeat
107         * @param period Period in server ticks of the task
108         * @return Task id number (-1 if scheduling failed)
109         * @deprecated This name is misleading, as it does not schedule "a sync"
110         *     task, but rather, "an async" task
111         */
112        @Deprecated
113        public int scheduleAsyncRepeatingTask(Plugin plugin, Runnable task, long delay, long period);
114    
115        /**
116         * Calls a method on the main thread and returns a Future object. This
117         * task will be executed by the main server thread.
118         * <ul>
119         * <li>Note: The Future.get() methods must NOT be called from the main
120         *     thread.
121         * <li>Note2: There is at least an average of 10ms latency until the
122         *     isDone() method returns true.
123         * </ul>
124         * @param <T> The callable's return type
125         * @param plugin Plugin that owns the task
126         * @param task Task to be executed
127         * @return Future Future object related to the task
128         */
129        public <T> Future<T> callSyncMethod(Plugin plugin, Callable<T> task);
130    
131        /**
132         * Removes task from scheduler.
133         *
134         * @param taskId Id number of task to be removed
135         */
136        public void cancelTask(int taskId);
137    
138        /**
139         * Removes all tasks associated with a particular plugin from the
140         * scheduler.
141         *
142         * @param plugin Owner of tasks to be removed
143         */
144        public void cancelTasks(Plugin plugin);
145    
146        /**
147         * Removes all tasks from the scheduler.
148         */
149        public void cancelAllTasks();
150    
151        /**
152         * Check if the task currently running.
153         * <p>
154         * A repeating task might not be running currently, but will be running in
155         * the future. A task that has finished, and does not repeat, will not be
156         * running ever again.
157         * <p>
158         * Explicitly, a task is running if there exists a thread for it, and that
159         * thread is alive.
160         *
161         * @param taskId The task to check.
162         * <p>
163         * @return If the task is currently running.
164         */
165        public boolean isCurrentlyRunning(int taskId);
166    
167        /**
168         * Check if the task queued to be run later.
169         * <p>
170         * If a repeating task is currently running, it might not be queued now
171         * but could be in the future. A task that is not queued, and not running,
172         * will not be queued again.
173         *
174         * @param taskId The task to check.
175         * <p>
176         * @return If the task is queued to be run.
177         */
178        public boolean isQueued(int taskId);
179    
180        /**
181         * Returns a list of all active workers.
182         * <p>
183         * This list contains asynch tasks that are being executed by separate
184         * threads.
185         *
186         * @return Active workers
187         */
188        public List<BukkitWorker> getActiveWorkers();
189    
190        /**
191         * Returns a list of all pending tasks. The ordering of the tasks is not
192         * related to their order of execution.
193         *
194         * @return Active workers
195         */
196        public List<BukkitTask> getPendingTasks();
197    
198        /**
199         * Returns a task that will run on the next server tick.
200         *
201         * @param plugin the reference to the plugin scheduling task
202         * @param task the task to be run
203         * @return a BukkitTask that contains the id number
204         * @throws IllegalArgumentException if plugin is null
205         * @throws IllegalArgumentException if task is null
206         */
207        public BukkitTask runTask(Plugin plugin, Runnable task) throws IllegalArgumentException;
208    
209        /**
210         * @deprecated Use {@link BukkitRunnable#runTask(Plugin)}
211         */
212        @Deprecated
213        public BukkitTask runTask(Plugin plugin, BukkitRunnable task) throws IllegalArgumentException;
214    
215        /**
216         * <b>Asynchronous tasks should never access any API in Bukkit. Great care
217         * should be taken to assure the thread-safety of asynchronous tasks.</b>
218         * <p>
219         * Returns a task that will run asynchronously.
220         *
221         * @param plugin the reference to the plugin scheduling task
222         * @param task the task to be run
223         * @return a BukkitTask that contains the id number
224         * @throws IllegalArgumentException if plugin is null
225         * @throws IllegalArgumentException if task is null
226         */
227        public BukkitTask runTaskAsynchronously(Plugin plugin, Runnable task) throws IllegalArgumentException;
228    
229        /**
230         * @deprecated Use {@link BukkitRunnable#runTaskAsynchronously(Plugin)}
231         */
232        @Deprecated
233        public BukkitTask runTaskAsynchronously(Plugin plugin, BukkitRunnable task) throws IllegalArgumentException;
234    
235        /**
236         * Returns a task that will run after the specified number of server
237         * ticks.
238         *
239         * @param plugin the reference to the plugin scheduling task
240         * @param task the task to be run
241         * @param delay the ticks to wait before running the task
242         * @return a BukkitTask that contains the id number
243         * @throws IllegalArgumentException if plugin is null
244         * @throws IllegalArgumentException if task is null
245         */
246        public BukkitTask runTaskLater(Plugin plugin, Runnable task, long delay) throws IllegalArgumentException;
247    
248        /**
249         * @deprecated Use {@link BukkitRunnable#runTaskLater(Plugin, long)}
250         */
251        @Deprecated
252        public BukkitTask runTaskLater(Plugin plugin, BukkitRunnable task, long delay) throws IllegalArgumentException;
253    
254        /**
255         * <b>Asynchronous tasks should never access any API in Bukkit. Great care
256         * should be taken to assure the thread-safety of asynchronous tasks.</b>
257         * <p>
258         * Returns a task that will run asynchronously after the specified number
259         * of server ticks.
260         *
261         * @param plugin the reference to the plugin scheduling task
262         * @param task the task to be run
263         * @param delay the ticks to wait before running the task
264         * @return a BukkitTask that contains the id number
265         * @throws IllegalArgumentException if plugin is null
266         * @throws IllegalArgumentException if task is null
267         */
268        public BukkitTask runTaskLaterAsynchronously(Plugin plugin, Runnable task, long delay) throws IllegalArgumentException;
269    
270        /**
271         * @deprecated Use {@link BukkitRunnable#runTaskLaterAsynchronously(Plugin, long)}
272         */
273        @Deprecated
274        public BukkitTask runTaskLaterAsynchronously(Plugin plugin, BukkitRunnable task, long delay) throws IllegalArgumentException;
275    
276        /**
277         * Returns a task that will repeatedly run until cancelled, starting after
278         * the specified number of server ticks.
279         *
280         * @param plugin the reference to the plugin scheduling task
281         * @param task the task to be run
282         * @param delay the ticks to wait before running the task
283         * @param period the ticks to wait between runs
284         * @return a BukkitTask that contains the id number
285         * @throws IllegalArgumentException if plugin is null
286         * @throws IllegalArgumentException if task is null
287         */
288        public BukkitTask runTaskTimer(Plugin plugin, Runnable task, long delay, long period) throws IllegalArgumentException;
289    
290        /**
291         * @deprecated Use {@link BukkitRunnable#runTaskTimer(Plugin, long, long)}
292         */
293        @Deprecated
294        public BukkitTask runTaskTimer(Plugin plugin, BukkitRunnable task, long delay, long period) throws IllegalArgumentException;
295    
296        /**
297         * <b>Asynchronous tasks should never access any API in Bukkit. Great care
298         * should be taken to assure the thread-safety of asynchronous tasks.</b>
299         * <p>
300         * Returns a task that will repeatedly run asynchronously until cancelled,
301         * starting after the specified number of server ticks.
302         *
303         * @param plugin the reference to the plugin scheduling task
304         * @param task the task to be run
305         * @param delay the ticks to wait before running the task for the first
306         *     time
307         * @param period the ticks to wait between runs
308         * @return a BukkitTask that contains the id number
309         * @throws IllegalArgumentException if plugin is null
310         * @throws IllegalArgumentException if task is null
311         */
312        public BukkitTask runTaskTimerAsynchronously(Plugin plugin, Runnable task, long delay, long period) throws IllegalArgumentException;
313    
314        /**
315         * @deprecated Use {@link BukkitRunnable#runTaskTimerAsynchronously(Plugin, long, long)}
316         */
317        @Deprecated
318        public BukkitTask runTaskTimerAsynchronously(Plugin plugin, BukkitRunnable task, long delay, long period) throws IllegalArgumentException;
319    }