From 62949948e1d55f7155b6858a8b554a7139747d72 Mon Sep 17 00:00:00 2001 From: Marc Baloup Date: Sun, 27 Aug 2023 17:28:12 +0200 Subject: [PATCH] Some more javadoc --- .../pandacube/lib/bungee/PandaLibBungee.java | 17 +++++++ .../lib/bungee/backup/BungeeBackupConfig.java | 21 +++++++++ .../bungee/backup/BungeeBackupManager.java | 18 +++++++- .../bungee/backup/BungeeWorkdirProcess.java | 9 +++- .../java/fr/pandacube/lib/chat/ChatUtil.java | 1 + .../fr/pandacube/lib/cli/CLIApplication.java | 45 ++++++++++++++++--- .../lib/cli/commands/CommandAdmin.java | 3 ++ .../lib/cli/commands/CommandStop.java | 2 +- .../lib/core/backup/BackupManager.java | 6 ++- .../core/mc_version/MinecraftVersionList.java | 13 ++++++ 10 files changed, 124 insertions(+), 11 deletions(-) diff --git a/pandalib-bungee/src/main/java/fr/pandacube/lib/bungee/PandaLibBungee.java b/pandalib-bungee/src/main/java/fr/pandacube/lib/bungee/PandaLibBungee.java index c58dd68..386ccbf 100644 --- a/pandalib-bungee/src/main/java/fr/pandacube/lib/bungee/PandaLibBungee.java +++ b/pandalib-bungee/src/main/java/fr/pandacube/lib/bungee/PandaLibBungee.java @@ -4,25 +4,42 @@ import fr.pandacube.lib.bungee.util.BungeeDailyLogRotateFileHandler; import fr.pandacube.lib.bungee.util.PluginMessagePassthrough; import net.md_5.bungee.api.plugin.Plugin; +/** + * General class used to initialize some tools of pandalib-bungee, following the bungee plugin's lifecycle. + */ public class PandaLibBungee { private static Plugin plugin; + /** + * Method to be called in {@link Plugin#onLoad()} method. + * @param plugin the plugin instance. + */ public static void onLoad(Plugin plugin) { PandaLibBungee.plugin = plugin; } + /** + * Method to be called in {@link Plugin#onEnable()} method. + */ public static void onEnable() { PluginMessagePassthrough.init(plugin); BungeeDailyLogRotateFileHandler.init(true); } + /** + * Method to be called in {@link Plugin#onDisable()} method. + */ public static void disable() { } + /** + * Returns the plugin instance. + * @return the plugin instance. + */ public static Plugin getPlugin() { return plugin; } diff --git a/pandalib-bungee/src/main/java/fr/pandacube/lib/bungee/backup/BungeeBackupConfig.java b/pandalib-bungee/src/main/java/fr/pandacube/lib/bungee/backup/BungeeBackupConfig.java index ed6861a..7def26a 100644 --- a/pandalib-bungee/src/main/java/fr/pandacube/lib/bungee/backup/BungeeBackupConfig.java +++ b/pandalib-bungee/src/main/java/fr/pandacube/lib/bungee/backup/BungeeBackupConfig.java @@ -6,12 +6,33 @@ import java.io.File; import java.util.ArrayList; import java.util.List; +/** + * Class that holds the configuration varables for {@link BungeeBackupManager}. + */ @SuppressWarnings("CanBeFinal") public class BungeeBackupConfig { + /** + * Tells if the working directory of the current bungee instance should be backed up. + */ public boolean workdirBackupEnabled = true; + /** + * Tells if the old logs of the current bungee instance should be backed up. + */ public boolean logsBackupEnabled = true; + /** + * The cron scheduling of when the workdir backup occurs. + */ public String scheduling = "0 2 * * *"; // cron format, here is every day at 2am + /** + * The destination directory for the backups. + */ public File backupDirectory = null; + /** + * The configuration handling the cleaning of the backup directory. + */ public BackupCleaner workdirBackupCleaner = BackupCleaner.KEEPING_1_EVERY_N_MONTH(3).merge(BackupCleaner.KEEPING_N_LAST(5)); + /** + * A list of ignored files or directory in the workdir to exclude from the backup. + */ public List workdirIgnoreList = new ArrayList<>(); } diff --git a/pandalib-bungee/src/main/java/fr/pandacube/lib/bungee/backup/BungeeBackupManager.java b/pandalib-bungee/src/main/java/fr/pandacube/lib/bungee/backup/BungeeBackupManager.java index 2108764..50ba2b1 100644 --- a/pandalib-bungee/src/main/java/fr/pandacube/lib/bungee/backup/BungeeBackupManager.java +++ b/pandalib-bungee/src/main/java/fr/pandacube/lib/bungee/backup/BungeeBackupManager.java @@ -6,10 +6,17 @@ import fr.pandacube.lib.core.backup.RotatedLogsBackupProcess; import java.io.File; +/** + * Handles the backup processes for a Bungeecord instance. + */ public class BungeeBackupManager extends BackupManager { BungeeBackupConfig config; - + + /** + * Instanciate a new {@link BungeeBackupManager}. + * @param config the configuration. + */ public BungeeBackupManager(BungeeBackupConfig config) { super(config.backupDirectory); setConfig(config); @@ -24,12 +31,19 @@ public class BungeeBackupManager extends BackupManager { super.addProcess(process); } + /** + * Sets a new configuration for this backup manager. + * @param config the new configuration. + */ public void setConfig(BungeeBackupConfig config) { this.config = config; backupQueue.forEach(this::updateProcessConfig); } - + /** + * Deploys the new configuration to the provided backup process. + * @param process the process on which to apply the new config. + */ public void updateProcessConfig(BackupProcess process) { if (process instanceof BungeeWorkdirProcess) { process.setEnabled(config.workdirBackupEnabled); diff --git a/pandalib-bungee/src/main/java/fr/pandacube/lib/bungee/backup/BungeeWorkdirProcess.java b/pandalib-bungee/src/main/java/fr/pandacube/lib/bungee/backup/BungeeWorkdirProcess.java index 0a4a59e..9ce5a2e 100644 --- a/pandalib-bungee/src/main/java/fr/pandacube/lib/bungee/backup/BungeeWorkdirProcess.java +++ b/pandalib-bungee/src/main/java/fr/pandacube/lib/bungee/backup/BungeeWorkdirProcess.java @@ -5,8 +5,15 @@ import fr.pandacube.lib.core.backup.BackupProcess; import java.io.File; import java.util.function.BiPredicate; +/** + * The backup process responsible for the working directory of the current Bungeecord instance. + */ public class BungeeWorkdirProcess extends BackupProcess { - + + /** + * Instantiates this backup process. + * @param bm the backup manager. + */ protected BungeeWorkdirProcess(BungeeBackupManager bm) { super(bm, "workdir"); } diff --git a/pandalib-chat/src/main/java/fr/pandacube/lib/chat/ChatUtil.java b/pandalib-chat/src/main/java/fr/pandacube/lib/chat/ChatUtil.java index ebad4d1..2b12169 100644 --- a/pandalib-chat/src/main/java/fr/pandacube/lib/chat/ChatUtil.java +++ b/pandalib-chat/src/main/java/fr/pandacube/lib/chat/ChatUtil.java @@ -199,6 +199,7 @@ public class ChatUtil { /** * Do like {@link String#join(CharSequence, Iterable)}, but for components. * @param separator the separator used everywhere except between the two last components to join. + * @param elements the components to join. * @return a new {@link Chat} instance with all the provided {@code component} joined using the separators. */ public static FormatableChat join(ComponentLike separator, Iterable elements) { diff --git a/pandalib-cli/src/main/java/fr/pandacube/lib/cli/CLIApplication.java b/pandalib-cli/src/main/java/fr/pandacube/lib/cli/CLIApplication.java index aea1206..68f2f7b 100644 --- a/pandalib-cli/src/main/java/fr/pandacube/lib/cli/CLIApplication.java +++ b/pandalib-cli/src/main/java/fr/pandacube/lib/cli/CLIApplication.java @@ -14,17 +14,23 @@ public abstract class CLIApplication { private static CLIApplication instance; + /** + * Returns the current application instance. + * @return the current application instance. + */ public static CLIApplication getInstance() { return instance; } - - - - + /** + * The instance of {@link CLI} for this application. + */ public final CLI cli; + /** + * Creates a new application instance. + */ protected CLIApplication() { instance = this; CLI tmpCLI = null; @@ -56,6 +62,10 @@ public abstract class CLIApplication { } } + /** + * Returns the application's {@link Logger}. + * @return the application's {@link Logger}. + */ public Logger getLogger() { return cli.getLogger(); } @@ -63,6 +73,9 @@ public abstract class CLIApplication { private final AtomicBoolean stopping = new AtomicBoolean(false); + /** + * Stops this application. + */ @SuppressWarnings("finally") public final void stop() { synchronized (stopping) { @@ -75,25 +88,45 @@ public abstract class CLIApplication { end(); } catch (Throwable t) { Log.severe("Error stopping application " + getName() + " version " + getClass().getPackage().getImplementationVersion(), t); + System.exit(1); } finally { Log.info("Bye bye."); System.exit(0); } } + /** + * Tells if this application is currently stopping, that is the {@link #stop()} method has been called. + * @return true if the application is stopping, false otherwise. + */ public boolean isStopping() { return stopping.get(); } - - + /** + * Gets the name of this application. + * @return the name of this application. + */ public abstract String getName(); + /** + * Method to override to initialize stuff in this application. + * This method is called on instanciation of this Application. + * @throws Exception If an exception is thrown, the application will not start. + */ protected abstract void start() throws Exception; + /** + * Method to override to reload specific stuff in this application. + * This method is called by using the command {@code admin reload}. + */ public abstract void reload(); + /** + * Method to override to execute stuff when this application stops. + * This method is called once before this application terminates, possibly from a shutdown hook Thread. + */ protected abstract void end(); diff --git a/pandalib-cli/src/main/java/fr/pandacube/lib/cli/commands/CommandAdmin.java b/pandalib-cli/src/main/java/fr/pandacube/lib/cli/commands/CommandAdmin.java index aa9706d..6018d9a 100644 --- a/pandalib-cli/src/main/java/fr/pandacube/lib/cli/commands/CommandAdmin.java +++ b/pandalib-cli/src/main/java/fr/pandacube/lib/cli/commands/CommandAdmin.java @@ -31,6 +31,9 @@ import static fr.pandacube.lib.chat.ChatStatic.failureText; import static fr.pandacube.lib.chat.ChatStatic.successText; import static fr.pandacube.lib.chat.ChatStatic.text; +/** + * The {@code admin} command for a {@link CLIApplication}. + */ public class CommandAdmin extends CLIBrigadierCommand { @Override diff --git a/pandalib-cli/src/main/java/fr/pandacube/lib/cli/commands/CommandStop.java b/pandalib-cli/src/main/java/fr/pandacube/lib/cli/commands/CommandStop.java index ef440c5..67f4f29 100644 --- a/pandalib-cli/src/main/java/fr/pandacube/lib/cli/commands/CommandStop.java +++ b/pandalib-cli/src/main/java/fr/pandacube/lib/cli/commands/CommandStop.java @@ -5,7 +5,7 @@ import com.mojang.brigadier.builder.LiteralArgumentBuilder; import fr.pandacube.lib.cli.CLIApplication; /** - * /stop (/end) command. + * the {@code stop} (or {@code end}) command for a {@link CLIApplication}. */ public class CommandStop extends CLIBrigadierCommand { diff --git a/pandalib-core/src/main/java/fr/pandacube/lib/core/backup/BackupManager.java b/pandalib-core/src/main/java/fr/pandacube/lib/core/backup/BackupManager.java index 948388c..1f45505 100644 --- a/pandalib-core/src/main/java/fr/pandacube/lib/core/backup/BackupManager.java +++ b/pandalib-core/src/main/java/fr/pandacube/lib/core/backup/BackupManager.java @@ -66,7 +66,10 @@ public class BackupManager extends TimerTask { return backupDirectory; } - + /** + * Tells if a backup is currently running. + * @return true if a backup is running, false otherwise. + */ public synchronized boolean isBackupRunning() { return runningBackup.get() != null; } @@ -93,6 +96,7 @@ public class BackupManager extends TimerTask { * Disables this backup manager, canceling scheduled backups. * It will wait for a currently running backup to finish before returning. */ + @SuppressWarnings("BusyWait") public synchronized void onDisable() { schedulerTimer.cancel(); diff --git a/pandalib-core/src/main/java/fr/pandacube/lib/core/mc_version/MinecraftVersionList.java b/pandalib-core/src/main/java/fr/pandacube/lib/core/mc_version/MinecraftVersionList.java index 1367ec9..da51dc2 100644 --- a/pandalib-core/src/main/java/fr/pandacube/lib/core/mc_version/MinecraftVersionList.java +++ b/pandalib-core/src/main/java/fr/pandacube/lib/core/mc_version/MinecraftVersionList.java @@ -5,14 +5,27 @@ import java.util.List; import java.util.Map; import java.util.TreeMap; +/** + * Record holding the data for {@link ProtocolVersion}, to facilitate serializing and deserializing. + * @param protocolOfVersion mapping from a version string to the corresponding protocol version number. + * @param versionsOfProtocol mapping from a protocol version number to a list of the supported MC versions. + */ public record MinecraftVersionList( Map protocolOfVersion, Map> versionsOfProtocol ) { + /** + * Creates an empty {@link MinecraftVersionList}. + */ public MinecraftVersionList() { this(new TreeMap<>(MinecraftVersionUtil::compareVersions), new TreeMap<>()); } + /** + * Adds a new pair of version string and protocol version number. + * @param versionId the version string (e.g. "1.19.4"). + * @param protocolVersion the protocol version number. + */ public void add(String versionId, int protocolVersion) { protocolOfVersion.put(versionId, protocolVersion); List versions = versionsOfProtocol.computeIfAbsent(protocolVersion, p -> new ArrayList<>());