diff --git a/src/main/java/me/axeno/hommr/Hommr.java b/src/main/java/me/axeno/hommr/Hommr.java index 1d2f5d9..18b6345 100644 --- a/src/main/java/me/axeno/hommr/Hommr.java +++ b/src/main/java/me/axeno/hommr/Hommr.java @@ -24,6 +24,11 @@ public final class Hommr extends JavaPlugin { @Getter private Lamp lamp; + /** + * Initializes the plugin on enable: sets the singleton instance, ensures default configuration, + * starts the HomeManager, creates and registers the Hommr API service, builds the command lamp, + * registers plugin commands, and emits the startup log banner. + */ @Override public void onEnable() { instance = this; @@ -43,12 +48,23 @@ public void onEnable() { this.logLoadMessage(); } + /** + * Perform plugin shutdown tasks when the plugin is disabled. + * + *

Shuts down the HomeManager and logs a disable message to the SLF4J logger.

+ */ @Override public void onDisable() { HomeManager.shutdown(); this.getSLF4JLogger().info("Hommr Disabled"); } + /** + * Logs a stylized startup banner containing plugin, Java, and server information. + * + *

Emits a multi-line ASCII banner to the plugin logger that includes the plugin + * version, the running Java version, and the server name/version.

+ */ private void logLoadMessage() { Logger logger = this.getSLF4JLogger(); @@ -64,4 +80,4 @@ private void logLoadMessage() { logger.info("\u001B[1;34m |_||_|\\___/|_| |_|_| |_|_|_\\ \u001B[0m"); logger.info("\u001B[1;34m \u001B[0m"); } -} +} \ No newline at end of file diff --git a/src/main/java/me/axeno/hommr/managers/DatabaseManager.java b/src/main/java/me/axeno/hommr/managers/DatabaseManager.java index bc6c168..be6124b 100644 --- a/src/main/java/me/axeno/hommr/managers/DatabaseManager.java +++ b/src/main/java/me/axeno/hommr/managers/DatabaseManager.java @@ -20,6 +20,15 @@ public class DatabaseManager { @Getter private Dao homeDao; + /** + * Set up the database connection and DAO for Home entities based on configuration. + * + * Initializes the plugin data folder if necessary, creates a JDBC connection source + * (MySQL when `database.type` is `"mysql"`, otherwise SQLite using a `homes.db` file), + * and creates a Dao for accessing Home records. Ensures the Home table + * exists in the database; failures during folder creation, table creation, or overall + * initialization are logged. + */ public void init() { try { File dataFolder = Hommr.getInstance().getDataFolder(); @@ -58,6 +67,11 @@ public void init() { } } + /** + * Closes the underlying database connection source and releases related resources. + * + * If an error occurs while closing, the exception is caught and a warning is logged. + */ public void close() { if (connectionSource != null) { try { @@ -68,10 +82,24 @@ public void close() { } } + /** + * Retrieve all Home records from the database. + * + * @return a list of all Home objects + * @throws SQLException if a database access error occurs while querying for homes + */ public List getAllHomes() throws SQLException { return homeDao.queryForAll(); } + /** + * Replaces all stored Home records with the provided list. + * + * Clears the Home table and inserts the given homes in a single batch operation. + * + * @param homes the list of Home objects to persist (may be empty) + * @throws SQLException if an error occurs while clearing the table or saving records + */ public void saveAllHomes(List homes) throws SQLException { TableUtils.clearTable(connectionSource, Home.class); try { @@ -88,4 +116,4 @@ public void saveAllHomes(List homes) throws SQLException { throw new SQLException("Error saving all homes", e); } } -} +} \ No newline at end of file diff --git a/src/main/java/me/axeno/hommr/managers/HomeManager.java b/src/main/java/me/axeno/hommr/managers/HomeManager.java index d595243..9f60c7f 100644 --- a/src/main/java/me/axeno/hommr/managers/HomeManager.java +++ b/src/main/java/me/axeno/hommr/managers/HomeManager.java @@ -21,6 +21,11 @@ public class HomeManager { private static Map playerHomesCache; private static DatabaseManager databaseManager; + /** + * Initializes the HomeManager: ensures the database manager exists, creates the in-memory player homes cache, and loads all persisted homes into the cache. + * + *

On failure to read from the database, the method logs a severe error and continues (the cache will be empty).

+ */ public static void init() { if (databaseManager == null) { databaseManager = new DatabaseManager(); @@ -41,6 +46,11 @@ public static void init() { } } + /** + * Persists all homes currently held in the in-memory cache to persistent storage and closes the database manager. + * + * If the database manager is not initialized, this method does nothing. On failure to save homes a severe log entry is recorded. + */ public static void shutdown() { if (databaseManager != null) { try { @@ -57,10 +67,29 @@ public static void shutdown() { } } + /** + * Get the PlayerHomes object for the specified player, creating and caching a new one if none exists. + * + * @param playerId the UUID of the player + * @return the PlayerHomes for the specified player; created and stored in the cache if absent + */ private static PlayerHomes getOrCreatePlayerHomes(UUID playerId) { return playerHomesCache.computeIfAbsent(playerId, PlayerHomes::new); } + /** + * Create or update a player's home with the given name and location. + * + * Attempts to store the provided location as a home for the player. If the player has reached + * the configured maximum number of homes and the operation would create a new home, the method + * fails and returns `false`. A HomeSetEvent is fired before the change; if that event is + * cancelled the operation is aborted. + * + * @param player the player who owns the home + * @param homeName the name of the home to create or update + * @param location the location to store for the home + * @return `true` if the home was created or updated, `false` if the operation was prevented (max homes reached or event cancelled) + */ public static boolean setHome(Player player, String homeName, Location location) { PlayerHomes playerHomes = getOrCreatePlayerHomes(player.getUniqueId()); @@ -83,11 +112,27 @@ public static boolean setHome(Player player, String homeName, Location location) return true; } + /** + * Retrieve the home with the given name for the specified player. + * + * If the player has no existing PlayerHomes entry in the in-memory cache, one will be created. + * + * @param playerId the UUID of the player + * @param homeName the name of the home to retrieve + * @return an Optional containing the Home if found, or an empty Optional if no home with that name exists + */ public static Optional getHome(UUID playerId, String homeName) { PlayerHomes playerHomes = getOrCreatePlayerHomes(playerId); return playerHomes.getHome(homeName); } + /** + * Delete the specified home for the given player, emitting a HomeDeleteEvent that can cancel the deletion. + * + * @param player the player who owns the home + * @param homeName the name of the home to delete + * @return `true` if the home was removed, `false` if the home did not exist or the deletion was cancelled + */ public static boolean deleteHome(Player player, String homeName) { PlayerHomes playerHomes = getOrCreatePlayerHomes(player.getUniqueId()); @@ -107,6 +152,16 @@ public static boolean deleteHome(Player player, String homeName) { return playerHomes.removeHome(homeName); } + /** + * Teleports the given player to the specified home if available and permitted. + * + * Attempts to locate the home by name for the player, reconstruct its location, fire a HomeTeleportEvent + * and, if the event is not cancelled, perform the teleport. + * + * @param player the player to teleport + * @param homeName the name of the home to teleport to + * @return `true` if the player was teleported, `false` if the home was not found, the location could not be reconstructed, or the teleport was cancelled + */ public static boolean teleportToHome(Player player, String homeName) { Optional homeOpt = getHome(player.getUniqueId(), homeName); if (homeOpt.isEmpty()) { @@ -131,21 +186,49 @@ public static boolean teleportToHome(Player player, String homeName) { return true; } + /** + * Retrieve the names of all homes for the specified player. + * + * @param playerId the UUID of the player whose home names to return + * @return the set of home names owned by the player, empty if the player has no homes + */ public static Set getHomeNames(UUID playerId) { return getOrCreatePlayerHomes(playerId).getHomeNames(); } + /** + * Retrieve the number of homes owned by the specified player. + * + * @param playerId the UUID of the player + * @return the number of homes the player currently has + */ public static int getHomeCount(UUID playerId) { return getOrCreatePlayerHomes(playerId).getHomeCount(); } + /** + * Determines whether the specified player has a home with the given name. + * + * @param playerId the UUID of the player + * @param homeName the name of the home to check + * @return `true` if the player has a home with the given name, `false` otherwise + */ public static boolean hasHome(UUID playerId, String homeName) { return getOrCreatePlayerHomes(playerId).hasHome(homeName); } + /** + * Determine the maximum number of homes allowed for the given player. + * + *

Currently returns a placeholder value indicating no limit; permission- or + * configuration-based limits should be implemented later.

+ * + * @param player the player whose home limit is being queried + * @return `-1` if unlimited, otherwise the maximum number of homes permitted for the player + */ public static int getMaxHomes(@SuppressWarnings("unused") Player player) { // TODO: Implement a system to determine max homes based on permissions or other criteria return -1; // -1 means unlimited } -} +} \ No newline at end of file diff --git a/src/main/java/me/axeno/hommr/models/Home.java b/src/main/java/me/axeno/hommr/models/Home.java index 465d842..55ad003 100644 --- a/src/main/java/me/axeno/hommr/models/Home.java +++ b/src/main/java/me/axeno/hommr/models/Home.java @@ -47,6 +47,14 @@ public class Home { @DatabaseField(canBeNull = false) private long createdAt; + /** + * Create a Home instance from a Bukkit Location for the given owner and name. + * + * @param owner the UUID of the player who owns the home + * @param name the display name for the home + * @param location the source Bukkit Location whose world, coordinates, yaw, and pitch are used + * @return a Home populated with the location data, owner and name; `id` is set to 0 and `createdAt` is set to the current system time in milliseconds + */ public static Home fromLocation(UUID owner, String name, Location location) { return new Home( 0, @@ -69,4 +77,4 @@ public Location toLocation() { } return new Location(world, x, y, z, yaw, pitch); } -} +} \ No newline at end of file diff --git a/src/main/java/me/axeno/hommr/models/PlayerHomes.java b/src/main/java/me/axeno/hommr/models/PlayerHomes.java index ef8ec60..072050d 100644 --- a/src/main/java/me/axeno/hommr/models/PlayerHomes.java +++ b/src/main/java/me/axeno/hommr/models/PlayerHomes.java @@ -10,11 +10,24 @@ public class PlayerHomes { private final UUID playerId; private final Map homes; + /** + * Creates a PlayerHomes instance for the specified player. + * + * Initializes the object and prepares an empty, thread-safe map for storing the player's named homes. + * + * @param playerId UUID identifying the player whose homes will be managed + */ public PlayerHomes(UUID playerId) { this.playerId = playerId; this.homes = new ConcurrentHashMap<>(); } + /** + * Stores a Home under the given name for this player, using the lowercase form of the name. + * + * @param name the home name; its lowercase form is used as the storage key + * @param home the Home instance to store; replaces any existing home with the same lowercase name + */ public void setHome(String name, Home home) { homes.put(name.toLowerCase(), home); } @@ -38,4 +51,4 @@ public boolean hasHome(String name) { public int getHomeCount() { return homes.size(); } -} +} \ No newline at end of file