Package dev.itsharshxd.zentrix.api.data

Interface DataService

public interface DataService
Manages Zentrix data folders and addon configurations.

Addons can use it 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 or create the addon's data folder
 File myAddonFolder = dataService.getAddonDataFolder("my-addon");

 // Load a config file from the addon folder
 File configFile = new File(myAddonFolder, "config.yml");
 FileConfiguration config = dataService.loadYamlConfiguration(configFile);

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

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

Directory layout

 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()
      Returns the main Zentrix plugin data folder.

      This is the root folder for Zentrix data. Addons should generally use getAddonDataFolder(String) instead.

      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()
      Returns the root folder for addon data.

      The folder is plugins/Zentrix/addons/.

      Returns:
      The addons data folder root

    • getAddonDataFolder

      @NotNull @NotNull File getAddonDataFolder(@NotNull @NotNull String addonId)
      Returns the dedicated data folder for an addon, creating it if needed.

      The folder is plugins/Zentrix/addons/{addonId}/.

      The folder is created when it does not 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 method:

      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)
      Returns 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. Changes do not affect the plugin's 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)
      Returns a value from a Zentrix configuration file.

      Use this 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