Skip to content

Commit 899fbb7

Browse files
maxcom1maxcom1
committed
Extend BukkitScheduler with simplified methods
1 parent 763b32d commit 899fbb7

File tree

3 files changed

+509
-0
lines changed

3 files changed

+509
-0
lines changed

‎paper-api/src/main/java/org/bukkit/scheduler/BukkitScheduler.java‎

Lines changed: 295 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
package org.bukkit.scheduler;
22

3+
import java.time.Duration;
4+
import java.time.LocalDateTime;
5+
import java.time.LocalTime;
36
import java.util.List;
47
import java.util.concurrent.Callable;
58
import java.util.concurrent.Future;
@@ -21,6 +24,21 @@ public interface BukkitScheduler {
2124
*/
2225
public int scheduleSyncDelayedTask(@NotNull Plugin plugin, @NotNull Runnable task, long delay);
2326

27+
/**
28+
* Schedules a once off task to occur after a delay.
29+
* <p>
30+
* Note that the smallest unit for {@link org.bukkit.scheduler.BukkitScheduler} is still 1 tick (50ms).
31+
* Values smaller than 50ms will be rounded down.
32+
* <p>
33+
* This task will be executed by the main server thread.
34+
*
35+
* @param plugin Plugin that owns the task
36+
* @param task Task to be executed
37+
* @param delay Delay in {@link java.time.Duration} before executing task
38+
* @return Task id number (-1 if scheduling failed)
39+
*/
40+
public int scheduleSyncDelayedTask(@NotNull Plugin plugin, @NotNull Runnable task, @NotNull Duration delay);
41+
2442
/**
2543
* @param plugin Plugin that owns the task
2644
* @param task Task to be executed
@@ -64,6 +82,22 @@ public interface BukkitScheduler {
6482
*/
6583
public int scheduleSyncRepeatingTask(@NotNull Plugin plugin, @NotNull Runnable task, long delay, long period);
6684

85+
/**
86+
* Schedules a repeating task.
87+
* <p>
88+
* Note that the smallest unit for {@link org.bukkit.scheduler.BukkitScheduler} is still 1 tick (50ms).
89+
* Values smaller than 50ms will be rounded down.
90+
* <p>
91+
* This task will be executed by the main server thread.
92+
*
93+
* @param plugin Plugin that owns the task
94+
* @param task Task to be executed
95+
* @param delay Delay in {@link java.time.Duration} before executing first repeat
96+
* @param period Period in {@link java.time.Duration} of the task execution
97+
* @return Task id number (-1 if scheduling failed)
98+
*/
99+
public int scheduleSyncRepeatingTask(@NotNull Plugin plugin, @NotNull Runnable task, @NotNull Duration delay, @NotNull Duration period);
100+
67101
/**
68102
* @param plugin Plugin that owns the task
69103
* @param task Task to be executed
@@ -295,6 +329,9 @@ public interface BukkitScheduler {
295329
@NotNull
296330
public BukkitTask runTaskLater(@NotNull Plugin plugin, @NotNull Runnable task, long delay) throws IllegalArgumentException;
297331

332+
@NotNull
333+
public BukkitTask runTaskLater(@NotNull Plugin plugin, @NotNull Runnable task, @NotNull Duration delay) throws IllegalArgumentException;
334+
298335
/**
299336
* Returns a task that will run after the specified number of server
300337
* ticks.
@@ -307,6 +344,22 @@ public interface BukkitScheduler {
307344
*/
308345
public void runTaskLater(@NotNull Plugin plugin, @NotNull Consumer<? super BukkitTask> task, long delay) throws IllegalArgumentException;
309346

347+
/**
348+
* Returns a task that will run after the specified duration.
349+
* <p>
350+
* The time given in {@link java.time.Duration} is converted to number of ticks.
351+
* Note that the smallest unit for {@link org.bukkit.scheduler.BukkitScheduler} is still 1 tick (50ms).
352+
* Values smaller than 50ms will be rounded down.
353+
*
354+
* @param plugin the reference to the plugin scheduling task
355+
* @param task the task to be run
356+
* @param delay duration to wait before running the task
357+
* @throws IllegalArgumentException if plugin is null
358+
* @throws IllegalArgumentException if task is null
359+
* @throws IllegalArgumentException if delay is null
360+
*/
361+
public void runTaskLater(@NotNull Plugin plugin, @NotNull Consumer<? super BukkitTask> task, @NotNull Duration delay) throws IllegalArgumentException;
362+
310363
/**
311364
* @param plugin the reference to the plugin scheduling task
312365
* @param task the task to be run
@@ -337,6 +390,27 @@ public interface BukkitScheduler {
337390
@NotNull
338391
public BukkitTask runTaskLaterAsynchronously(@NotNull Plugin plugin, @NotNull Runnable task, long delay) throws IllegalArgumentException;
339392

393+
/**
394+
* <b>Asynchronous tasks should never access any API in Bukkit.</b> <b>Great care
395+
* should be taken to assure the thread-safety of asynchronous tasks.</b>
396+
* <p>
397+
* Returns a task that will run asynchronously after the specified duration.
398+
* <p>
399+
* The time given in {@link java.time.Duration} is converted to number of ticks.
400+
* Note that the smallest unit for {@link org.bukkit.scheduler.BukkitScheduler} is still 1 tick (50ms).
401+
* Values smaller than 50ms will be rounded down.
402+
*
403+
* @param plugin the reference to the plugin scheduling task
404+
* @param task the task to be run
405+
* @param delay the duration to wait before running the task
406+
* @return a BukkitTask that contains the id number
407+
* @throws IllegalArgumentException if plugin is null
408+
* @throws IllegalArgumentException if task is null
409+
* @throws IllegalArgumentException if delay is null
410+
*/
411+
@NotNull
412+
public BukkitTask runTaskLaterAsynchronously(@NotNull Plugin plugin, @NotNull Runnable task, @NotNull Duration delay) throws IllegalArgumentException;
413+
340414
/**
341415
* <b>Asynchronous tasks should never access any API in Bukkit.</b> <b>Great care
342416
* should be taken to assure the thread-safety of asynchronous tasks.</b>
@@ -352,6 +426,25 @@ public interface BukkitScheduler {
352426
*/
353427
public void runTaskLaterAsynchronously(@NotNull Plugin plugin, @NotNull Consumer<? super BukkitTask> task, long delay) throws IllegalArgumentException;
354428

429+
/**
430+
* <b>Asynchronous tasks should never access any API in Bukkit.</b> <b>Great care
431+
* should be taken to assure the thread-safety of asynchronous tasks.</b>
432+
* <p>
433+
* Returns a task that will run asynchronously after the specified duration.
434+
* <p>
435+
* The time given in {@link java.time.Duration} is converted to number of ticks.
436+
* Note that the smallest unit for {@link org.bukkit.scheduler.BukkitScheduler} is still 1 tick (50ms).
437+
* Values smaller than 50ms will be rounded down.
438+
*
439+
* @param plugin the reference to the plugin scheduling task
440+
* @param task the task to be run
441+
* @param delay the duration to wait before running the task
442+
* @throws IllegalArgumentException if plugin is null
443+
* @throws IllegalArgumentException if task is null
444+
* @throws IllegalArgumentException if delay is null
445+
*/
446+
public void runTaskLaterAsynchronously(@NotNull Plugin plugin, @NotNull Consumer<? super BukkitTask> task, @NotNull Duration delay) throws IllegalArgumentException;
447+
355448
/**
356449
* @param plugin the reference to the plugin scheduling task
357450
* @param task the task to be run
@@ -380,6 +473,27 @@ public interface BukkitScheduler {
380473
@NotNull
381474
public BukkitTask runTaskTimer(@NotNull Plugin plugin, @NotNull Runnable task, long delay, long period) throws IllegalArgumentException;
382475

476+
/**
477+
* Returns a task that will repeatedly run until cancelled,
478+
* starting after the specified duration.
479+
* <p>
480+
* The time given in {@link java.time.Duration} is converted to number of ticks.
481+
* Note that the smallest unit for {@link org.bukkit.scheduler.BukkitScheduler} is still 1 tick (50ms).
482+
* Values smaller than 50ms will be rounded down.
483+
*
484+
* @param plugin the reference to the plugin scheduling task
485+
* @param task the task to be run
486+
* @param delay the duration to wait before running the task
487+
* @param period the duration to wait between runs
488+
* @return a BukkitTask that contains the id number
489+
* @throws IllegalArgumentException if plugin is null
490+
* @throws IllegalArgumentException if task is null
491+
* @throws IllegalArgumentException if delay is null
492+
* @throws IllegalArgumentException if period is null
493+
*/
494+
@NotNull
495+
public BukkitTask runTaskTimer(@NotNull Plugin plugin, @NotNull Runnable task, @NotNull Duration delay, @NotNull Duration period) throws IllegalArgumentException;
496+
383497
/**
384498
* Returns a task that will repeatedly run until cancelled, starting after
385499
* the specified number of server ticks.
@@ -393,6 +507,25 @@ public interface BukkitScheduler {
393507
*/
394508
public void runTaskTimer(@NotNull Plugin plugin, @NotNull Consumer<? super BukkitTask> task, long delay, long period) throws IllegalArgumentException;
395509

510+
/**
511+
* Returns a task that will repeatedly run until cancelled,
512+
* starting after the specified duration.
513+
* <p>
514+
* The time given in {@link java.time.Duration} is converted to number of ticks.
515+
* Note that the smallest unit for {@link org.bukkit.scheduler.BukkitScheduler} is still 1 tick (50ms).
516+
* Values smaller than 50ms will be rounded down.
517+
*
518+
* @param plugin the reference to the plugin scheduling task
519+
* @param task the task to be run
520+
* @param delay the duration to wait before running the task
521+
* @param period the duration to wait between runs
522+
* @throws IllegalArgumentException if plugin is null
523+
* @throws IllegalArgumentException if task is null
524+
* @throws IllegalArgumentException if delay is null
525+
* @throws IllegalArgumentException if period is null
526+
*/
527+
public void runTaskTimer(@NotNull Plugin plugin, @NotNull Consumer<? super BukkitTask> task, @NotNull Duration delay, @NotNull Duration period) throws IllegalArgumentException;
528+
396529
/**
397530
* @param plugin the reference to the plugin scheduling task
398531
* @param task the task to be run
@@ -426,6 +559,31 @@ public interface BukkitScheduler {
426559
@NotNull
427560
public BukkitTask runTaskTimerAsynchronously(@NotNull Plugin plugin, @NotNull Runnable task, long delay, long period) throws IllegalArgumentException;
428561

562+
/**
563+
* <b>Asynchronous tasks should never access any API in Bukkit.</b> <b>Great care
564+
* should be taken to assure the thread-safety of asynchronous tasks.</b>
565+
* <p>
566+
* Returns a task that will repeatedly run asynchronously until cancelled,
567+
* starting after the specified duration.
568+
* <p>
569+
* The time given in {@link java.time.Duration} is converted to number of ticks.
570+
* Note that the smallest unit for {@link org.bukkit.scheduler.BukkitScheduler} is still 1 tick (50ms).
571+
* Values smaller than 50ms will be rounded down.
572+
*
573+
* @param plugin the reference to the plugin scheduling task
574+
* @param task the task to be run
575+
* @param delay the duration to wait before running the task for the
576+
* first time
577+
* @param period the duration to wait between runs
578+
* @return a BukkitTask that contains the id number
579+
* @throws IllegalArgumentException if plugin is null
580+
* @throws IllegalArgumentException if task is null
581+
* @throws IllegalArgumentException if delay is null
582+
* @throws IllegalArgumentException if period is null
583+
*/
584+
@NotNull
585+
public BukkitTask runTaskTimerAsynchronously(@NotNull Plugin plugin, @NotNull Runnable task, @NotNull Duration delay, @NotNull Duration period) throws IllegalArgumentException;
586+
429587
/**
430588
* <b>Asynchronous tasks should never access any API in Bukkit.</b> <b>Great care
431589
* should be taken to assure the thread-safety of asynchronous tasks.</b>
@@ -443,6 +601,29 @@ public interface BukkitScheduler {
443601
*/
444602
public void runTaskTimerAsynchronously(@NotNull Plugin plugin, @NotNull Consumer<? super BukkitTask> task, long delay, long period) throws IllegalArgumentException;
445603

604+
/**
605+
* <b>Asynchronous tasks should never access any API in Bukkit.</b> <b>Great care
606+
* should be taken to assure the thread-safety of asynchronous tasks.</b>
607+
* <p>
608+
* Returns a task that will repeatedly run asynchronously until cancelled,
609+
* starting after the specified duration.
610+
* <p>
611+
* The time given in {@link java.time.Duration} is converted to number of ticks.
612+
* Note that the smallest unit for {@link org.bukkit.scheduler.BukkitScheduler} is still 1 tick (50ms).
613+
* Values smaller than 50ms will be rounded down.
614+
*
615+
* @param plugin the reference to the plugin scheduling task
616+
* @param task the task to be run
617+
* @param delay the duration to wait before running the task for the
618+
* first time
619+
* @param period the duration to wait between runs
620+
* @throws IllegalArgumentException if plugin is null
621+
* @throws IllegalArgumentException if task is null
622+
* @throws IllegalArgumentException if delay is null
623+
* @throws IllegalArgumentException if period is null
624+
*/
625+
public void runTaskTimerAsynchronously(@NotNull Plugin plugin, @NotNull Consumer<? super BukkitTask> task, @NotNull Duration delay, @NotNull Duration period) throws IllegalArgumentException;
626+
446627
/**
447628
* @param plugin the reference to the plugin scheduling task
448629
* @param task the task to be run
@@ -458,6 +639,120 @@ public interface BukkitScheduler {
458639
@NotNull
459640
public BukkitTask runTaskTimerAsynchronously(@NotNull Plugin plugin, @NotNull BukkitRunnable task, long delay, long period) throws IllegalArgumentException;
460641

642+
/**
643+
* Returns a task that will run at a specified date time.
644+
* <p>
645+
* The LocalDateTime used is the local time, appropriate
646+
* time zone adjustments are made automatically.
647+
*
648+
* @param plugin the reference to the plugin scheduling task
649+
* @param runnable the task to be run
650+
* @param localDateTime the time to run this task at
651+
* @throws IllegalArgumentException if plugin is null
652+
* @throws IllegalArgumentException if runnable is null
653+
* @throws IllegalArgumentException if localDateTime is nll
654+
*/
655+
@NotNull
656+
public BukkitTask runTaskAtTime(@NotNull Plugin plugin, @NotNull Runnable runnable, @NotNull LocalDateTime localDateTime) throws IllegalArgumentException;
657+
658+
/**
659+
* Returns a task that will run at a specified date time.
660+
* <p>
661+
* The LocalDateTime used is the local time, appropriate
662+
* time zone adjustments are made automatically.
663+
*
664+
* @param plugin the reference to the plugin scheduling task
665+
* @param task the task to be run
666+
* @param localDateTime the time to run this task at
667+
* @throws IllegalArgumentException if plugin is null
668+
* @throws IllegalArgumentException if runnable is null
669+
* @throws IllegalArgumentException if localDateTime is nll
670+
*/
671+
@NotNull
672+
public void runTaskAtTime(@NotNull Plugin plugin, @NotNull Consumer<? super BukkitTask> task, @NotNull LocalDateTime localDateTime) throws IllegalArgumentException;
673+
674+
/**
675+
* <b>Asynchronous tasks should never access any API in Bukkit.</b> <b>Great care
676+
* should be taken to assure the thread-safety of asynchronous tasks.</b>
677+
* <p>
678+
* Returns a task that will run asynchronously
679+
* at a specified date time.
680+
* <p>
681+
* The LocalDateTime used is the local time, appropriate
682+
* time zone adjustments are made automatically.
683+
*
684+
* @param plugin the reference to the plugin scheduling task
685+
* @param runnable the task to be run
686+
* @param localDateTime the time to run this task at
687+
* @throws IllegalArgumentException if plugin is null
688+
* @throws IllegalArgumentException if runnable is null
689+
* @throws IllegalArgumentException if localDateTime is nll
690+
*/
691+
@NotNull
692+
public BukkitTask runTaskAtTimeAsynchronously(@NotNull Plugin plugin, @NotNull Runnable runnable, @NotNull LocalDateTime localDateTime) throws IllegalArgumentException;
693+
694+
/**
695+
* <b>Asynchronous tasks should never access any API in Bukkit.</b> <b>Great care
696+
* should be taken to assure the thread-safety of asynchronous tasks.</b>
697+
* <p>
698+
* Returns a task that will run asynchronously
699+
* at a specified date time.
700+
* <p>
701+
* The LocalDateTime used is the local time, appropriate
702+
* time zone adjustments are made automatically.
703+
*
704+
* @param plugin the reference to the plugin scheduling task
705+
* @param task the task to be run
706+
* @param localDateTime the time to run this task at
707+
* @throws IllegalArgumentException if plugin is null
708+
* @throws IllegalArgumentException if runnable is null
709+
* @throws IllegalArgumentException if localDateTime is nll
710+
*/
711+
@NotNull
712+
public void runTaskAtTimeAsynchronously(@NotNull Plugin plugin, @NotNull Consumer<? super BukkitTask> task, @NotNull LocalDateTime localDateTime) throws IllegalArgumentException;
713+
714+
/**
715+
* Returns a task that will run every day at
716+
* a specified time (hour, minute and second).
717+
* <p>
718+
* The LocalTime used is the local time, appropriate
719+
* time zone adjustments are made automatically.
720+
*
721+
* @param plugin the reference to the plugin scheduling task
722+
* @param runnable the task to be run
723+
* @param localTime the time to run this task at
724+
* @throws IllegalArgumentException if plugin is null
725+
* @throws IllegalArgumentException if runnable is null
726+
* @throws IllegalArgumentException if LocalTime is nll
727+
*/
728+
@NotNull
729+
public BukkitTask runRepeatedTaskAtTime(@NotNull Plugin plugin, @NotNull Runnable runnable, @NotNull LocalTime localTime) throws IllegalArgumentException;
730+
731+
/**
732+
* Returns a task that will run every day at
733+
* a specified time (hour, minute and second).
734+
* <p>
735+
* The LocalTime used is the local time, appropriate
736+
* time zone adjustments are made automatically.
737+
*
738+
* @param plugin the reference to the plugin scheduling task
739+
* @param task the task to be run
740+
* @param localTime the time to run this task at
741+
* @throws IllegalArgumentException if plugin is null
742+
* @throws IllegalArgumentException if runnable is null
743+
* @throws IllegalArgumentException if LocalTime is nll
744+
*/
745+
@NotNull
746+
public void runRepeatedTaskAtTime(@NotNull Plugin plugin, @NotNull Consumer<? super BukkitTask> task, @NotNull LocalTime localTime) throws IllegalArgumentException;
747+
748+
/*
749+
@NotNull
750+
public BukkitTask runRepeatedTaskAtTimeAsynchronously(@NotNull Plugin plugin, @NotNull Runnable runnable, @NotNull LocalTime localTime) throws IllegalArgumentException;
751+
752+
@NotNull
753+
public void runRepeatedTaskAtTimeAsynchronously(@NotNull Plugin plugin, @NotNull Consumer<? super BukkitTask> task, @NotNull LocalTime localTime) throws IllegalArgumentException;
754+
*/
755+
461756
// Paper start - add getMainThreadExecutor
462757
/**
463758
* Returns an executor that will run tasks on the next server tick.

0 commit comments

Comments
 (0)