From 99a07a2ba64f89fa061749a448fab0bb29cd4ac4 Mon Sep 17 00:00:00 2001 From: Marc Baloup Date: Thu, 11 Aug 2022 01:32:37 +0200 Subject: [PATCH] Javadoc and some API changes --- .../commands/BungeeBrigadierCommand.java | 2 +- .../main/java/fr/pandacube/lib/cli/CLI.java | 68 ++++------ .../lib/cli/commands/CLIBrigadierCommand.java | 34 ++--- .../cli/commands/CLIBrigadierDispatcher.java | 22 +++- .../fr/pandacube/lib/cli/log/CLILogger.java | 10 +- .../lib/commands/BrigadierDispatcher.java | 4 +- .../paper/commands/PaperBrigadierCommand.java | 2 +- pandalib-paper/pom.xml | 2 - .../pandacube/lib/paper/gui/GUIInventory.java | 122 +++++++++++------- .../paper/scheduler/AutoUpdatedObject.java | 64 --------- .../lib/paper/scheduler/PandalibRunnable.java | 104 +++++++++++++++ .../lib/paper/scheduler/SchedulerUtil.java | 39 +++++- .../lib/paper/util/ItemStackBuilder.java | 13 +- 13 files changed, 298 insertions(+), 188 deletions(-) delete mode 100644 pandalib-paper/src/main/java/fr/pandacube/lib/paper/scheduler/AutoUpdatedObject.java create mode 100644 pandalib-paper/src/main/java/fr/pandacube/lib/paper/scheduler/PandalibRunnable.java diff --git a/pandalib-bungee-commands/src/main/java/fr/pandacube/lib/bungee/commands/BungeeBrigadierCommand.java b/pandalib-bungee-commands/src/main/java/fr/pandacube/lib/bungee/commands/BungeeBrigadierCommand.java index 0da035e..fcb1f04 100644 --- a/pandalib-bungee-commands/src/main/java/fr/pandacube/lib/bungee/commands/BungeeBrigadierCommand.java +++ b/pandalib-bungee-commands/src/main/java/fr/pandacube/lib/bungee/commands/BungeeBrigadierCommand.java @@ -31,7 +31,7 @@ public abstract class BungeeBrigadierCommand extends BrigadierCommand CLIBrigadierDispatcher.instance.execute(cmdLine), "CLICmdThread #"+(i++)).start(); - } } catch (IOException e) { Log.severe(e); diff --git a/pandalib-cli/src/main/java/fr/pandacube/lib/cli/commands/CLIBrigadierCommand.java b/pandalib-cli/src/main/java/fr/pandacube/lib/cli/commands/CLIBrigadierCommand.java index ec7ce22..c3041a7 100644 --- a/pandalib-cli/src/main/java/fr/pandacube/lib/cli/commands/CLIBrigadierCommand.java +++ b/pandalib-cli/src/main/java/fr/pandacube/lib/cli/commands/CLIBrigadierCommand.java @@ -1,25 +1,22 @@ package fr.pandacube.lib.cli.commands; -import java.util.Arrays; -import java.util.List; +import com.mojang.brigadier.builder.LiteralArgumentBuilder; +import com.mojang.brigadier.suggestion.SuggestionProvider; +import com.mojang.brigadier.tree.LiteralCommandNode; +import fr.pandacube.lib.commands.BrigadierCommand; +import fr.pandacube.lib.commands.SuggestionsSupplier; + import java.util.function.Function; import java.util.function.Predicate; -import com.mojang.brigadier.arguments.ArgumentType; -import com.mojang.brigadier.builder.LiteralArgumentBuilder; -import com.mojang.brigadier.builder.RequiredArgumentBuilder; -import com.mojang.brigadier.context.CommandContext; -import com.mojang.brigadier.context.ParsedCommandNode; -import com.mojang.brigadier.suggestion.SuggestionProvider; -import com.mojang.brigadier.tree.LiteralCommandNode; - -import fr.pandacube.lib.commands.BrigadierCommand; -import fr.pandacube.lib.commands.BrigadierSuggestionsUtil; -import fr.pandacube.lib.commands.SuggestionsSupplier; -import fr.pandacube.lib.util.Log; - +/** + * Abstract class that holds the logic of a specific command to be registered in {@link CLIBrigadierDispatcher}. + */ public abstract class CLIBrigadierCommand extends BrigadierCommand { + /** + * Instanciate this command instance. + */ public CLIBrigadierCommand() { LiteralCommandNode commandNode = buildCommand().build(); postBuildCommand(commandNode); @@ -28,7 +25,7 @@ public abstract class CLIBrigadierCommand extends BrigadierCommand { aliases = new String[0]; CLIBrigadierDispatcher.instance.register(commandNode); - + for (String alias : aliases) { CLIBrigadierDispatcher.instance.register(literal(alias) @@ -66,6 +63,11 @@ public abstract class CLIBrigadierCommand extends BrigadierCommand { + /** + * Wraps the provided {@link SuggestionsSupplier} into a Brigadier’s {@link SuggestionProvider}. + * @param suggestions the suggestions to wrap. + * @return a {@link SuggestionProvider} generating the suggestions from the provided {@link SuggestionsSupplier}. + */ protected SuggestionProvider wrapSuggestions(SuggestionsSupplier suggestions) { return wrapSuggestions(suggestions, Function.identity()); } diff --git a/pandalib-cli/src/main/java/fr/pandacube/lib/cli/commands/CLIBrigadierDispatcher.java b/pandalib-cli/src/main/java/fr/pandacube/lib/cli/commands/CLIBrigadierDispatcher.java index a49e347..78acb49 100644 --- a/pandalib-cli/src/main/java/fr/pandacube/lib/cli/commands/CLIBrigadierDispatcher.java +++ b/pandalib-cli/src/main/java/fr/pandacube/lib/cli/commands/CLIBrigadierDispatcher.java @@ -11,14 +11,25 @@ import fr.pandacube.lib.util.Log; import jline.console.completer.Completer; import net.kyori.adventure.text.ComponentLike; +/** + * Implementation of {@link BrigadierDispatcher} that integrates the commands into the JLine CLI interface. + */ public class CLIBrigadierDispatcher extends BrigadierDispatcher implements Completer { - + + /** + * The instance of {@link CLIBrigadierDispatcher}. + */ public static final CLIBrigadierDispatcher instance = new CLIBrigadierDispatcher(); private static final Object sender = new Object(); - + + /** + * Executes the provided command. + * @param commandWithoutSlash the command, without the eventual slash at the begining. + * @return the value returned by the executed command. + */ public int execute(String commandWithoutSlash) { return execute(sender, commandWithoutSlash); } @@ -37,7 +48,12 @@ public class CLIBrigadierDispatcher extends BrigadierDispatcher implemen return completeResult.getRange().getStart(); } - + + /** + * Gets the suggestions for the currently being typed command. + * @param buffer the command that is being typed. + * @return the suggestions for the currently being typed command. + */ public Suggestions getSuggestions(String buffer) { return getSuggestions(sender, buffer); } diff --git a/pandalib-cli/src/main/java/fr/pandacube/lib/cli/log/CLILogger.java b/pandalib-cli/src/main/java/fr/pandacube/lib/cli/log/CLILogger.java index f2e16a3..f5e76ea 100644 --- a/pandalib-cli/src/main/java/fr/pandacube/lib/cli/log/CLILogger.java +++ b/pandalib-cli/src/main/java/fr/pandacube/lib/cli/log/CLILogger.java @@ -11,10 +11,18 @@ import net.md_5.bungee.log.ColouredWriter; import net.md_5.bungee.log.ConciseFormatter; import net.md_5.bungee.log.LoggingOutputStream; +/** + * Initializer for the logging system of a CLI application. + */ public class CLILogger { private static Logger logger = null; - + + /** + * Initialize and return the logger for this application. + * @param cli the CLI instance to use + * @return the logger of this application. + */ public static synchronized Logger getLogger(CLI cli) { if (logger == null) { logger = Logger.getGlobal(); diff --git a/pandalib-commands/src/main/java/fr/pandacube/lib/commands/BrigadierDispatcher.java b/pandalib-commands/src/main/java/fr/pandacube/lib/commands/BrigadierDispatcher.java index 34d1827..0692f59 100644 --- a/pandalib-commands/src/main/java/fr/pandacube/lib/commands/BrigadierDispatcher.java +++ b/pandalib-commands/src/main/java/fr/pandacube/lib/commands/BrigadierDispatcher.java @@ -63,10 +63,10 @@ public abstract class BrigadierDispatcher { /** - * Gets the suggestions for the currenlty being typed command. + * Gets the suggestions for the currently being typed command. * @param sender the command sender. * @param buffer the command that is being typed. - * @return the suggestions for the currenlty being typed command. + * @return the suggestions for the currently being typed command. */ public Suggestions getSuggestions(S sender, String buffer) { ParseResults parsed = dispatcher.parse(buffer, sender); diff --git a/pandalib-paper-commands/src/main/java/fr/pandacube/lib/paper/commands/PaperBrigadierCommand.java b/pandalib-paper-commands/src/main/java/fr/pandacube/lib/paper/commands/PaperBrigadierCommand.java index 6bd378a..bba74aa 100644 --- a/pandalib-paper-commands/src/main/java/fr/pandacube/lib/paper/commands/PaperBrigadierCommand.java +++ b/pandalib-paper-commands/src/main/java/fr/pandacube/lib/paper/commands/PaperBrigadierCommand.java @@ -129,7 +129,7 @@ public abstract class PaperBrigadierCommand extends BrigadierCommand registeredAliases; /** - * Instanciate this command isntance. + * Instanciate this command instance. * * @param pl the plugin instance. * @param regPolicy the registration policy for this command. diff --git a/pandalib-paper/pom.xml b/pandalib-paper/pom.xml index ac5038e..435b59b 100644 --- a/pandalib-paper/pom.xml +++ b/pandalib-paper/pom.xml @@ -58,13 +58,11 @@ io.papermc.paper paper-api ${paper.version}-SNAPSHOT - provided io.papermc.paper paper-mojangapi ${paper.version}-SNAPSHOT - provided diff --git a/pandalib-paper/src/main/java/fr/pandacube/lib/paper/gui/GUIInventory.java b/pandalib-paper/src/main/java/fr/pandacube/lib/paper/gui/GUIInventory.java index 8ec165f..f3b507d 100644 --- a/pandalib-paper/src/main/java/fr/pandacube/lib/paper/gui/GUIInventory.java +++ b/pandalib-paper/src/main/java/fr/pandacube/lib/paper/gui/GUIInventory.java @@ -7,6 +7,7 @@ import java.util.Map.Entry; import java.util.function.Consumer; import com.google.common.collect.ImmutableMap; +import fr.pandacube.lib.paper.PandaLibPaper; import org.bukkit.Bukkit; import org.bukkit.Material; import org.bukkit.enchantments.Enchantment; @@ -18,13 +19,19 @@ import org.bukkit.event.inventory.InventoryClickEvent; import org.bukkit.event.inventory.InventoryCloseEvent; import org.bukkit.inventory.Inventory; import org.bukkit.inventory.ItemStack; -import org.bukkit.plugin.Plugin; import fr.pandacube.lib.chat.Chat; import fr.pandacube.lib.paper.util.ItemStackBuilder; +/** + * An inventory based GUI. + */ public class GUIInventory implements Listener { - + + /** + * Used as parameter of {@link #buildButton(ItemStack, Integer, Chat, List, Map)} to indicate that a button should + * shine like an enchanted object, without showing enchant informations in the hover text. + */ public static final Map FAKE_ENCHANT = ImmutableMap.of(Enchantment.DURABILITY, 1); private final Player player; @@ -33,8 +40,14 @@ public class GUIInventory implements Listener { private boolean isOpened = false; private final Map> onClickEvents; - public GUIInventory(Player p, int nbLines, Chat title, Consumer closeEventAction, - Plugin pl) { + /** + * Create a new inventory based GUI. + * @param p the player for which to create the GUI. + * @param nbLines the number of invotory lines for the interface. + * @param title the title of the GUI (title of the inventory) + * @param closeEventAction the action to perform when the player closes the GUI inventory + */ + public GUIInventory(Player p, int nbLines, Chat title, Consumer closeEventAction) { if (title == null) inv = Bukkit.createInventory(null, nbLines * 9); else @@ -46,7 +59,7 @@ public class GUIInventory implements Listener { player = p; - Bukkit.getPluginManager().registerEvents(this, pl); + Bukkit.getPluginManager().registerEvents(this, PandaLibPaper.getPlugin()); } @@ -55,9 +68,11 @@ public class GUIInventory implements Listener { } /** - * @param clickEventActions (l'event passé en paramètre de la méthode done a - * été pré-annulée. Pour la rétablir, faites un - * event.setCancelled(false)). + * Set a button on the provided slot, if this slot is still empty. + * @param p the slot index. + * @param iStack the item to put in the slot. + * @param clickEventActions the action to perform when the user clicks that button. The event passed as a parameter + * is already cancelled. It is possible to uncancel it if needed. */ public void setButtonIfEmpty(int p, ItemStack iStack, Consumer clickEventActions) { if (inv.getItem(p) == null) @@ -65,9 +80,11 @@ public class GUIInventory implements Listener { } /** - * @param clickEventActions (l'event passé en paramètre de la méthode done a - * été pré-annulée. Pour la rétablir, faites un - * event.setCancelled(false)). + * Set a button on the provided slot. + * @param p the slot index. + * @param iStack the item to put in the slot. + * @param clickEventActions the action to perform when the user clicks that button. The event passed as a parameter + * is already cancelled. It is possible to uncancel it if needed. */ public void setButton(int p, ItemStack iStack, Consumer clickEventActions) { inv.setItem(p, iStack); @@ -75,38 +92,63 @@ public class GUIInventory implements Listener { } /** - * @param clickEventActions (l'event passé en paramètre de la méthode done a - * été pré-annulée. Pour la rétablir, faites un - * event.setCancelled(false)). + * Update/replace the action to perform for a specific slot. + * @param p the slot index. + * @param clickEventActions the action to perform when the user clicks that button. The event passed as a parameter + * is already cancelled. It is possible to uncancel it if needed. */ public void changeClickEventAction(int p, Consumer clickEventActions) { onClickEvents.put(p, clickEventActions); } + /** + * Returns the item that is in the provided slot. + * @param p the slot index. + * @return the item that is in the provided slot. + */ public ItemStack getItemStack(int p) { return inv.getItem(p); } + /** + * Makes the GUI inventory appears for the player. + */ public void open() { if (isOpened) return; player.openInventory(inv); isOpened = true; } - + + /** + * Force this GUI to be closes, without the intervention of the player. + * The bukkit API will call the {@link InventoryCloseEvent}, trigerring eventual actions associated with this event. + */ public void forceClose() { if (!isOpened) return; player.closeInventory(); // internally calls the InventoryCloseEvent } - + + /** + * Tells if this inventory is open for the player. + * @return true if this inventory is open for the player, false otherwise. + */ public boolean isOpen() { return isOpened; } + /** + * Clears the content of the GUI and the click event actions. + */ public void clear() { onClickEvents.clear(); inv.clear(); } + /** + * Clears a part of the GUI and the click event actions. + * @param firstElement the first element to remove. + * @param nbElement the number of element to remove. + */ public void clear(int firstElement, int nbElement) { for (int i = firstElement; i < firstElement + nbElement; i++) { inv.setItem(i, null); @@ -114,10 +156,18 @@ public class GUIInventory implements Listener { } } + /** + * Gets the underlying inventory of this GUI. + * @return the underlying inventory of this GUI. + */ public Inventory getInventory() { return inv; } + /** + * Inventory click event handler. + * @param event the event. + */ @EventHandler public void onInventoryClick(InventoryClickEvent event) { if (!event.getWhoClicked().equals(player)) return; @@ -135,6 +185,10 @@ public class GUIInventory implements Listener { } + /** + * Inventory close event handler. + * @param event the event. + */ @EventHandler public void onInventoryClose(InventoryCloseEvent event) { if (!event.getPlayer().equals(player)) return; @@ -183,9 +237,6 @@ public class GUIInventory implements Listener { public static ItemStack buildButton(ItemStack base, Chat displayName, List lores, Map enchantments) { return buildButton(base, null, displayName, lores, enchantments); } - public static ItemStack buildButton(ItemStack base, Integer amount, Chat displayName, Map enchantments) { - return buildButton(base, amount, displayName, null, enchantments); - } public static ItemStack buildButton(ItemStack base, Chat displayName, Map enchantments) { return buildButton(base, null, displayName, null, enchantments); } @@ -195,45 +246,22 @@ public class GUIInventory implements Listener { public static ItemStack buildButton(ItemStack base, Chat displayName, List lores) { return buildButton(base, null, displayName, lores, null); } - public static ItemStack buildButton(ItemStack base, Integer amount, Chat displayName) { - return buildButton(base, amount, displayName, null, null); - } public static ItemStack buildButton(ItemStack base, Chat displayName) { return buildButton(base, null, displayName, null, null); } - public static ItemStack buildButton(ItemStack base, Integer amount) { - return buildButton(base, amount, null, null, null); - } - - - - public static ItemStack buildButton(Material m, int amount, Chat displayName, List lores, Map enchantments) { - return buildButton(new ItemStack(m, amount), displayName, lores, enchantments); - } + public static ItemStack buildButton(Material m, Chat displayName, List lores, Map enchantments) { - return buildButton(m, 1, displayName, lores, enchantments); - } - public static ItemStack buildButton(Material m, int amount, Chat displayName, Map enchantments) { - return buildButton(m, amount, displayName, null, enchantments); + return buildButton(new ItemStack(m), null, displayName, lores, enchantments); } public static ItemStack buildButton(Material m, Chat displayName, Map enchantments) { - return buildButton(m, 1, displayName, null, enchantments); - } - public static ItemStack buildButton(Material m, int amount, Chat displayName, List lores) { - return buildButton(m, amount, displayName, lores, null); + return buildButton(new ItemStack(m), null, displayName, null, enchantments); } public static ItemStack buildButton(Material m, Chat displayName, List lores) { - return buildButton(m, 1, displayName, lores, null); - } - public static ItemStack buildButton(Material m, int amount, Chat displayName) { - return buildButton(m, amount, displayName, null, null); + return buildButton(new ItemStack(m), null, displayName, lores, null); } public static ItemStack buildButton(Material m, Chat displayName) { - return buildButton(m, 1, displayName, null, null); - } - public static ItemStack buildButton(Material m, int amount) { - return buildButton(m, amount, null, null, null); + return buildButton(new ItemStack(m), null, displayName, null, null); } diff --git a/pandalib-paper/src/main/java/fr/pandacube/lib/paper/scheduler/AutoUpdatedObject.java b/pandalib-paper/src/main/java/fr/pandacube/lib/paper/scheduler/AutoUpdatedObject.java deleted file mode 100644 index d8e492c..0000000 --- a/pandalib-paper/src/main/java/fr/pandacube/lib/paper/scheduler/AutoUpdatedObject.java +++ /dev/null @@ -1,64 +0,0 @@ -package fr.pandacube.lib.paper.scheduler; - -import java.util.ArrayList; -import java.util.List; -import java.util.Objects; - -import org.bukkit.Bukkit; -import org.bukkit.plugin.Plugin; -import org.bukkit.scheduler.BukkitTask; - -import fr.pandacube.lib.paper.PandaLibPaper; - -public class AutoUpdatedObject { - private static final Plugin plugin = PandaLibPaper.getPlugin(); - - private Runnable updater; - - private final List tasks = new ArrayList<>(); - - - protected AutoUpdatedObject() { } - public AutoUpdatedObject(Runnable updater) { - this.updater = Objects.requireNonNull(updater); - } - - public synchronized void updateSync() { - tasks.add(Bukkit.getScheduler().runTask(plugin, this::update)); - } - - public synchronized void updateAsync() { - tasks.add(Bukkit.getScheduler().runTaskAsynchronously(plugin, this::update)); - } - - public synchronized void updateLater(long delay) - throws IllegalArgumentException, IllegalStateException { - tasks.add(Bukkit.getScheduler().runTaskLater(plugin, this::update, delay)); - } - - public synchronized void updateLaterAsync(long delay) - throws IllegalArgumentException, IllegalStateException { - tasks.add(Bukkit.getScheduler().runTaskLaterAsynchronously(plugin, this::update, delay)); - } - - public synchronized void updateTimer(long delay, long period) - throws IllegalArgumentException, IllegalStateException { - tasks.add(Bukkit.getScheduler().runTaskTimer(plugin, this::update, delay, period)); - } - - public synchronized void updateTimerAsync(long delay, long period) - throws IllegalArgumentException, IllegalStateException { - tasks.add(Bukkit.getScheduler().runTaskTimerAsynchronously(plugin, this::update, delay, period)); - } - - public synchronized void cancel() { - tasks.forEach(BukkitTask::cancel); - tasks.clear(); - } - - public void update() { - Objects.requireNonNull(updater, "Please use new AutoUpdatedObject(Runnable) or override the run method."); - updater.run(); - } - -} diff --git a/pandalib-paper/src/main/java/fr/pandacube/lib/paper/scheduler/PandalibRunnable.java b/pandalib-paper/src/main/java/fr/pandacube/lib/paper/scheduler/PandalibRunnable.java new file mode 100644 index 0000000..729c8bc --- /dev/null +++ b/pandalib-paper/src/main/java/fr/pandacube/lib/paper/scheduler/PandalibRunnable.java @@ -0,0 +1,104 @@ +package fr.pandacube.lib.paper.scheduler; + +import java.util.ArrayList; +import java.util.List; +import java.util.Objects; + +import org.bukkit.Bukkit; +import org.bukkit.plugin.Plugin; +import org.bukkit.scheduler.BukkitRunnable; +import org.bukkit.scheduler.BukkitTask; + +import fr.pandacube.lib.paper.PandaLibPaper; + +/** + * An extension of {@link BukkitRunnable} that already integrates a reference to the Bukkit plugin. + */ +public class PandalibRunnable extends BukkitRunnable { + private static final Plugin plugin = PandaLibPaper.getPlugin(); + + private Runnable updater; + + + /** + * Instanciate a {@link PandalibRunnable}, whose {@link #run()} method will be called by the server scheduler. + * When using this default constructor, the {@link #run()} method must be override to provides code to run. + */ + protected PandalibRunnable() { } + + /** + * Instanciate a {@link PandalibRunnable}, with an {@code updater} that will be called by the server scheduler. + * @param updater the updater to run when this task is executed. + */ + public PandalibRunnable(Runnable updater) { + this.updater = Objects.requireNonNull(updater); + } + + + /** + * Same as {@link #runTask(Plugin)}, but the plugin instance is already provided by + * {@link PandaLibPaper#getPlugin()}. + * @return a {@link BukkitTask} that contains the id number. + */ + public synchronized BukkitTask runTask() { + return runTask(plugin); + } + + /** + * Same as {@link #runTaskAsynchronously(Plugin)}, but the plugin instance is already provided by + * {@link PandaLibPaper#getPlugin()}. + * @return a {@link BukkitTask} that contains the id number. + */ + public synchronized BukkitTask runTaskAsynchronously() { + return runTaskAsynchronously(plugin); + } + + /** + * Same as {@link #runTaskLater(Plugin, long)}, but the plugin instance is already provided by + * {@link PandaLibPaper#getPlugin()}. + * @param delay the ticks to wait before running the task. + * @return a {@link BukkitTask} that contains the id number. + */ + public synchronized BukkitTask runTaskLater(long delay) { + return runTaskLater(plugin, delay); + } + + /** + * Same as {@link #runTaskLaterAsynchronously(Plugin, long)}, but the plugin instance is already provided by + * {@link PandaLibPaper#getPlugin()}. + * @param delay the ticks to wait before running the task. + * @return a {@link BukkitTask} that contains the id number. + */ + public synchronized BukkitTask runTaskLaterAsynchronously(long delay) { + return runTaskLaterAsynchronously(plugin, delay); + } + + /** + * Same as {@link #runTaskTimer(Plugin, long, long)}, but the plugin instance is already provided by + * {@link PandaLibPaper#getPlugin()}. + * @param delay the ticks to wait before running the task. + * @param period the ticks to wait between runs. + * @return a {@link BukkitTask} that contains the id number. + */ + public synchronized BukkitTask runTaskTimer(long delay, long period) { + return runTaskTimer(plugin, delay, period); + } + + /** + * Same as {@link #runTaskTimerAsynchronously(Plugin, long, long)}, but the plugin instance is already provided by + * {@link PandaLibPaper#getPlugin()}. + * @param delay the ticks to wait before running the task. + * @param period the ticks to wait between runs. + * @return a {@link BukkitTask} that contains the id number. + */ + public synchronized BukkitTask runTaskTimerAsynchronously(long delay, long period) { + return runTaskTimerAsynchronously(plugin, delay, period); + } + + @Override + public void run() { + Objects.requireNonNull(updater, "Please use new PandalibRunnable(Runnable) or override the run method.") + .run(); + } + +} diff --git a/pandalib-paper/src/main/java/fr/pandacube/lib/paper/scheduler/SchedulerUtil.java b/pandalib-paper/src/main/java/fr/pandacube/lib/paper/scheduler/SchedulerUtil.java index 4a806d0..7a7ae87 100644 --- a/pandalib-paper/src/main/java/fr/pandacube/lib/paper/scheduler/SchedulerUtil.java +++ b/pandalib-paper/src/main/java/fr/pandacube/lib/paper/scheduler/SchedulerUtil.java @@ -1,21 +1,45 @@ package fr.pandacube.lib.paper.scheduler; import java.util.concurrent.Callable; +import java.util.concurrent.CancellationException; +import java.util.concurrent.ExecutionException; import org.bukkit.Bukkit; import fr.pandacube.lib.util.Log; import fr.pandacube.lib.paper.PandaLibPaper; +/** + * Provides methods to easily manage synchronous and asynchronous operations with the server thread. + */ public class SchedulerUtil { - + + /** + * Ensure that the provided runnable is run on the server thread. + * If the current thread is the server thread, then the task is run right now, then this method returns. + * If the current thread is another thread, it passes over the runnable to the Bukkit scheduler, then returns + * imediately. + * @param task the task to run on the main thread. + */ public static void runOnServerThread(Runnable task) { if (Bukkit.isPrimaryThread()) task.run(); Bukkit.getScheduler().runTask(PandaLibPaper.getPlugin(), task); } - + + /** + * Runs the provided task on the main thread, and wait for this task to end to return its value. + * If the current thread is the server thread, then the task is run right now, then this method returns with the + * return value of the provided task. Otherwise, it will wait for the task to run on the main thread, to be able to + * return the value from the task. + * @param task the task to run on the main thread and to get the value from. + * @return the value returned by the task. + * @param the type fo the return value of the task + * @throws CancellationException – if the task was cancelled + * @throws ExecutionException – if the task threw an exception + * @throws InterruptedException – if the current thread was interrupted while waiting + */ public static T runOnServerThreadAndWait(Callable task) throws Exception { if (Bukkit.isPrimaryThread()) return task.call(); @@ -29,7 +53,16 @@ public class SchedulerUtil { } }).get(); } - + + /** + * Runs the provided task on the main thread, and wait for this task to end to return. + * If the current thread is the server thread, then the task is run right now, then this method returns. + * Otherwise, it will wait for the task to finish on the main thread. + * @param task the task to run on the main thread. + * @throws CancellationException – if the task was cancelled + * @throws ExecutionException – if the task threw an exception + * @throws InterruptedException – if the current thread was interrupted while waiting + */ public static void runOnServerThreadAndWait(Runnable task) throws Exception { runOnServerThreadAndWait((Callable)() -> { task.run(); diff --git a/pandalib-paper/src/main/java/fr/pandacube/lib/paper/util/ItemStackBuilder.java b/pandalib-paper/src/main/java/fr/pandacube/lib/paper/util/ItemStackBuilder.java index 4b425e8..be01e36 100644 --- a/pandalib-paper/src/main/java/fr/pandacube/lib/paper/util/ItemStackBuilder.java +++ b/pandalib-paper/src/main/java/fr/pandacube/lib/paper/util/ItemStackBuilder.java @@ -24,10 +24,9 @@ public class ItemStackBuilder { /** * Create a builder with a clone of the provided ItemStack. - * + *

* The returned builder will not alter the provided ItemStack. - * IF you want to modify the ItemStack with the builder, please use {@link #wrap(ItemStack)}. - * + * If you want to modify the ItemStack with the builder, please use {@link #wrap(ItemStack)}. * @param base the original ItemStack. * @return the builder */ @@ -37,7 +36,6 @@ public class ItemStackBuilder { /** * Create a builder of a new ItemStack with the specified Material. - * * @param mat the material of the new builded ItemStack * @return the builder */ @@ -47,11 +45,12 @@ public class ItemStackBuilder { /** * Create a builder that will alter the data of the provided ItemStack. - * - * The {@link #build()} method of thez returned builder will return the same instance + *

+ * The {@link #build()} method of the returned builder will return the same instance * of ItemStack as the parameter of this method. - * + *

* To create a builder that doesn’t modify the provided ItemStack, use {@link #of(ItemStack)}. + * @param stack the wrapped itemstack. * @return the builder */ public static ItemStackBuilder wrap(ItemStack stack) {