HomeAPI

Overview

The HomeAPI is a core component of the system plugin, providing functionality for managing player homes in a Minecraft server. It allows players to set, retrieve, teleport to, delete, list, and rename their homes. The API also handles database integration to ensure persistence.

---

Initialization

Constructor

public HomeAPI(DatabaseManager databaseManager)

• Parameters:

  • databaseManager: The database manager used to handle SQL connections.

• Description: Initializes the HomeAPI instance with the given database manager.

---

Methods

setHome

public void setHome(Player player, String homeName)

• Description: Sets a new home for a player at their current location.

• Parameters:

  • player: The player setting the home.

  • homeName: The name of the home.

• Behavior:

  • Checks the player's rank and their home limit.

  • Validates if a home with the same name already exists.

  • Saves the home to the database if all conditions are met.

• Notifications: Sends appropriate messages to the player if the operation succeeds or fails.

---

getHome

public Location getHome(Player player, String homeName)

• Description: Retrieves the location of a specified home.

• Parameters:

  • player: The player requesting the home.

  • homeName: The name of the home.

• Returns:

  • The Location of the home if found, otherwise null.

• Behavior:

  • First checks the in-memory cache.

  • If not found, attempts to load the home from the database.

---

deleteHome

public void deleteHome(Player player, String homeName)

• Description: Deletes a specified home for the player.

• Parameters:

  • player: The player deleting the home.

  • homeName: The name of the home to delete.

• Behavior:

  • Removes the home from memory and the database.

  • Sends appropriate notifications to the player.

---

teleportToHome

public void teleportToHome(Player player, String homeName)

• Description: Teleports the player to a specified home.

• Parameters:

  • player: The player being teleported.

  • homeName: The name of the home.

• Behavior:

  • Fetches the home location and teleports the player if the home exists.

  • Sends success or error messages to the player.

---

listHomes

public void listHomes(Player player)

• Description: Lists all homes for a player.

• Parameters:

  • player: The player requesting the list.

• Behavior:

  • Fetches homes from the database.

  • Sends a formatted list of homes to the player or notifies them if none exist.

---

renameHome

public void renameHome(Player player, String oldName, String newName)

• Description: Renames an existing home for a player.

• Parameters:

  • player: The player renaming the home.

  • oldName: The current name of the home.

  • newName: The new name for the home.

• Behavior:

  • Updates the home name in the database.

  • Notifies the player of success or failure.

---

saveHomeToDatabase

public void saveHomeToDatabase(UUID playerId, String homeName, Location location)

• Description: Saves a home to the database.

• Parameters:

  • playerId: The UUID of the player.

  • homeName: The name of the home.

  • location: The location of the home.

• Behavior:

  • Executes an SQL query to insert or update the home in the database.

---

getHomesFromDatabase

public Map<String, Location> getHomesFromDatabase(UUID playerId)

• Description: Fetches all homes for a player from the database.

• Parameters:

  • playerId: The UUID of the player.

• Returns:

  • A map of home names to locations.

• Behavior:

  • Executes an SQL query to retrieve all homes for the player.

---

deleteHomeFromDatabase

private void deleteHomeFromDatabase(UUID playerId, String homeName)

• Description: Deletes a home from the database.

• Parameters:

  • playerId: The UUID of the player.

  • homeName: The name of the home to delete.

• Behavior:

  • Executes an SQL query to remove the home.

---

loadHomeFromDatabase

private void loadHomeFromDatabase(UUID playerId, String homeName)

• Description: Loads a specific home from the database into memory.

• Parameters:

  • playerId: The UUID of the player.

  • homeName: The name of the home.

• Behavior:

  • Queries the database for the home and caches the result.

---

getPlayersWithHomes

public List<String> getPlayersWithHomes()

• Description: Retrieves a list of players who have at least one home.

• Returns:

  • A list of player names.

• Behavior:

  • Executes an SQL query to find distinct players with homes.

---

getHomeNames

public List<String> getHomeNames(UUID playerId)

• Description: Retrieves the names of all homes for a specific player.

• Parameters:

  • playerId: The UUID of the player.

• Returns:

  • A list of home names.

• Behavior:

  • Executes an SQL query to fetch home names for the player.

---

Error Handling

• SQL errors are logged to the server console.

• Player-facing errors are displayed using the PlaceholderHandler.

---

Dependencies

• System plugin for rank and database management.

• PlaceholderHandler for messaging.

• DatabaseManager for SQL operations.

---

Notes

• The API uses a caching mechanism to reduce database queries.

• Homes are stored persistently in a database.

• Home limits are enforced based on player rank.