Package dev.itsharshxd.zentrix.api.data

Interface DataService

public interface DataService
Service for accessing Zentrix's data folder and managing addon configurations.

This service allows addon developers to:

  • Access the main Zentrix data folder
  • Create and manage addon-specific data folders
  • Read and write configuration files
  • Store addon data persistently

Usage Example


 DataService dataService = api.getDataService();

 // Get your addon's data folder (creates if not exists)
 File myAddonFolder = dataService.getAddonDataFolder("my-addon");

 // Create a config file in your addon folder
 File configFile = new File(myAddonFolder, "config.yml");
 FileConfiguration config = dataService.loadYamlConfiguration(configFile);

 // Read/write values
 config.set("my-setting", true);
 dataService.saveYamlConfiguration(config, configFile);

 // Or use the helper method for quick config access
 FileConfiguration quickConfig = dataService.getOrCreateConfig("my-addon", "settings.yml");

Directory Structure

 plugins/Zentrix/
 ├── config.yml          (main plugin config - READ ONLY for addons)
 ├── settings.yml        (plugin settings - READ ONLY for addons)
 ├── addons/             (addon data folder root)
 │   ├── my-addon/       (your addon's folder)
 │   │   ├── config.yml
 │   │   └── data/
 │   └── other-addon/
 └── ...
Since:
1.0.1

  • Method Details

    • getPluginDataFolder

      @NotNull @NotNull File getPluginDataFolder()
      Gets the main Zentrix plugin data folder.

      This is the root folder where Zentrix stores all its data. Addons should generally use getAddonDataFolder(String) instead to keep their data organized.

      Warning: Modifying core Zentrix config files may cause unexpected behavior. Use with caution.

      Returns:
      The main plugin data folder (e.g., plugins/Zentrix/)

    • getAddonsFolder

      @NotNull @NotNull File getAddonsFolder()
      Gets the root folder where all addon data is stored.

      This folder is: plugins/Zentrix/addons/

      Returns:
      The addons data folder root

    • getAddonDataFolder

      @NotNull @NotNull File getAddonDataFolder(@NotNull @NotNull String addonId)
      Gets (or creates) a dedicated data folder for a specific addon.

      This creates a folder at: plugins/Zentrix/addons/{addonId}/

      The folder is automatically created if it doesn't exist.

      Parameters:
      addonId - The unique identifier for your addon (lowercase, no spaces)
      Returns:
      The addon's dedicated data folder
      Throws:
      IllegalArgumentException - if addonId is null, empty, or contains invalid characters

    • getAddonSubfolder

      @NotNull @NotNull File getAddonSubfolder(@NotNull @NotNull String addonId, @NotNull @NotNull String subfolder)
      Gets a subfolder within an addon's data folder.

      Example: getAddonSubfolder("my-addon", "cache") returns: plugins/Zentrix/addons/my-addon/cache/

      Parameters:
      addonId - The addon identifier
      subfolder - The subfolder name (can include path separators)
      Returns:
      The subfolder (created if not exists)

    • loadYamlConfiguration

      @NotNull @NotNull org.bukkit.configuration.file.YamlConfiguration loadYamlConfiguration(@NotNull @NotNull File file)
      Loads a YAML configuration from a file.

      If the file doesn't exist, returns an empty configuration.

      Parameters:
      file - The file to load
      Returns:
      The loaded configuration (never null)

    • saveYamlConfiguration

      boolean saveYamlConfiguration(@NotNull @NotNull org.bukkit.configuration.file.FileConfiguration config, @NotNull @NotNull File file)
      Saves a YAML configuration to a file.
      Parameters:
      config - The configuration to save
      file - The destination file
      Returns:
      true if saved successfully, false otherwise

    • getOrCreateConfig

      @NotNull @NotNull org.bukkit.configuration.file.YamlConfiguration getOrCreateConfig(@NotNull @NotNull String addonId, @NotNull @NotNull String fileName)
      Gets or creates a configuration file for an addon.

      This is a convenience method that:

      1. Gets the addon's data folder
      2. Creates the config file if it doesn't exist
      3. Loads and returns the configuration

      Parameters:
      addonId - The addon identifier
      fileName - The config file name (e.g., "config.yml")
      Returns:
      The loaded configuration

    • saveConfig

      boolean saveConfig(@NotNull @NotNull String addonId, @NotNull @NotNull String fileName, @NotNull @NotNull org.bukkit.configuration.file.FileConfiguration config)
      Saves an addon's configuration file.
      Parameters:
      addonId - The addon identifier
      fileName - The config file name
      config - The configuration to save
      Returns:
      true if saved successfully

    • copyDefaultConfig

      boolean copyDefaultConfig(@NotNull @NotNull String addonId, @NotNull @NotNull InputStream resourcePath, @NotNull @NotNull String destination, boolean replace)
      Copies a default configuration from an addon's resources.

      Use this to copy a default config.yml from your addon's JAR to the addon data folder if it doesn't already exist.

      Parameters:
      addonId - The addon identifier
      resourcePath - The path to the resource in the JAR
      destination - The destination file name in the addon folder
      replace - Whether to replace existing file
      Returns:
      true if copied successfully or file already exists (when replace=false)

    • getAddonFile

      @NotNull @NotNull File getAddonFile(@NotNull @NotNull String addonId, @NotNull @NotNull String fileName)
      Gets a file from an addon's data folder.
      Parameters:
      addonId - The addon identifier
      fileName - The file name or relative path
      Returns:
      The file object (may not exist yet)

    • addonFileExists

      boolean addonFileExists(@NotNull @NotNull String addonId, @NotNull @NotNull String fileName)
      Checks if a file exists in an addon's data folder.
      Parameters:
      addonId - The addon identifier
      fileName - The file name or relative path
      Returns:
      true if the file exists

    • deleteAddonFile

      boolean deleteAddonFile(@NotNull @NotNull String addonId, @NotNull @NotNull String fileName)
      Deletes a file from an addon's data folder.
      Parameters:
      addonId - The addon identifier
      fileName - The file name or relative path
      Returns:
      true if deleted successfully or file didn't exist

    • listAddonFiles

      @NotNull @NotNull String[] listAddonFiles(@NotNull @NotNull String addonId)
      Lists all files in an addon's data folder.
      Parameters:
      addonId - The addon identifier
      Returns:
      Array of file names (empty if folder doesn't exist or is empty)

    • listAddonFiles

      @NotNull @NotNull String[] listAddonFiles(@NotNull @NotNull String addonId, @NotNull @NotNull String subfolder)
      Lists all files in a subfolder of an addon's data folder.
      Parameters:
      addonId - The addon identifier
      subfolder - The subfolder path
      Returns:
      Array of file names (empty if folder doesn't exist or is empty)

    • getZentrixConfig

      @NotNull @NotNull Optional<org.bukkit.configuration.file.YamlConfiguration> getZentrixConfig(@NotNull @NotNull String configName)
      Gets a read-only copy of a Zentrix configuration file.

      Available config names:

      • "settings" - General plugin settings
      • "phases" - Game phase configurations
      • "game-types" - Game mode configurations
      • "teams" - Team configurations
      • "classes" - Player class configurations
      • "currency" - Currency system configuration
      • "broadcasts" - Broadcast message configurations

      Note: These are read-only snapshots. Modifications won't affect the actual plugin configuration.

      Parameters:
      configName - The config name (without .yml extension)
      Returns:
      The configuration, or empty if not found

    • getZentrixConfigValue

      @Nullable @Nullable Object getZentrixConfigValue(@NotNull @NotNull String configName, @NotNull @NotNull String path)
      Gets a value from a Zentrix configuration file.

      Convenience method for quick config value access.

      Parameters:
      configName - The config name (without .yml extension)
      path - The configuration path
      Returns:
      The value, or null if not found

    • getZentrixConfigString

      @NotNull @NotNull String getZentrixConfigString(@NotNull @NotNull String configName, @NotNull @NotNull String path, @NotNull @NotNull String defaultValue)
      Gets a string value from a Zentrix configuration file.
      Parameters:
      configName - The config name
      path - The configuration path
      defaultValue - Default value if not found
      Returns:
      The string value or default

    • getZentrixConfigInt

      int getZentrixConfigInt(@NotNull @NotNull String configName, @NotNull @NotNull String path, int defaultValue)
      Gets an int value from a Zentrix configuration file.
      Parameters:
      configName - The config name
      path - The configuration path
      defaultValue - Default value if not found
      Returns:
      The int value or default

    • getZentrixConfigBoolean

      boolean getZentrixConfigBoolean(@NotNull @NotNull String configName, @NotNull @NotNull String path, boolean defaultValue)
      Gets a boolean value from a Zentrix configuration file.
      Parameters:
      configName - The config name
      path - The configuration path
      defaultValue - Default value if not found
      Returns:
      The boolean value or default