GH-1212 Replace JetBrains nullability annotations with JSpecify

buildSrc/src/main/kotlin/Versions.kt

@@ -7,7 +7,10 @@ object Versions {
     const val MULTIFICATION = "1.2.4"
 
     const val JETBRAINS_ANNOTATIONS = "26.0.2-1"
+    const val JSPECIFY = "1.0.0"
+
     const val PLACEHOLDER_API = "2.12.1"
+
     const val DYNMAP_API = "3.7-beta-6"
     const val LOMBOK = "1.18.42"
 

eternalcore-api/build.gradle.kts

@@ -7,4 +7,5 @@ plugins {
 dependencies {
     compileOnly("org.spigotmc:spigot-api:${Versions.SPIGOT_API}")
     api("org.jetbrains:annotations:${Versions.JETBRAINS_ANNOTATIONS}")
+    api("org.jspecify:jspecify:${Versions.JSPECIFY}")
 }

eternalcore-api/src/main/java/com/eternalcode/core/EternalCoreApiProvider.java

@@ -1,7 +1,11 @@
 package com.eternalcode.core;
 
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.Nullable;
+
 public final class EternalCoreApiProvider {
 
+    @Nullable
     private static EternalCoreApi api;
 
     private EternalCoreApiProvider() {
@@ -16,6 +20,7 @@ public static EternalCoreApi provide() {
         return api;
     }
 
+    @ApiStatus.Internal
     static void initialize(EternalCoreApi api) {
         if (EternalCoreApiProvider.api != null) {
             throw new IllegalStateException("EternalCoreApiProvider is already initialized");
@@ -28,6 +33,7 @@ static void initialize(EternalCoreApi api) {
         EternalCoreApiProvider.api = api;
     }
 
+    @ApiStatus.Internal
     static void deinitialize() {
         if (EternalCoreApiProvider.api == null) {
             throw new IllegalStateException("EternalCoreApiProvider is not initialized");

eternalcore-api/src/main/java/com/eternalcode/core/feature/adminchat/AdminChatService.java

@@ -3,8 +3,8 @@
 import java.util.Collection;
 import java.util.UUID;
 import org.bukkit.command.CommandSender;
-import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Unmodifiable;
+import org.jspecify.annotations.NonNull;
 
 /**
  * Service responsible for managing admin chat functionality.
@@ -20,15 +20,15 @@ public interface AdminChatService {
      * @param playerUuid the UUID of the player to toggle admin chat for
      * @return {@code true} if persistent chat was enabled, {@code false} if it was disabled
      */
-    boolean toggleChat(@NotNull UUID playerUuid);
+    boolean toggleChat(@NonNull UUID playerUuid);
 
     /**
      * Checks if the persistent admin chat mode is enabled for the specified player.
      *
      * @param playerUuid the UUID of the player to check
      * @return {@code true} if persistent chat is enabled, {@code false} otherwise
      */
-    boolean hasEnabledChat(@NotNull UUID playerUuid);
+    boolean hasEnabledChat(@NonNull UUID playerUuid);
 
     /**
      * Retrieves all players who currently have persistent admin chat enabled.
@@ -39,7 +39,6 @@ public interface AdminChatService {
      *
      * @return an unmodifiable collection of player UUIDs with enabled admin chat
      */
-    @NotNull
     @Unmodifiable
     Collection<UUID> getPlayersWithEnabledChat();
 
@@ -52,27 +51,27 @@ public interface AdminChatService {
      * @param message the message content to send
      * @param sender  the command sender who is sending the message
      */
-    void sendAdminChatMessage(@NotNull String message, @NotNull CommandSender sender);
+    void sendAdminChatMessage(@NonNull String message, @NonNull CommandSender sender);
 
     /**
      * Enables persistent admin chat for the specified player.
      *
      * @param playerUuid the UUID of the player
      */
-    void enableChat(@NotNull UUID playerUuid);
+    void enableChat(@NonNull UUID playerUuid);
 
     /**
      * Disables persistent admin chat for the specified player.
      *
      * @param playerUuid the UUID of the player
      */
-    void disableChat(@NotNull UUID playerUuid);
+    void disableChat(@NonNull UUID playerUuid);
 
     /**
      * Checks if the specified command sender has permission to see admin chat messages.
      *
      * @param sender the command sender to check
      * @return {@code true} if the sender can see admin chat messages, {@code false} otherwise
      */
-    boolean canSeeAdminChat(@NotNull CommandSender sender);
+    boolean canSeeAdminChat(@NonNull CommandSender sender);
 }

eternalcore-api/src/main/java/com/eternalcode/core/feature/adminchat/event/AdminChatEvent.java

@@ -1,10 +1,11 @@
 package com.eternalcode.core.feature.adminchat.event;
 
+import java.util.Objects;
 import org.bukkit.command.CommandSender;
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
-import org.jetbrains.annotations.NotNull;
+import org.jspecify.annotations.NonNull;
 
 /**
  * Event called when an admin chat message is being sent.
@@ -21,40 +22,27 @@ public class AdminChatEvent extends Event implements Cancellable {
     private String content;
     private boolean cancelled;
 
-    public AdminChatEvent(@NotNull CommandSender sender, @NotNull String content) {
+    public AdminChatEvent(CommandSender sender, String content) {
         super(false);
 
-        if (sender == null) {
-            throw new IllegalArgumentException("Sender cannot be null");
-        }
-        if (content == null) {
-            throw new IllegalArgumentException("Content cannot be null");
-        }
-
-        this.sender = sender;
-        this.content = content;
+        this.sender = Objects.requireNonNull(sender, "sender cannot be null");
+        this.content = Objects.requireNonNull(content, "content cannot be null");
         this.cancelled = false;
     }
 
-    @NotNull
     public static HandlerList getHandlerList() {
         return HANDLER_LIST;
     }
 
-    @NotNull
     public CommandSender getSender() {
         return this.sender;
     }
 
-    @NotNull
     public String getContent() {
         return this.content;
     }
 
-    public void setContent(@NotNull String content) {
-        if (content == null) {
-            throw new IllegalArgumentException("Content cannot be null");
-        }
+    public void setContent(String content) {
         this.content = content;
     }
 
@@ -69,8 +57,7 @@ public void setCancelled(boolean cancelled) {
     }
 
     @Override
-    @NotNull
-    public HandlerList getHandlers() {
+    public @NonNull HandlerList getHandlers() {
         return HANDLER_LIST;
     }
 }

eternalcore-api/src/main/java/com/eternalcode/core/feature/afk/event/AfkSwitchEvent.java

@@ -4,6 +4,7 @@
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
+import org.jspecify.annotations.NonNull;
 
 /**
  * Called when a player switches their afk status.
@@ -41,7 +42,7 @@ public void setCancelled(boolean cancel) {
     }
 
     @Override
-    public HandlerList getHandlers() {
+    public @NonNull HandlerList getHandlers() {
         return HANDLER_LIST;
     }
 

eternalcore-api/src/main/java/com/eternalcode/core/feature/butcher/ButcherEntityRemoveEvent.java

@@ -4,6 +4,7 @@
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
+import org.jspecify.annotations.NonNull;
 
 public class ButcherEntityRemoveEvent extends Event implements Cancellable {
 
@@ -31,7 +32,7 @@ public Entity getEntity() {
     }
 
     @Override
-    public HandlerList getHandlers() {
+    public @NonNull HandlerList getHandlers() {
         return HANDLER_LIST;
     }
 

eternalcore-api/src/main/java/com/eternalcode/core/feature/catboy/CatboyService.java

@@ -1,12 +1,11 @@
 package com.eternalcode.core.feature.catboy;
 
-import org.bukkit.entity.Cat;
-import org.bukkit.entity.Player;
-import org.jetbrains.annotations.Unmodifiable;
-
 import java.util.Collection;
 import java.util.Optional;
 import java.util.UUID;
+import org.bukkit.entity.Cat;
+import org.bukkit.entity.Player;
+import org.jetbrains.annotations.Unmodifiable;
 
 /**
  * Service for managing catboys.

eternalcore-api/src/main/java/com/eternalcode/core/feature/catboy/event/CatboySwitchEvent.java

@@ -3,6 +3,7 @@
 import org.bukkit.entity.Player;
 import org.bukkit.event.HandlerList;
 import org.bukkit.event.player.PlayerEvent;
+import org.jspecify.annotations.NonNull;
 
 /**
  * Called when a player switches their catboy status.
@@ -26,7 +27,7 @@ public boolean isCatboy() {
     }
 
     @Override
-    public HandlerList getHandlers() {
+    public @NonNull HandlerList getHandlers() {
         return HANDLER_LIST;
     }
 

eternalcore-api/src/main/java/com/eternalcode/core/feature/chat/event/ClearChatEvent.java

@@ -4,6 +4,7 @@
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
+import org.jspecify.annotations.NonNull;
 
 /**
  * Called when one of the server administrators clear chat using /chat clear command.
@@ -35,7 +36,7 @@ public void setCancelled(boolean cancelled) {
     }
 
     @Override
-    public HandlerList getHandlers() {
+    public @NonNull HandlerList getHandlers() {
         return HANDLER_LIST;
     }
 

eternalcore-api/src/main/java/com/eternalcode/core/feature/chat/event/DisableChatEvent.java

@@ -4,6 +4,7 @@
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
+import org.jspecify.annotations.NonNull;
 
 /**
  * Called when one of the server administrators disables chat using /chat off command.
@@ -35,7 +36,7 @@ public void setCancelled(boolean cancelled) {
     }
 
     @Override
-    public HandlerList getHandlers() {
+    public @NonNull HandlerList getHandlers() {
         return HANDLER_LIST;
     }
 

eternalcore-api/src/main/java/com/eternalcode/core/feature/chat/event/EditSlowModeEvent.java

@@ -6,6 +6,7 @@
 
 import java.time.Duration;
 import java.util.UUID;
+import org.jspecify.annotations.NonNull;
 
 /**
  * Called when one of the server administrators edit slowmode chat using /chat slowmode command.
@@ -54,7 +55,7 @@ public void setCancelled(boolean cancelled) {
     }
 
     @Override
-    public HandlerList getHandlers() {
+    public @NonNull HandlerList getHandlers() {
         return HANDLER_LIST;
     }
 

eternalcore-api/src/main/java/com/eternalcode/core/feature/chat/event/EnableChatEvent.java

@@ -4,6 +4,7 @@
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
+import org.jspecify.annotations.NonNull;
 
 /**
  * Called when one of the server administrators enables chat using /chat on command.
@@ -35,7 +36,7 @@ public void setCancelled(boolean cancelled) {
     }
 
     @Override
-    public HandlerList getHandlers() {
+    public @NonNull HandlerList getHandlers() {
         return HANDLER_LIST;
     }
 

eternalcore-api/src/main/java/com/eternalcode/core/feature/helpop/event/HelpOpEvent.java

@@ -4,6 +4,7 @@
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
+import org.jspecify.annotations.NonNull;
 
 public class HelpOpEvent extends Event implements Cancellable {
 
@@ -39,7 +40,7 @@ public void setCancelled(boolean cancel) {
     }
 
     @Override
-    public HandlerList getHandlers() {
+    public @NonNull HandlerList getHandlers() {
         return HANDLER_LIST;
     }
 

eternalcore-api/src/main/java/com/eternalcode/core/feature/home/HomeService.java

@@ -1,12 +1,11 @@
 package com.eternalcode.core.feature.home;
 
 import java.util.Collection;
-import java.util.Map;
 import java.util.Optional;
 import java.util.UUID;
 import org.bukkit.Location;
 import org.bukkit.entity.Player;
-import org.jetbrains.annotations.Nullable;
+import org.jspecify.annotations.Nullable;
 
 public interface HomeService {
 

eternalcore-api/src/main/java/com/eternalcode/core/feature/home/event/HomeCreateEvent.java

@@ -5,6 +5,7 @@
 import org.bukkit.event.Cancellable;
 import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
+import org.jspecify.annotations.NonNull;
 
 /**
  * Event called when a home is created.
@@ -62,7 +63,7 @@ public void setCancelled(boolean cancel) {
     }
 
     @Override
-    public HandlerList getHandlers() {
+    public @NonNull HandlerList getHandlers() {
         return HANDLER_LIST;
     }
 

eternalcore-api/src/main/java/com/eternalcode/core/feature/home/event/HomeDeleteEvent.java

@@ -6,6 +6,7 @@
 import org.bukkit.event.HandlerList;
 
 import java.util.UUID;
+import org.jspecify.annotations.NonNull;
 
 /**
  * Event called when a home is deleted.
@@ -44,7 +45,7 @@ public void setCancelled(boolean cancel) {
     }
 
     @Override
-    public HandlerList getHandlers() {
+    public @NonNull HandlerList getHandlers() {
         return HANDLER_LIST;
     }
 

eternalcore-api/src/main/java/com/eternalcode/core/feature/home/event/HomeLimitReachedEvent.java

@@ -4,6 +4,7 @@
 import org.bukkit.event.HandlerList;
 
 import java.util.UUID;
+import org.jspecify.annotations.NonNull;
 
 /**
  * Event called when a player tries to create a home but has reached the limit.
@@ -37,7 +38,7 @@ public int getLimitAmount() {
     }
 
     @Override
-    public HandlerList getHandlers() {
+    public @NonNull HandlerList getHandlers() {
         return HANDLER_LIST;
     }