SPIGOT-2540: Add nullability annotations to entire Bukkit API

By: Darkyenus <darkyenus@gmail.com>
2025-08-28 19:03:51 -07:00 · 2019-03-13 17:42:57 +11:00
parent e069a80fd8
commit 416c865476
565 changed files with 5372 additions and 2008 deletions
--- a/paper-api/src/main/java/org/bukkit/scheduler/BukkitRunnable.java
+++ b/paper-api/src/main/java/org/bukkit/scheduler/BukkitRunnable.java
@@ -2,6 +2,7 @@ package org.bukkit.scheduler;

 import org.bukkit.Bukkit;
 import org.bukkit.plugin.Plugin;
+import org.jetbrains.annotations.NotNull;

 /**
 * This class is provided as an easy way to handle scheduling tasks.
@@ -38,7 +39,8 @@ public abstract class BukkitRunnable implements Runnable {
     * @throws IllegalStateException if this was already scheduled
     * @see BukkitScheduler#runTask(Plugin, Runnable)
     */
-    public synchronized BukkitTask runTask(Plugin plugin) throws IllegalArgumentException, IllegalStateException {
+    @NotNull
+    public synchronized BukkitTask runTask(@NotNull Plugin plugin) throws IllegalArgumentException, IllegalStateException {
        checkNotYetScheduled();
        return setupTask(Bukkit.getScheduler().runTask(plugin, (Runnable) this));
    }
@@ -55,7 +57,8 @@ public abstract class BukkitRunnable implements Runnable {
     * @throws IllegalStateException if this was already scheduled
     * @see BukkitScheduler#runTaskAsynchronously(Plugin, Runnable)
     */
-    public synchronized BukkitTask runTaskAsynchronously(Plugin plugin) throws IllegalArgumentException, IllegalStateException  {
+    @NotNull
+    public synchronized BukkitTask runTaskAsynchronously(@NotNull Plugin plugin) throws IllegalArgumentException, IllegalStateException  {
        checkNotYetScheduled();
        return setupTask(Bukkit.getScheduler().runTaskAsynchronously(plugin, (Runnable) this));
    }
@@ -70,7 +73,8 @@ public abstract class BukkitRunnable implements Runnable {
     * @throws IllegalStateException if this was already scheduled
     * @see BukkitScheduler#runTaskLater(Plugin, Runnable, long)
     */
-    public synchronized BukkitTask runTaskLater(Plugin plugin, long delay) throws IllegalArgumentException, IllegalStateException  {
+    @NotNull
+    public synchronized BukkitTask runTaskLater(@NotNull Plugin plugin, long delay) throws IllegalArgumentException, IllegalStateException  {
        checkNotYetScheduled();
        return setupTask(Bukkit.getScheduler().runTaskLater(plugin, (Runnable) this, delay));
    }
@@ -89,7 +93,8 @@ public abstract class BukkitRunnable implements Runnable {
     * @throws IllegalStateException if this was already scheduled
     * @see BukkitScheduler#runTaskLaterAsynchronously(Plugin, Runnable, long)
     */
-    public synchronized BukkitTask runTaskLaterAsynchronously(Plugin plugin, long delay) throws IllegalArgumentException, IllegalStateException  {
+    @NotNull
+    public synchronized BukkitTask runTaskLaterAsynchronously(@NotNull Plugin plugin, long delay) throws IllegalArgumentException, IllegalStateException  {
        checkNotYetScheduled();
        return setupTask(Bukkit.getScheduler().runTaskLaterAsynchronously(plugin, (Runnable) this, delay));
    }
@@ -106,7 +111,8 @@ public abstract class BukkitRunnable implements Runnable {
     * @throws IllegalStateException if this was already scheduled
     * @see BukkitScheduler#runTaskTimer(Plugin, Runnable, long, long)
     */
-    public synchronized BukkitTask runTaskTimer(Plugin plugin, long delay, long period) throws IllegalArgumentException, IllegalStateException  {
+    @NotNull
+    public synchronized BukkitTask runTaskTimer(@NotNull Plugin plugin, long delay, long period) throws IllegalArgumentException, IllegalStateException  {
        checkNotYetScheduled();
        return setupTask(Bukkit.getScheduler().runTaskTimer(plugin, (Runnable) this, delay, period));
    }
@@ -128,7 +134,8 @@ public abstract class BukkitRunnable implements Runnable {
     * @see BukkitScheduler#runTaskTimerAsynchronously(Plugin, Runnable, long,
     *     long)
     */
-    public synchronized BukkitTask runTaskTimerAsynchronously(Plugin plugin, long delay, long period) throws IllegalArgumentException, IllegalStateException  {
+    @NotNull
+    public synchronized BukkitTask runTaskTimerAsynchronously(@NotNull Plugin plugin, long delay, long period) throws IllegalArgumentException, IllegalStateException  {
        checkNotYetScheduled();
        return setupTask(Bukkit.getScheduler().runTaskTimerAsynchronously(plugin, (Runnable) this, delay, period));
    }
@@ -156,7 +163,8 @@ public abstract class BukkitRunnable implements Runnable {
        }
    }

-    private BukkitTask setupTask(final BukkitTask task) {
+    @NotNull
+    private BukkitTask setupTask(@NotNull final BukkitTask task) {
        this.task = task;
        return task;
    }
--- a/paper-api/src/main/java/org/bukkit/scheduler/BukkitScheduler.java
+++ b/paper-api/src/main/java/org/bukkit/scheduler/BukkitScheduler.java
@@ -1,6 +1,8 @@
 package org.bukkit.scheduler;

 import org.bukkit.plugin.Plugin;
+import org.jetbrains.annotations.NotNull;
+
 import java.util.concurrent.Callable;
 import java.util.concurrent.Future;
 import java.util.List;
@@ -18,7 +20,7 @@ public interface BukkitScheduler {
     * @param delay Delay in server ticks before executing task
     * @return Task id number (-1 if scheduling failed)
     */
-    public int scheduleSyncDelayedTask(Plugin plugin, Runnable task, long delay);
+    public int scheduleSyncDelayedTask(@NotNull Plugin plugin, @NotNull Runnable task, long delay);

    /**
     * @deprecated Use {@link BukkitRunnable#runTaskLater(Plugin, long)}
@@ -28,7 +30,7 @@ public interface BukkitScheduler {
     * @return Task id number (-1 if scheduling failed)
     */
    @Deprecated
-    public int scheduleSyncDelayedTask(Plugin plugin, BukkitRunnable task, long delay);
+    public int scheduleSyncDelayedTask(@NotNull Plugin plugin, @NotNull BukkitRunnable task, long delay);

    /**
     * Schedules a once off task to occur as soon as possible.
@@ -39,7 +41,7 @@ public interface BukkitScheduler {
     * @param task Task to be executed
     * @return Task id number (-1 if scheduling failed)
     */
-    public int scheduleSyncDelayedTask(Plugin plugin, Runnable task);
+    public int scheduleSyncDelayedTask(@NotNull Plugin plugin, @NotNull Runnable task);

    /**
     * @deprecated Use {@link BukkitRunnable#runTask(Plugin)}
@@ -48,7 +50,7 @@ public interface BukkitScheduler {
     * @return Task id number (-1 if scheduling failed)
     */
    @Deprecated
-    public int scheduleSyncDelayedTask(Plugin plugin, BukkitRunnable task);
+    public int scheduleSyncDelayedTask(@NotNull Plugin plugin, @NotNull BukkitRunnable task);

    /**
     * Schedules a repeating task.
@@ -61,7 +63,7 @@ public interface BukkitScheduler {
     * @param period Period in server ticks of the task
     * @return Task id number (-1 if scheduling failed)
     */
-    public int scheduleSyncRepeatingTask(Plugin plugin, Runnable task, long delay, long period);
+    public int scheduleSyncRepeatingTask(@NotNull Plugin plugin, @NotNull Runnable task, long delay, long period);

    /**
     * @deprecated Use {@link BukkitRunnable#runTaskTimer(Plugin, long, long)}
@@ -72,7 +74,7 @@ public interface BukkitScheduler {
     * @return Task id number (-1 if scheduling failed)
     */
    @Deprecated
-    public int scheduleSyncRepeatingTask(Plugin plugin, BukkitRunnable task, long delay, long period);
+    public int scheduleSyncRepeatingTask(@NotNull Plugin plugin, @NotNull BukkitRunnable task, long delay, long period);

    /**
     * <b>Asynchronous tasks should never access any API in Bukkit. Great care
@@ -89,7 +91,7 @@ public interface BukkitScheduler {
     *     task, but rather, "an async" task
     */
    @Deprecated
-    public int scheduleAsyncDelayedTask(Plugin plugin, Runnable task, long delay);
+    public int scheduleAsyncDelayedTask(@NotNull Plugin plugin, @NotNull Runnable task, long delay);

    /**
     * <b>Asynchronous tasks should never access any API in Bukkit. Great care
@@ -105,7 +107,7 @@ public interface BukkitScheduler {
     *     task, but rather, "an async" task
     */
    @Deprecated
-    public int scheduleAsyncDelayedTask(Plugin plugin, Runnable task);
+    public int scheduleAsyncDelayedTask(@NotNull Plugin plugin, @NotNull Runnable task);

    /**
     * <b>Asynchronous tasks should never access any API in Bukkit. Great care
@@ -123,7 +125,7 @@ public interface BukkitScheduler {
     *     task, but rather, "an async" task
     */
    @Deprecated
-    public int scheduleAsyncRepeatingTask(Plugin plugin, Runnable task, long delay, long period);
+    public int scheduleAsyncRepeatingTask(@NotNull Plugin plugin, @NotNull Runnable task, long delay, long period);

    /**
     * Calls a method on the main thread and returns a Future object. This
@@ -139,7 +141,8 @@ public interface BukkitScheduler {
     * @param task Task to be executed
     * @return Future Future object related to the task
     */
-    public <T> Future<T> callSyncMethod(Plugin plugin, Callable<T> task);
+    @NotNull
+    public <T> Future<T> callSyncMethod(@NotNull Plugin plugin, @NotNull Callable<T> task);

    /**
     * Removes task from scheduler.
@@ -154,7 +157,7 @@ public interface BukkitScheduler {
     *
     * @param plugin Owner of tasks to be removed
     */
-    public void cancelTasks(Plugin plugin);
+    public void cancelTasks(@NotNull Plugin plugin);

    /**
     * Check if the task currently running.
@@ -193,6 +196,7 @@ public interface BukkitScheduler {
     *
     * @return Active workers
     */
+    @NotNull
    public List<BukkitWorker> getActiveWorkers();

    /**
@@ -201,6 +205,7 @@ public interface BukkitScheduler {
     *
     * @return Active workers
     */
+    @NotNull
    public List<BukkitTask> getPendingTasks();

    /**
@@ -212,7 +217,8 @@ public interface BukkitScheduler {
     * @throws IllegalArgumentException if plugin is null
     * @throws IllegalArgumentException if task is null
     */
-    public BukkitTask runTask(Plugin plugin, Runnable task) throws IllegalArgumentException;
+    @NotNull
+    public BukkitTask runTask(@NotNull Plugin plugin, @NotNull Runnable task) throws IllegalArgumentException;

    /**
     * Returns a task that will run on the next server tick.
@@ -222,7 +228,7 @@ public interface BukkitScheduler {
     * @throws IllegalArgumentException if plugin is null
     * @throws IllegalArgumentException if task is null
     */
-    public void runTask(Plugin plugin, Consumer<BukkitTask> task) throws IllegalArgumentException;
+    public void runTask(@NotNull Plugin plugin, @NotNull Consumer<BukkitTask> task) throws IllegalArgumentException;

    /**
     * @deprecated Use {@link BukkitRunnable#runTask(Plugin)}
@@ -234,7 +240,8 @@ public interface BukkitScheduler {
     * @throws IllegalArgumentException if task is null
     */
    @Deprecated
-    public BukkitTask runTask(Plugin plugin, BukkitRunnable task) throws IllegalArgumentException;
+    @NotNull
+    public BukkitTask runTask(@NotNull Plugin plugin, @NotNull BukkitRunnable task) throws IllegalArgumentException;

    /**
     * <b>Asynchronous tasks should never access any API in Bukkit. Great care
@@ -248,7 +255,8 @@ public interface BukkitScheduler {
     * @throws IllegalArgumentException if plugin is null
     * @throws IllegalArgumentException if task is null
     */
-    public BukkitTask runTaskAsynchronously(Plugin plugin, Runnable task) throws IllegalArgumentException;
+    @NotNull
+    public BukkitTask runTaskAsynchronously(@NotNull Plugin plugin, @NotNull Runnable task) throws IllegalArgumentException;

    /**
     * <b>Asynchronous tasks should never access any API in Bukkit. Great care
@@ -261,7 +269,7 @@ public interface BukkitScheduler {
     * @throws IllegalArgumentException if plugin is null
     * @throws IllegalArgumentException if task is null
     */
-    public void runTaskAsynchronously(Plugin plugin, Consumer<BukkitTask> task) throws IllegalArgumentException;
+    public void runTaskAsynchronously(@NotNull Plugin plugin, @NotNull Consumer<BukkitTask> task) throws IllegalArgumentException;

    /**
     * @deprecated Use {@link BukkitRunnable#runTaskAsynchronously(Plugin)}
@@ -272,7 +280,8 @@ public interface BukkitScheduler {
     * @throws IllegalArgumentException if task is null
     */
    @Deprecated
-    public BukkitTask runTaskAsynchronously(Plugin plugin, BukkitRunnable task) throws IllegalArgumentException;
+    @NotNull
+    public BukkitTask runTaskAsynchronously(@NotNull Plugin plugin, @NotNull BukkitRunnable task) throws IllegalArgumentException;

    /**
     * Returns a task that will run after the specified number of server
@@ -285,7 +294,8 @@ public interface BukkitScheduler {
     * @throws IllegalArgumentException if plugin is null
     * @throws IllegalArgumentException if task is null
     */
-    public BukkitTask runTaskLater(Plugin plugin, Runnable task, long delay) throws IllegalArgumentException;
+    @NotNull
+    public BukkitTask runTaskLater(@NotNull Plugin plugin, @NotNull Runnable task, long delay) throws IllegalArgumentException;

    /**
     * Returns a task that will run after the specified number of server
@@ -297,7 +307,7 @@ public interface BukkitScheduler {
     * @throws IllegalArgumentException if plugin is null
     * @throws IllegalArgumentException if task is null
     */
-    public void runTaskLater(Plugin plugin, Consumer<BukkitTask> task, long delay) throws IllegalArgumentException;
+    public void runTaskLater(@NotNull Plugin plugin, @NotNull Consumer<BukkitTask> task, long delay) throws IllegalArgumentException;

    /**
     * @deprecated Use {@link BukkitRunnable#runTaskLater(Plugin, long)}
@@ -309,7 +319,8 @@ public interface BukkitScheduler {
     * @throws IllegalArgumentException if task is null
     */
    @Deprecated
-    public BukkitTask runTaskLater(Plugin plugin, BukkitRunnable task, long delay) throws IllegalArgumentException;
+    @NotNull
+    public BukkitTask runTaskLater(@NotNull Plugin plugin, @NotNull BukkitRunnable task, long delay) throws IllegalArgumentException;

    /**
     * <b>Asynchronous tasks should never access any API in Bukkit. Great care
@@ -325,7 +336,8 @@ public interface BukkitScheduler {
     * @throws IllegalArgumentException if plugin is null
     * @throws IllegalArgumentException if task is null
     */
-    public BukkitTask runTaskLaterAsynchronously(Plugin plugin, Runnable task, long delay) throws IllegalArgumentException;
+    @NotNull
+    public BukkitTask runTaskLaterAsynchronously(@NotNull Plugin plugin, @NotNull Runnable task, long delay) throws IllegalArgumentException;

    /**
     * <b>Asynchronous tasks should never access any API in Bukkit. Great care
@@ -340,7 +352,7 @@ public interface BukkitScheduler {
     * @throws IllegalArgumentException if plugin is null
     * @throws IllegalArgumentException if task is null
     */
-    public void runTaskLaterAsynchronously(Plugin plugin, Consumer<BukkitTask> task, long delay) throws IllegalArgumentException;
+    public void runTaskLaterAsynchronously(@NotNull Plugin plugin, @NotNull Consumer<BukkitTask> task, long delay) throws IllegalArgumentException;

    /**
     * @deprecated Use {@link BukkitRunnable#runTaskLaterAsynchronously(Plugin, long)}
@@ -352,7 +364,8 @@ public interface BukkitScheduler {
     * @throws IllegalArgumentException if task is null
     */
    @Deprecated
-    public BukkitTask runTaskLaterAsynchronously(Plugin plugin, BukkitRunnable task, long delay) throws IllegalArgumentException;
+    @NotNull
+    public BukkitTask runTaskLaterAsynchronously(@NotNull Plugin plugin, @NotNull BukkitRunnable task, long delay) throws IllegalArgumentException;

    /**
     * Returns a task that will repeatedly run until cancelled, starting after
@@ -366,7 +379,8 @@ public interface BukkitScheduler {
     * @throws IllegalArgumentException if plugin is null
     * @throws IllegalArgumentException if task is null
     */
-    public BukkitTask runTaskTimer(Plugin plugin, Runnable task, long delay, long period) throws IllegalArgumentException;
+    @NotNull
+    public BukkitTask runTaskTimer(@NotNull Plugin plugin, @NotNull Runnable task, long delay, long period) throws IllegalArgumentException;

    /**
     * Returns a task that will repeatedly run until cancelled, starting after
@@ -379,7 +393,7 @@ public interface BukkitScheduler {
     * @throws IllegalArgumentException if plugin is null
     * @throws IllegalArgumentException if task is null
     */
-    public void runTaskTimer(Plugin plugin, Consumer<BukkitTask> task, long delay, long period) throws IllegalArgumentException;
+    public void runTaskTimer(@NotNull Plugin plugin, @NotNull Consumer<BukkitTask> task, long delay, long period) throws IllegalArgumentException;

    /**
     * @deprecated Use {@link BukkitRunnable#runTaskTimer(Plugin, long, long)}
@@ -392,7 +406,8 @@ public interface BukkitScheduler {
     * @throws IllegalArgumentException if task is null
     */
    @Deprecated
-    public BukkitTask runTaskTimer(Plugin plugin, BukkitRunnable task, long delay, long period) throws IllegalArgumentException;
+    @NotNull
+    public BukkitTask runTaskTimer(@NotNull Plugin plugin, @NotNull BukkitRunnable task, long delay, long period) throws IllegalArgumentException;

    /**
     * <b>Asynchronous tasks should never access any API in Bukkit. Great care
@@ -410,7 +425,8 @@ public interface BukkitScheduler {
     * @throws IllegalArgumentException if plugin is null
     * @throws IllegalArgumentException if task is null
     */
-    public BukkitTask runTaskTimerAsynchronously(Plugin plugin, Runnable task, long delay, long period) throws IllegalArgumentException;
+    @NotNull
+    public BukkitTask runTaskTimerAsynchronously(@NotNull Plugin plugin, @NotNull Runnable task, long delay, long period) throws IllegalArgumentException;

    /**
     * <b>Asynchronous tasks should never access any API in Bukkit. Great care
@@ -427,7 +443,7 @@ public interface BukkitScheduler {
     * @throws IllegalArgumentException if plugin is null
     * @throws IllegalArgumentException if task is null
     */
-    public void runTaskTimerAsynchronously(Plugin plugin, Consumer<BukkitTask> task, long delay, long period) throws IllegalArgumentException;
+    public void runTaskTimerAsynchronously(@NotNull Plugin plugin, @NotNull Consumer<BukkitTask> task, long delay, long period) throws IllegalArgumentException;

    /**
     * @deprecated Use {@link BukkitRunnable#runTaskTimerAsynchronously(Plugin, long, long)}
@@ -441,5 +457,6 @@ public interface BukkitScheduler {
     * @throws IllegalArgumentException if task is null
     */
    @Deprecated
-    public BukkitTask runTaskTimerAsynchronously(Plugin plugin, BukkitRunnable task, long delay, long period) throws IllegalArgumentException;
+    @NotNull
+    public BukkitTask runTaskTimerAsynchronously(@NotNull Plugin plugin, @NotNull BukkitRunnable task, long delay, long period) throws IllegalArgumentException;
 }
--- a/paper-api/src/main/java/org/bukkit/scheduler/BukkitTask.java
+++ b/paper-api/src/main/java/org/bukkit/scheduler/BukkitTask.java
@@ -1,6 +1,7 @@
 package org.bukkit.scheduler;

 import org.bukkit.plugin.Plugin;
+import org.jetbrains.annotations.NotNull;

 /**
 * Represents a task being executed by the scheduler
@@ -19,6 +20,7 @@ public interface BukkitTask {
     *
     * @return The Plugin that owns the task
     */
+    @NotNull
    public Plugin getOwner();

    /**
--- a/paper-api/src/main/java/org/bukkit/scheduler/BukkitWorker.java
+++ b/paper-api/src/main/java/org/bukkit/scheduler/BukkitWorker.java
@@ -1,6 +1,7 @@
 package org.bukkit.scheduler;

 import org.bukkit.plugin.Plugin;
+import org.jetbrains.annotations.NotNull;

 /**
 * Represents a worker thread for the scheduler. This gives information about
@@ -22,6 +23,7 @@ public interface BukkitWorker {
     *
     * @return The Plugin that owns the task
     */
+    @NotNull
    public Plugin getOwner();

    /**
@@ -29,6 +31,7 @@ public interface BukkitWorker {
     *
     * @return The Thread object for the worker
     */
+    @NotNull
    public Thread getThread();

 }