Merge pull request #83 from Craftinators/hooks

Abstraction and Documentation of `/hooks` directory

common/src/main/java/com/hibiscusmc/hmccosmetics/cosmetic/Cosmetics.java

@@ -8,6 +8,7 @@ import com.hibiscusmc.hmccosmetics.util.MessagesUtil;
 import org.apache.commons.lang3.EnumUtils;
 import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 import org.spongepowered.configurate.CommentedConfigurationNode;
 import org.spongepowered.configurate.ConfigurateException;
 import org.spongepowered.configurate.ConfigurationNode;
@@ -33,6 +34,7 @@ public class Cosmetics {
         COSMETICS.remove(cosmetic);
     }
 
+    @Nullable
     public static Cosmetic getCosmetic(String id) {
         return COSMETICS.get(id);
     }

common/src/main/java/com/hibiscusmc/hmccosmetics/hooks/Hook.java

@@ -2,45 +2,92 @@ package com.hibiscusmc.hmccosmetics.hooks;
 
 import org.bukkit.event.Listener;
 import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
-public class Hook implements Listener {
-
+/**
+ * Represents a hook into other minecraft plugins
+ */
+public abstract class Hook implements Listener {
     private final String id;
-    private boolean active;
-    private boolean itemHook;
+    private boolean active = false;
+    private boolean itemHook = false;
 
-    public Hook(String id) {
+    public Hook(@NotNull String id) {
         this.id = id;
-        active = false;
         Hooks.addHook(this);
     }
 
-    public void load() {
-        // Override
-    }
+    /**
+     * Loads this hook
+     *
+     * @implNote By default, this method does nothing. It should be overridden by child classes to implement any necessary loading logic
+     */
+    public void load() { }
 
-    public ItemStack getItem(String itemId) {
+    /**
+     * Gets an {@link ItemStack} that is associated with the provided id from the hooked plugin
+     * @param itemId The id of the {@link ItemStack}
+     * @return The {@link ItemStack} with the id provided. If an invalid id was provided or if the hook doesn't have any related {@link ItemStack}s then this will return null
+     * @implNote By default, this method returns null. It should be overridden by child classes if you will to have your hook return a related {@link ItemStack}
+     */
+    @Nullable
+    public ItemStack getItem(@NotNull String itemId) {
         return null;
-        // Override
     }
 
-    public String getId() {
+    /**
+     * Gets the id of this hook
+     *
+     * @return The unique id for this hook
+     */
+    @NotNull
+    public final String getId() {
         return id;
     }
 
-    public void setActive(boolean active) {
-        this.active = active;
-    }
-
+    /**
+     * Gets whether this hook has been activated
+     * @return true if this hook is active, false otherwise
+     * @deprecated As of release 2.2.5+, replaced by {@link #isActive()}
+     */
+    @Deprecated
     public boolean getActive() {
         return this.active;
     }
 
-    public void setEnabledItemHook(boolean enabled) {
-        itemHook = enabled;
+    /**
+     * Gets whether this hook has been activated
+     * @return true if this hook is active, false otherwise
+     * @since 2.2.5
+     */
+    public final boolean isActive() {
+        return this.active;
     }
 
-    public boolean hasEnabledItemHook() {
+    /**
+     * Sets whether this hook is active
+     * @param active true to activate the hook, false otherwise
+     */
+    public final void setActive(boolean active) {
+        this.active = active;
+    }
+
+    /**
+     * Whether the method {@link #getItem(String)} should return a non-null value
+     * @return true if {@link #getItem(String)} should return a non-null value, false otherwise
+     *
+     * @apiNote Even though this method returns true does not mean that {@link #getItem(String)} won't return null, rather if this returns false then {@link #getItem(String)} should return false everytime
+     */
+    public final boolean hasEnabledItemHook() {
         return itemHook;
     }
+
+    /**
+     * Sets whether the method {@link #getItem(String)} should return a non-null value
+     * @param enabled true if {@link #getItem(String)} should return a non-null value, false otherwise
+     */
+    public final void setEnabledItemHook(boolean enabled) {
+        itemHook = enabled;
+    }
 }

common/src/main/java/com/hibiscusmc/hmccosmetics/hooks/Hooks.java

@@ -67,13 +67,13 @@ public class Hooks {
         if (!isItemHook(split[0])) return null;
         Hook hook = getHook(split[0]);
         if (!hook.hasEnabledItemHook()) return null;
-        if (!hook.getActive()) return null;
+        if (!hook.isActive()) return null;
         return hook.getItem(split[1]);
     }
 
     public static boolean isActiveHook(String id) {
         Hook hook = getHook(id);
         if (hook == null) return false;
-        return hook.getActive();
+        return hook.isActive();
     }
 }

common/src/main/java/com/hibiscusmc/hmccosmetics/hooks/items/HookHMCCosmetics.java

@@ -3,18 +3,23 @@ package com.hibiscusmc.hmccosmetics.hooks.items;
 import com.hibiscusmc.hmccosmetics.cosmetic.Cosmetic;
 import com.hibiscusmc.hmccosmetics.cosmetic.Cosmetics;
 import com.hibiscusmc.hmccosmetics.hooks.Hook;
-import org.bukkit.event.Listener;
 import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.NotNull;
 
-public class HookHMCCosmetics extends Hook implements Listener {
-
+/**
+ * A hook that integrates the plugin {@link com.hibiscusmc.hmccosmetics.HMCCosmeticsPlugin HMCCosmetics} to provide cosmetic items
+ */
+public class HookHMCCosmetics extends Hook {
     public HookHMCCosmetics() {
         super("HMCCosmetics");
         setEnabledItemHook(true);
     }
 
+    /**
+     * Gets a cosmetic {@link ItemStack} that is associated with the provided id from the plugin {@link com.hibiscusmc.hmccosmetics.HMCCosmeticsPlugin HMCCosmetics}
+     */
     @Override
-    public ItemStack getItem(String itemId) {
+    public ItemStack getItem(@NotNull String itemId) {
         Cosmetic cosmetic = Cosmetics.getCosmetic(itemId);
         if (cosmetic == null) return null;
         return cosmetic.getItem();

common/src/main/java/com/hibiscusmc/hmccosmetics/hooks/items/HookItemAdder.java

@@ -7,11 +7,14 @@ import dev.lone.itemsadder.api.CustomStack;
 import dev.lone.itemsadder.api.Events.ItemsAdderLoadDataEvent;
 import org.bukkit.Material;
 import org.bukkit.event.EventHandler;
-import org.bukkit.event.Listener;
 import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.NotNull;
 
-public class HookItemAdder extends Hook implements Listener {
-
+/**
+ * A hook that integrates the plugin {@link dev.lone.itemsadder.api.ItemsAdder ItemsAdder} to provide custom items
+ */
+@SuppressWarnings("SpellCheckingInspection")
+public class HookItemAdder extends Hook {
     private boolean enabled = false;
 
     public HookItemAdder() {
@@ -19,8 +22,11 @@ public class HookItemAdder extends Hook implements Listener {
         setEnabledItemHook(true);
     }
 
+    /**
+     * Gets a cosmetic {@link ItemStack} that is associated with the provided id from the plugin {@link dev.lone.itemsadder.api.ItemsAdder ItemsAdder}
+     */
     @Override
-    public ItemStack getItem(String itemId) {
+    public ItemStack getItem(@NotNull String itemId) {
         if (enabled) {
             CustomStack stack = CustomStack.getInstance(itemId);
             if (stack == null) return null;
@@ -32,7 +38,8 @@ public class HookItemAdder extends Hook implements Listener {
 
     @EventHandler
     public void onItemAdderDataLoad(ItemsAdderLoadDataEvent event) {
-        if (enabled && !Settings.getItemsAdderReloadChange()) return; // Defaultly it will only run once at startup. If hook setting is enable
+        // By default, it will only run once at startup, if hook setting is enabled
+        if (enabled && !Settings.getItemsAdderReloadChange()) return;
         this.enabled = true;
         HMCCosmeticsPlugin.setup();
     }

common/src/main/java/com/hibiscusmc/hmccosmetics/hooks/items/HookLooty.java

@@ -3,18 +3,24 @@ package com.hibiscusmc.hmccosmetics.hooks.items;
 import com.hibiscusmc.hmccosmetics.hooks.Hook;
 import com.mineinabyss.geary.prefabs.PrefabKey;
 import com.mineinabyss.looty.LootyFactory;
-import org.bukkit.event.Listener;
 import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.NotNull;
 
-public class HookLooty extends Hook implements Listener {
-
+/**
+ * A hook that integrates the plugin {@link com.mineinabyss.looty.LootyPlugin Looty} to provide custom items
+ */
+@SuppressWarnings("SpellCheckingInspection")
+public class HookLooty extends Hook {
     public HookLooty() {
         super("looty");
         setEnabledItemHook(true);
     }
 
+    /**
+     * Gets a cosmetic {@link ItemStack} that is associated with the provided id from the plugin {@link com.mineinabyss.looty.LootyPlugin Looty}
+     */
     @Override
-    public ItemStack getItem(String itemId) {
+    public ItemStack getItem(@NotNull String itemId) {
         PrefabKey prefabKey = PrefabKey.Companion.ofOrNull(itemId);
         if (prefabKey == null) return null;
         return LootyFactory.INSTANCE.createFromPrefab(prefabKey);

common/src/main/java/com/hibiscusmc/hmccosmetics/hooks/items/HookMythic.java

@@ -2,17 +2,24 @@ package com.hibiscusmc.hmccosmetics.hooks.items;
 
 import com.hibiscusmc.hmccosmetics.hooks.Hook;
 import io.lumine.mythic.bukkit.MythicBukkit;
-import org.bukkit.event.Listener;
 import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.NotNull;
 
-public class HookMythic extends Hook implements Listener {
+/**
+ * A hook that integrates the plugin {@link io.lumine.mythic.bukkit.MythicBukkit MythicBukkit} to provide custom items
+ */
+@SuppressWarnings("SpellCheckingInspection")
+public class HookMythic extends Hook {
     public HookMythic() {
         super("mythicmobs");
         setEnabledItemHook(true);
     }
 
+    /**
+     * Gets a cosmetic {@link ItemStack} that is associated with the provided id from the plugin {@link io.lumine.mythic.bukkit.MythicBukkit MythicBukkit}
+     */
     @Override
-    public ItemStack getItem(String itemId) {
+    public ItemStack getItem(@NotNull String itemId) {
         return MythicBukkit.inst().getItemManager().getItemStack(itemId);
     }
 }

common/src/main/java/com/hibiscusmc/hmccosmetics/hooks/items/HookOraxen.java

@@ -3,18 +3,24 @@ package com.hibiscusmc.hmccosmetics.hooks.items;
 import com.hibiscusmc.hmccosmetics.hooks.Hook;
 import io.th0rgal.oraxen.api.OraxenItems;
 import io.th0rgal.oraxen.items.ItemBuilder;
-import org.bukkit.event.Listener;
 import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.NotNull;
 
-public class HookOraxen extends Hook implements Listener {
-
+/**
+ * A hook that integrates the plugin {@link io.th0rgal.oraxen.OraxenPlugin OraxenPlugin} to provide custom items
+ */
+@SuppressWarnings("SpellCheckingInspection")
+public class HookOraxen extends Hook {
     public HookOraxen() {
         super("oraxen");
         setEnabledItemHook(true);
     }
 
+    /**
+     * Gets a cosmetic {@link ItemStack} that is associated with the provided id from the plugin {@link io.th0rgal.oraxen.OraxenPlugin OraxenPlugin}
+     */
     @Override
-    public ItemStack getItem(String itemId) {
+    public ItemStack getItem(@NotNull String itemId) {
         ItemBuilder builder = OraxenItems.getItemById(itemId);
         if (builder == null) return null;
         return builder.build();

common/src/main/java/com/hibiscusmc/hmccosmetics/hooks/misc/HookCMI.java

@@ -7,11 +7,12 @@ import com.hibiscusmc.hmccosmetics.user.CosmeticUser;
 import com.hibiscusmc.hmccosmetics.user.CosmeticUsers;
 import org.bukkit.entity.Player;
 import org.bukkit.event.EventHandler;
-import org.bukkit.event.Listener;
 import org.jetbrains.annotations.NotNull;
 
-public class HookCMI extends Hook implements Listener {
-
+/**
+ * A hook that integrates the plugin {@link com.Zrips.CMI.CMI CMI}
+ */
+public class HookCMI extends Hook {
     public HookCMI() {
         super("CMI");
     }

common/src/main/java/com/hibiscusmc/hmccosmetics/hooks/misc/HookHMCColor.java

@@ -1,10 +1,11 @@
 package com.hibiscusmc.hmccosmetics.hooks.misc;
 
 import com.hibiscusmc.hmccosmetics.hooks.Hook;
-import org.bukkit.event.Listener;
-
-public class HookHMCColor extends Hook implements Listener {
 
+/**
+ * A hook that integrates the plugin {@link com.hibiscusmc.hmccolor.HMCColor HMCColor}
+ */
+public class HookHMCColor extends Hook {
     public HookHMCColor() {
         super("HMCColor");
     }

common/src/main/java/com/hibiscusmc/hmccosmetics/hooks/misc/HookPremiumVanish.java

@@ -7,13 +7,14 @@ import de.myzelyam.api.vanish.PlayerHideEvent;
 import de.myzelyam.api.vanish.PlayerShowEvent;
 import org.bukkit.entity.Player;
 import org.bukkit.event.EventHandler;
-import org.bukkit.event.Listener;
 import org.jetbrains.annotations.NotNull;
 
-public class HookPremiumVanish extends Hook implements Listener {
-
-    // NOTE: Supervanish and Premium Vanish both use the same api
-
+/**
+ * A hook that integrates the plugin {@link de.myzelyam.api.vanish.VanishAPI Supervanish}
+ *
+ * @implSpec Supervanish and Premium Vanish both use the same api
+ */
+public class HookPremiumVanish extends Hook {
     public HookPremiumVanish() {
         super("PremiumVanish");
     }
@@ -33,5 +34,4 @@ public class HookPremiumVanish extends Hook implements Listener {
         if (user == null) return;
         user.showCosmetics();
     }
-
 }

common/src/main/java/com/hibiscusmc/hmccosmetics/hooks/misc/HookSuperVanish.java

@@ -7,13 +7,14 @@ import de.myzelyam.api.vanish.PlayerHideEvent;
 import de.myzelyam.api.vanish.PlayerShowEvent;
 import org.bukkit.entity.Player;
 import org.bukkit.event.EventHandler;
-import org.bukkit.event.Listener;
 import org.jetbrains.annotations.NotNull;
 
-public class HookSuperVanish extends Hook implements Listener {
-
-    // NOTE: Supervanish and Premium Vanish both use the same api
-
+/**
+ * A hook that integrates the plugin {@link de.myzelyam.api.vanish.VanishAPI Supervanish}
+ *
+ * @implSpec Supervanish and Premium Vanish both use the same api
+ */
+public class HookSuperVanish extends Hook {
     public HookSuperVanish() {
         super("SuperVanish");
     }

common/src/main/java/com/hibiscusmc/hmccosmetics/hooks/placeholders/HMCPlaceholderExpansion.java

@@ -12,12 +12,15 @@ import org.bukkit.OfflinePlayer;
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.inventory.meta.ItemMeta;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 import java.util.Arrays;
 import java.util.List;
 
+/**
+ * A hook that integrates the plugin {@link me.clip.placeholderapi.PlaceholderAPIPlugin PlaceholderAPIPlugin}
+ */
 public class HMCPlaceholderExpansion extends PlaceholderExpansion {
-
     private static boolean papiEnabled = false;
 
     public HMCPlaceholderExpansion() {
@@ -73,7 +76,7 @@ public class HMCPlaceholderExpansion extends PlaceholderExpansion {
                     if (placeholderArgs.size() == 2) return user.getCosmetic(slot).getId();
                     switch (placeholderArgs.get(2).toLowerCase()) {
                         case "material" -> {
-                            return getMaterial(user.getCosmetic(slot));
+                            return getMaterialName(user.getCosmetic(slot));
                         }
                         case "custommodeldata" -> {
                             return getModelData(user.getCosmetic(slot));
@@ -135,33 +138,76 @@ public class HMCPlaceholderExpansion extends PlaceholderExpansion {
         return null;
     }
 
+    /**
+     * Gets the name of the cosmetic item {@link org.bukkit.Material Material}
+     * @param cosmetic The cosmetic to get its {@link org.bukkit.Material Material}s name
+     * @return The name of the cosmetic item {@link org.bukkit.Material Material}
+     * @deprecated As of release 2.2.5+, use {@link #getMaterialName(Cosmetic)} instead
+     */
+    @Deprecated
+    @Nullable
     public String getMaterial(@NotNull Cosmetic cosmetic) {
         ItemStack item = cosmetic.getItem();
         if (item == null) return null;
-        return cosmetic.getItem().getType().toString();
+        return item.getType().toString();
     }
 
+    /**
+     * Gets the name of the cosmetic item {@link org.bukkit.Material Material}
+     * @param cosmetic The cosmetic to get its {@link org.bukkit.Material Material}s name
+     * @return The name of the cosmetic item {@link org.bukkit.Material Material}
+     * @since 2.2.5
+     */
+    @Nullable
+    public String getMaterialName(@NotNull Cosmetic cosmetic) {
+        ItemStack item = cosmetic.getItem();
+        if (item == null) return null;
+        return item.getType().toString();
+    }
+
+    /**
+     * Gets the cosmetic items custom model data
+     * @param cosmetic The cosmetic to get its custom model data
+     * @return The cosmetic items custom model data
+     */
+    @Nullable
     public String getModelData(@NotNull Cosmetic cosmetic) {
         ItemStack item = cosmetic.getItem();
         if (item == null) return null;
         if (!item.hasItemMeta()) return null;
         ItemMeta itemMeta = item.getItemMeta();
+        if (itemMeta == null) return null;
         return String.valueOf(itemMeta.getCustomModelData());
     }
 
+    /**
+     * Gets the cosmetic items display name
+     * @param cosmetic The cosmetic to get its items display name
+     * @return The cosmetic items display name
+     */
+    @Nullable
     public String getItemName(@NotNull Cosmetic cosmetic) {
         ItemStack item = cosmetic.getItem();
         if (item == null) return null;
         if (!item.hasItemMeta()) return null;
         ItemMeta itemMeta = item.getItemMeta();
+        if (itemMeta == null) return null;
         return itemMeta.getDisplayName();
     }
 
+    /**
+     * Gets the cosmetic items lore
+     * @param cosmetic The cosmetic to get its items lore
+     * @return The cosmetic items lore
+     */
+    @Nullable
     public String getItemLore(@NotNull Cosmetic cosmetic) {
         ItemStack item = cosmetic.getItem();
         if (item == null) return null;
         if (item.hasItemMeta()) {
-            return String.valueOf(item.getItemMeta().getLore());
+            ItemMeta itemMeta = item.getItemMeta();
+            if (itemMeta == null) return null;
+            return String.valueOf(itemMeta.getLore());
         }
         return null;
     }

common/src/main/java/com/hibiscusmc/hmccosmetics/hooks/placeholders/HookPlaceholderAPI.java

@@ -2,14 +2,20 @@ package com.hibiscusmc.hmccosmetics.hooks.placeholders;
 
 import com.hibiscusmc.hmccosmetics.hooks.Hook;
 
+/**
+ * A hook that integrates the plugin {@link me.clip.placeholderapi.PlaceholderAPI PlaceholderAPI}
+ */
 public class HookPlaceholderAPI extends Hook {
-
     public HookPlaceholderAPI() {
         super("PlaceholderAPI");
     }
 
+    /**
+     * @throws RuntimeException If PlaceholderAPI fails to register
+     */
     @Override
-    public void load() {
-        new HMCPlaceholderExpansion().register();
+    public void load() throws RuntimeException {
+        if (!new HMCPlaceholderExpansion().register())
+            throw new RuntimeException("Failed to register PlaceholderExpansion");
     }
 }

common/src/main/java/com/hibiscusmc/hmccosmetics/hooks/worldguard/WGHook.java

@@ -9,9 +9,18 @@ import com.sk89q.worldguard.protection.flags.registry.FlagRegistry;
 
 import java.util.logging.Level;
 
+/**
+ * A hook that integrates the plugin {@link com.sk89q.worldguard.WorldGuard WorldGuard}
+ */
 public class WGHook {
-
+    /**
+     * @implNote Please use {@link #getCosmeticEnableFlag()} instead
+     */
     public static StateFlag COSMETIC_ENABLE_FLAG;
+
+    /**
+     * @implNote Please use {@link #getCosmeticWardrobeFlag()} instead
+     */
     public static StateFlag COSMETIC_WARDROBE_FLAG;
 
     public WGHook() {
@@ -35,10 +44,18 @@ public class WGHook {
         }
     }
 
+    /**
+     * Gets the cosmetic enable {@link StateFlag}
+     * @return The cosmetic enable {@link StateFlag}
+     */
     public static StateFlag getCosmeticEnableFlag() {
         return COSMETIC_ENABLE_FLAG;
     }
 
+    /**
+     * Gets the cosmetic wardrobe {@link StateFlag}
+     * @return The cosmetic wardrobe {@link StateFlag}
+     */
     public static StateFlag getCosmeticWardrobeFlag() {
         return COSMETIC_WARDROBE_FLAG;
     }

common/src/main/java/com/hibiscusmc/hmccosmetics/hooks/worldguard/WGListener.java

@@ -14,8 +14,10 @@ import org.bukkit.event.Listener;
 import org.bukkit.event.player.PlayerMoveEvent;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Contains {@link com.sk89q.worldguard.WorldGuard WorldGuard} related event listeners
+ */
 public class WGListener implements Listener {
-
     @EventHandler
     public void onPlayerMove(@NotNull PlayerMoveEvent event) {
         CosmeticUser user = CosmeticUsers.getUser(event.getPlayer());