Some more javadoc

This commit is contained in:
Marc Baloup 2023-08-27 17:28:12 +02:00
parent bd3bea8381
commit 62949948e1
10 changed files with 124 additions and 11 deletions

View File

@ -4,25 +4,42 @@ import fr.pandacube.lib.bungee.util.BungeeDailyLogRotateFileHandler;
import fr.pandacube.lib.bungee.util.PluginMessagePassthrough; import fr.pandacube.lib.bungee.util.PluginMessagePassthrough;
import net.md_5.bungee.api.plugin.Plugin; 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 { public class PandaLibBungee {
private static Plugin plugin; private static Plugin plugin;
/**
* Method to be called in {@link Plugin#onLoad()} method.
* @param plugin the plugin instance.
*/
public static void onLoad(Plugin plugin) { public static void onLoad(Plugin plugin) {
PandaLibBungee.plugin = plugin; PandaLibBungee.plugin = plugin;
} }
/**
* Method to be called in {@link Plugin#onEnable()} method.
*/
public static void onEnable() { public static void onEnable() {
PluginMessagePassthrough.init(plugin); PluginMessagePassthrough.init(plugin);
BungeeDailyLogRotateFileHandler.init(true); BungeeDailyLogRotateFileHandler.init(true);
} }
/**
* Method to be called in {@link Plugin#onDisable()} method.
*/
public static void disable() { public static void disable() {
} }
/**
* Returns the plugin instance.
* @return the plugin instance.
*/
public static Plugin getPlugin() { public static Plugin getPlugin() {
return plugin; return plugin;
} }

View File

@ -6,12 +6,33 @@ import java.io.File;
import java.util.ArrayList; import java.util.ArrayList;
import java.util.List; import java.util.List;
/**
* Class that holds the configuration varables for {@link BungeeBackupManager}.
*/
@SuppressWarnings("CanBeFinal") @SuppressWarnings("CanBeFinal")
public class BungeeBackupConfig { public class BungeeBackupConfig {
/**
* Tells if the working directory of the current bungee instance should be backed up.
*/
public boolean workdirBackupEnabled = true; public boolean workdirBackupEnabled = true;
/**
* Tells if the old logs of the current bungee instance should be backed up.
*/
public boolean logsBackupEnabled = true; 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 public String scheduling = "0 2 * * *"; // cron format, here is every day at 2am
/**
* The destination directory for the backups.
*/
public File backupDirectory = null; 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)); 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<String> workdirIgnoreList = new ArrayList<>(); public List<String> workdirIgnoreList = new ArrayList<>();
} }

View File

@ -6,10 +6,17 @@ import fr.pandacube.lib.core.backup.RotatedLogsBackupProcess;
import java.io.File; import java.io.File;
/**
* Handles the backup processes for a Bungeecord instance.
*/
public class BungeeBackupManager extends BackupManager { public class BungeeBackupManager extends BackupManager {
BungeeBackupConfig config; BungeeBackupConfig config;
/**
* Instanciate a new {@link BungeeBackupManager}.
* @param config the configuration.
*/
public BungeeBackupManager(BungeeBackupConfig config) { public BungeeBackupManager(BungeeBackupConfig config) {
super(config.backupDirectory); super(config.backupDirectory);
setConfig(config); setConfig(config);
@ -24,12 +31,19 @@ public class BungeeBackupManager extends BackupManager {
super.addProcess(process); super.addProcess(process);
} }
/**
* Sets a new configuration for this backup manager.
* @param config the new configuration.
*/
public void setConfig(BungeeBackupConfig config) { public void setConfig(BungeeBackupConfig config) {
this.config = config; this.config = config;
backupQueue.forEach(this::updateProcessConfig); 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) { public void updateProcessConfig(BackupProcess process) {
if (process instanceof BungeeWorkdirProcess) { if (process instanceof BungeeWorkdirProcess) {
process.setEnabled(config.workdirBackupEnabled); process.setEnabled(config.workdirBackupEnabled);

View File

@ -5,8 +5,15 @@ import fr.pandacube.lib.core.backup.BackupProcess;
import java.io.File; import java.io.File;
import java.util.function.BiPredicate; import java.util.function.BiPredicate;
/**
* The backup process responsible for the working directory of the current Bungeecord instance.
*/
public class BungeeWorkdirProcess extends BackupProcess { public class BungeeWorkdirProcess extends BackupProcess {
/**
* Instantiates this backup process.
* @param bm the backup manager.
*/
protected BungeeWorkdirProcess(BungeeBackupManager bm) { protected BungeeWorkdirProcess(BungeeBackupManager bm) {
super(bm, "workdir"); super(bm, "workdir");
} }

View File

@ -199,6 +199,7 @@ public class ChatUtil {
/** /**
* Do like {@link String#join(CharSequence, Iterable)}, but for components. * 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 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. * @return a new {@link Chat} instance with all the provided {@code component} joined using the separators.
*/ */
public static FormatableChat join(ComponentLike separator, Iterable<? extends ComponentLike> elements) { public static FormatableChat join(ComponentLike separator, Iterable<? extends ComponentLike> elements) {

View File

@ -14,17 +14,23 @@ public abstract class CLIApplication {
private static CLIApplication instance; private static CLIApplication instance;
/**
* Returns the current application instance.
* @return the current application instance.
*/
public static CLIApplication getInstance() { public static CLIApplication getInstance() {
return instance; return instance;
} }
/**
* The instance of {@link CLI} for this application.
*/
public final CLI cli; public final CLI cli;
/**
* Creates a new application instance.
*/
protected CLIApplication() { protected CLIApplication() {
instance = this; instance = this;
CLI tmpCLI = null; 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() { public Logger getLogger() {
return cli.getLogger(); return cli.getLogger();
} }
@ -63,6 +73,9 @@ public abstract class CLIApplication {
private final AtomicBoolean stopping = new AtomicBoolean(false); private final AtomicBoolean stopping = new AtomicBoolean(false);
/**
* Stops this application.
*/
@SuppressWarnings("finally") @SuppressWarnings("finally")
public final void stop() { public final void stop() {
synchronized (stopping) { synchronized (stopping) {
@ -75,25 +88,45 @@ public abstract class CLIApplication {
end(); end();
} catch (Throwable t) { } catch (Throwable t) {
Log.severe("Error stopping application " + getName() + " version " + getClass().getPackage().getImplementationVersion(), t); Log.severe("Error stopping application " + getName() + " version " + getClass().getPackage().getImplementationVersion(), t);
System.exit(1);
} finally { } finally {
Log.info("Bye bye."); Log.info("Bye bye.");
System.exit(0); 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() { public boolean isStopping() {
return stopping.get(); return stopping.get();
} }
/**
* Gets the name of this application.
* @return the name of this application.
*/
public abstract String getName(); 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; 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(); 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(); protected abstract void end();

View File

@ -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.successText;
import static fr.pandacube.lib.chat.ChatStatic.text; import static fr.pandacube.lib.chat.ChatStatic.text;
/**
* The {@code admin} command for a {@link CLIApplication}.
*/
public class CommandAdmin extends CLIBrigadierCommand { public class CommandAdmin extends CLIBrigadierCommand {
@Override @Override

View File

@ -5,7 +5,7 @@ import com.mojang.brigadier.builder.LiteralArgumentBuilder;
import fr.pandacube.lib.cli.CLIApplication; 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 { public class CommandStop extends CLIBrigadierCommand {

View File

@ -66,7 +66,10 @@ public class BackupManager extends TimerTask {
return backupDirectory; return backupDirectory;
} }
/**
* Tells if a backup is currently running.
* @return true if a backup is running, false otherwise.
*/
public synchronized boolean isBackupRunning() { public synchronized boolean isBackupRunning() {
return runningBackup.get() != null; return runningBackup.get() != null;
} }
@ -93,6 +96,7 @@ public class BackupManager extends TimerTask {
* Disables this backup manager, canceling scheduled backups. * Disables this backup manager, canceling scheduled backups.
* It will wait for a currently running backup to finish before returning. * It will wait for a currently running backup to finish before returning.
*/ */
@SuppressWarnings("BusyWait")
public synchronized void onDisable() { public synchronized void onDisable() {
schedulerTimer.cancel(); schedulerTimer.cancel();

View File

@ -5,14 +5,27 @@ import java.util.List;
import java.util.Map; import java.util.Map;
import java.util.TreeMap; 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( public record MinecraftVersionList(
Map<String, Integer> protocolOfVersion, Map<String, Integer> protocolOfVersion,
Map<Integer, List<String>> versionsOfProtocol Map<Integer, List<String>> versionsOfProtocol
) { ) {
/**
* Creates an empty {@link MinecraftVersionList}.
*/
public MinecraftVersionList() { public MinecraftVersionList() {
this(new TreeMap<>(MinecraftVersionUtil::compareVersions), new TreeMap<>()); 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) { public void add(String versionId, int protocolVersion) {
protocolOfVersion.put(versionId, protocolVersion); protocolOfVersion.put(versionId, protocolVersion);
List<String> versions = versionsOfProtocol.computeIfAbsent(protocolVersion, p -> new ArrayList<>()); List<String> versions = versionsOfProtocol.computeIfAbsent(protocolVersion, p -> new ArrayList<>());