From 6c53061f61eac86f177d09478ba0b2ad0a85faf5 Mon Sep 17 00:00:00 2001 From: Brianna Date: Thu, 18 Jul 2019 01:41:12 -0400 Subject: [PATCH] Added Javadocs --- .../epicfurnaces/utils/locale/Locale.java | 128 +++++++++++++++--- .../epicfurnaces/utils/locale/Message.java | 58 +++++++- 2 files changed, 163 insertions(+), 23 deletions(-) diff --git a/src/main/java/com/songoda/epicfurnaces/utils/locale/Locale.java b/src/main/java/com/songoda/epicfurnaces/utils/locale/Locale.java index 8dfa3a1..75e440c 100644 --- a/src/main/java/com/songoda/epicfurnaces/utils/locale/Locale.java +++ b/src/main/java/com/songoda/epicfurnaces/utils/locale/Locale.java @@ -11,14 +11,19 @@ import java.util.regex.Matcher; import java.util.regex.Pattern; import java.util.stream.Collectors; +/** + * Assists in the utilization of localization files. + * Created to be used by the Songoda Team. + * + * @author Brianna O'Keefe - Songoda + */ public class Locale { - private static JavaPlugin plugin; - private static File localeFolder; + private static final List LOCALES = new ArrayList<>(); private static final Pattern NODE_PATTERN = Pattern.compile("(\\w+(?:\\.{1}\\w+)*)\\s*=\\s*\"(.*)\""); private static final String FILE_EXTENSION = ".lang"; - - private static final List LOCALES = new ArrayList<>(); + private static JavaPlugin plugin; + private static File localeFolder; private final Map nodes = new HashMap<>(); @@ -27,7 +32,12 @@ public class Locale { private File file; private String name; - public Locale(String name) { + /** + * Instantiate the Locale class for future use + * + * @param name the name of the instantiated language + */ + private Locale(String name) { if (plugin == null) return; @@ -41,6 +51,14 @@ public class Locale { plugin.getLogger().info("Loaded locale \"" + fileName + "\""); } + /** + * Initialize the class to load all existing language files and update them. + * This must be called before any other methods in this class as otherwise + * the methods will fail to invoke + * + * @param plugin the plugin instance + * @param defaultLocale the default language + */ public Locale(JavaPlugin plugin, String defaultLocale) { Locale.plugin = plugin; @@ -65,10 +83,24 @@ public class Locale { } } + /** + * Save a locale file from the InputStream, to the locale folder + * + * @param fileName the name of the file to save + * @return true if the operation was successful, false otherwise + */ public static boolean saveLocale(String fileName) { return saveLocale(plugin.getResource(defaultLocale + FILE_EXTENSION), fileName); } + + /** + * Save a locale file from the InputStream, to the locale folder + * + * @param in file to save + * @param fileName the name of the file to save + * @return true if the operation was successful, false otherwise + */ public static boolean saveLocale(InputStream in, String fileName) { if (!localeFolder.exists()) localeFolder.mkdirs(); @@ -94,6 +126,7 @@ public class Locale { } } + // Write new changes to existing files, if any at all private static boolean compareFiles(InputStream in, File existingFile) { InputStream defaultFile = in == null ? plugin.getResource((defaultLocale != null ? defaultLocale : "en_US") + FILE_EXTENSION) : in; @@ -116,7 +149,10 @@ public class Locale { if (!changed) { writer.newLine(); writer.newLine(); + // Leave a note alerting the user of the newly added messages. writer.write("# New messages for " + plugin.getName() + " v" + plugin.getDescription().getVersion() + "."); + + // If changes were found outside of the default file leave a note explaining that. if (in == null) { writer.newLine(); writer.write("# These translations were found untranslated, join"); @@ -141,6 +177,13 @@ public class Locale { return changed; } + + /** + * Check whether a locale exists and is registered or not + * + * @param name the whole language tag (i.e. "en_US") + * @return true if it exists + */ public static boolean localeLoaded(String name) { for (Locale locale : LOCALES) if (locale.getName().equals(name)) return true; @@ -148,25 +191,23 @@ public class Locale { } + /** + * Get a locale by its entire proper name (i.e. "en_US") + * + * @param name the full name of the locale + * @return locale of the specified name + */ public static Locale getLocale(String name) { for (Locale locale : LOCALES) if (locale.getName().equalsIgnoreCase(name)) return locale; return null; } - private static void copy(InputStream input, OutputStream output) { - int n; - byte[] buffer = new byte[1024 * 4]; - - try { - while ((n = input.read(buffer)) != -1) { - output.write(buffer, 0, n); - } - } catch (IOException e) { - e.printStackTrace(); - } - } - + /** + * Clear the previous message cache and load new messages directly from file + * + * @return reload messages from file + */ public boolean reloadMessages() { if (!this.file.exists()) { plugin.getLogger().warning("Could not find file for locale \"" + this.name + "\""); @@ -186,7 +227,7 @@ public class Locale { continue; } - nodes.put(matcher.group(1),matcher.group(2)); + nodes.put(matcher.group(1), matcher.group(2)); } } catch (IOException e) { e.printStackTrace(); @@ -195,24 +236,67 @@ public class Locale { return true; } - private Message applyPrefix(Message message) { + /** + * Supply the Message object with the plugins prefix. + * + * @param message message to be applied + * @return applied message + */ + private Message supplyPrefix(Message message) { return message.setPrefix(this.nodes.getOrDefault("general.nametag.prefix", "[Plugin]")); } + /** + * Create a new unsaved Message + * + * @param message the message to create + * @return the created message + */ public Message newMessage(String message) { - return applyPrefix(new Message(message)); + return supplyPrefix(new Message(message)); } + /** + * Get a message set for a specific node. + * + * @param node the node to get + * @return the message for the specified node + */ public Message getMessage(String node) { return this.getMessageOrDefault(node, node); } + /** + * Get a message set for a specific node + * + * @param node the node to get + * @param defaultValue the default value given that a value for the node was not found + * @return the message for the specified node. Default if none found + */ public Message getMessageOrDefault(String node, String defaultValue) { - return applyPrefix(new Message(this.nodes.getOrDefault(node, defaultValue))); + return supplyPrefix(new Message(this.nodes.getOrDefault(node, defaultValue))); } + /** + * Return the locale name (i.e. "en_US") + * + * @return the locale name + */ public String getName() { return name; } + private static void copy(InputStream input, OutputStream output) { + int n; + byte[] buffer = new byte[1024 * 4]; + + try { + while ((n = input.read(buffer)) != -1) { + output.write(buffer, 0, n); + } + } catch (IOException e) { + e.printStackTrace(); + } + } + } diff --git a/src/main/java/com/songoda/epicfurnaces/utils/locale/Message.java b/src/main/java/com/songoda/epicfurnaces/utils/locale/Message.java index e3ae24b..5fb3cbd 100644 --- a/src/main/java/com/songoda/epicfurnaces/utils/locale/Message.java +++ b/src/main/java/com/songoda/epicfurnaces/utils/locale/Message.java @@ -4,44 +4,100 @@ import org.bukkit.ChatColor; import org.bukkit.command.CommandSender; import org.bukkit.entity.Player; +/** + * The Message object. This holds the message to be sent + * as well as the plugins prefix so that they can both be + * easily manipulated then deployed + */ public class Message { private String prefix = null; private String message; - Message(String message) { + /** + * create a new message + * + * @param message the message text + */ + public Message(String message) { this.message = message; } + /** + * Format and send the held message to a player + * + * @param player player to send the message to + */ public void sendMessage(Player player) { player.sendMessage(this.getMessage()); } + /** + * Format and send the held message with the + * appended plugin prefix to a player + * + * @param player player to send the message to + */ public void sendPrefixedMessage(Player player) { player.sendMessage(this.getPrefixedMessage()); } + /** + * Format and send the held message to a player + * + * @param sender command sender to send the message to + */ public void sendMessage(CommandSender sender) { sender.sendMessage(this.getMessage()); } + /** + * Format and send the held message with the + * appended plugin prefix to a command sender + * + * @param sender command sender to send the message to + */ public void sendPrefixedMessage(CommandSender sender) { sender.sendMessage(this.getPrefixedMessage()); } + /** + * Format the held message and append the plugins + * prefix + * + * @return the prefixed message + */ public String getPrefixedMessage() { return ChatColor.translateAlternateColorCodes('&',(prefix == null ? "" : this.prefix) + " " + this.message); } + /** + * Get and format the held message + * + * @return the message + */ public String getMessage() { return ChatColor.translateAlternateColorCodes('&', this.message); } + /** + * Get the held message + * + * @return the message + */ public String getUnformattedMessage() { return this.message; } + /** + * Replace the provided placeholder with the + * provided object + * + * @param placeholder the placeholder to replace + * @param replacement the replacement object + * @return the modified Message + */ public Message processPlaceholder(String placeholder, Object replacement) { this.message = message.replace("%" + placeholder + "%", replacement.toString()); return this;