ConfigAPI

The ConfigAPIv2 will be deprecated and replaced with ConfigAPIv3 with System v0.4.12-dev.

After the release of ConfigAPIv3 a new documentation will follow.

Overview

The ConfigAPI is a utility class designed to simplify the management of YAML configuration files in a Spigot plugin. It provides functionality for creating, loading, saving, and modifying configuration files, including player-specific configurations and inline comments.

---

Initialization

Constructors

• ConfigAPI(String path, String fileName, Plugin plugin)

  Creates or loads a configuration file at the specified path. If the file does not exist, it is created with default settings.

  Parameters:

  • path (String): The directory path where the configuration file is located.

  • fileName (String): The name of the configuration file.

  • plugin (Plugin): The plugin instance.

• ConfigAPI(String path, String fileName, Runnable callback, Plugin plugin)

  Same as above, but with an additional callback that runs after creating a new configuration file.

  Parameters:

  • path (String): The directory path where the configuration file is located.

  • fileName (String): The name of the configuration file.

  • callback (Runnable): Code to execute after creating a new configuration file.

  • plugin (Plugin): The plugin instance.

---

Static Methods

getConig(String path, String fileName, Plugin plugin)

Initializes and retrieves a singleton instance of the ConfigAPI. Subsequent calls return the existing instance.

Parameters:

• path (String): The configuration directory.

• fileName (String): The configuration file name.

• plugin (Plugin): The plugin instance.

Returns:

• ConfigAPI: The singleton instance of the class.

getConfig()

Retrieves the existing instance of ConfigAPI. Throws an exception if not initialized.

Returns:

• ConfigAPI: The singleton instance of the class.

Throws:

• IllegalStateException: If the ConfigAPI has not been initialized.

---

Core Methods

File Management

• save(): Writes the in-memory configuration to the file, preserving inline comments.

• reloadConfig(): Reloads the configuration from the file.

• exists(): Checks if the configuration file exists.

  Returns:

  • boolean: true if the file exists, false otherwise.

• delete(): Deletes the configuration file if it exists.

Access and Modification

• get(): Retrieves the FileConfiguration object for the main configuration file.

• setInlineComments(String path, List<String> comments): Adds inline comments for a specified configuration path.

  Parameters:

  • path (String): The configuration path.

  • comments (List): The list of comments to add.

• setStringList(String path, List<String> list): Sets a list of strings at the specified path.

• getStringList(String path): Retrieves a list of strings from the specified path.

  Returns:

  • List<String>: The string list from the specified path.

• addDefaultStringList(String path, List<String> defaultList): Sets a default string list if the path does not already exist.

Version Management

• checkVersion(String currentVersion): Logs a warning if the configuration version does not match the provided version.

  Parameters:

  • currentVersion (String): The expected version of the configuration.

---

Player-Specific Configuration

Loading and Saving

• getPlayerConfig(Player player): Retrieves or creates a YAML configuration file for a specific player.

  Parameters:

  • player (Player): The player instance.

  Returns:

  • YamlConfiguration: The player's configuration file.

• saveModifiedConfigs(): Saves only the configurations marked as modified.

• setPlayerConfigModified(Player player): Marks a player's configuration as modified for saving.

Access and Modification

• setPlayerConfigValue(Player player, String path, Object value): Sets a value in a player's configuration and marks it as modified.

  Parameters:

  • player (Player): The player instance.

  • path (String): The configuration path.

  • value (Object): The value to set.

• getPlayerConfigValue(Player player, String path, T defaultValue): Retrieves a value from a player's configuration with a fallback default.

  Parameters:

  • player (Player): The player instance.

  • path (String): The configuration path.

  • defaultValue (T): The default value to return if the path does not exist.

  Returns:

  • T: The retrieved value.

Locations

• setPlayerLocation(Player player, String path, Location location): Stores a player's location in their configuration file.

• getPlayerLocation(Player player, String path): Retrieves a player's location from their configuration file.

  Returns:

  • Location: The retrieved location or null if not set.

---

Location Management

• setLocation(String path, Location location): Sets a location in the main configuration file.

• getLocation(String path): Retrieves a location from the main configuration file.

  Returns:

  • Location: The retrieved location or null if not set.

---

Utility Methods

• checkVersion(String currentVersion): Checks the configuration file's version against the provided version string. Logs a warning if they do not match.

• setStringList(String path, List<String> list): Sets a list of strings in the configuration at the specified path.

• getStringList(String path): Retrieves a list of strings from the configuration file.

---

Notes

• Ensure ConfigAPI is initialized using getConig before calling other methods.

• Supports inline comments, player-specific configurations, and location handling for better organization and usability.

• Automatically creates missing files and directories when saving configurations.

---

Examples

Initialize and Use

// Initialize ConfigAPI
ConfigAPI configAPI = ConfigAPI.getConig("plugins/MyPlugin", "config.yml", plugin);

// Set and save a value
configAPI.get().set("example.path", "Hello World!");
configAPI.save();

// Retrieve a value
String value = configAPI.get().getString("example.path");
System.out.println(value);

Inline Comments

// Add inline comments
configAPI.setInlineComments("example.path", Arrays.asList("This is an example", "Set to a greeting"));

Player-Specific Configuration

// Set a player's configuration value
Player player = Bukkit.getPlayer("playerName");
configAPI.setPlayerConfigValue(player, "example.key", "value");

// Retrieve a value with a default
String playerValue = configAPI.getPlayerConfigValue(player, "example.key", "default");
System.out.println(playerValue);

Handling Locations

// Save a location
Location loc = player.getLocation();
configAPI.setLocation("spawn", loc);

// Retrieve a location
Location spawnLoc = configAPI.getLocation("spawn");
player.teleport(spawnLoc);

How to hook into ConfigAPI

Configurations.java

import de.isolveproblems.system.api.ConfigAPI;

public class ConfigurationMessages {

    private final YourProject yourProject = YourProject.getPlugin(YourProject.class);

    public ConfigAPI config;

    public void getConfig() {
        config = new ConfigAPI("plugins/YourProject", "config.yml", yourProject);
        config.getConfig().addDefault("config.prefix", "&c[YourProject]");
        config.saveConfig();
    }
}

Configuration in Main Class

import de.isolveproblems.system.api.SettingsAPI;

public class YourProject extends JavaPlugin {

    private YourProject yourProject;
    private Configuration configHandler;

    @Override
    public void onEnable() {
        this.yourProject = this;
        this.configHandler= new ConfigurationHandler();
        
        this.load();
    }

    @Override
    public void onDisable() {

    }

    public YourProject getYourProject() {
        return this.yourProject;
    }
    
    public void load() {
        this.getConfiguration().getConfig();
    }
        
    public Configuration getConfiguration() {
        return this.configHandler;
    }
}

How to use ConfigAPI in your classes

import your.mainclass.project-name

public class YourCommand implements CommandExecutor {

 private final YourProject yourProject = YourProject.getPlugin(YourProject.class);
 
 @Override
 public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
      Player player = (Player) sender;  
      
      if(args.length == 0) {
           player.sendMessage(yourProject.getConfiguration().get().getConfig().getString("config.prefix"));
           //do stuff here
      }
      return false;
 }