How to work with Configuration Files

Welcome to BearCommands Wiki!
In this section we will look into working with default Configuration Files, like config.yml and messages.yml, as well as custom ones. I will be assuming that you followed the how to start guide and that your plugin Main Class extends an instance of IBearPlugin.

Contents
How does BearCommands handles Configuration Files
The config.yml
The messages.yml
Configuration checking
Custom configuration files

How does BearCommands handles Configuration Files

Because of the necessity for cross-compatibility across platforms, BearCommands uses a wrapper class called Configuration which might contain Bukkit FileConfiguration, BungeeCord Configuration or a Map that represents the objects inside a YAML file. This class provides various methods taken from the FileConfiguration class like getString, isIntegerList, getItemStack and more. For the sake of uniformity, we will keep referring to this class while taking about configurations.

The config.yml

If you have correctly extended a BearPlugin class in your plugin Main Class, the config.yml loading will be automatically handled: if among your resources there is a config.yml file, this will be automatically saved in the folder plugins/<plugin-name>/config.yml. By default, this file will be checked and corrected if there are missing or wrong options. While this might be the expected behaviour, for some plugin which require the user to add custom options (e.g. ranks) this will be a problem, because all removed content will be replaced. To avoid this, you will have to edit the loadConfig method:

/* ... */
    @Override
    public void loadConfig() throws Exception {
        loadGeneral("config.yml", false); // Set to false to disable checking and auto-correction.
        reloadConfig(); // Only required if on Bukkit.
    }
/* ... */

The loaded config might be accessed using the getConfiguration method, which returns a Configuration type object for every platform.

The messages.yml

The messages.yml file works on the same lines as the config.yml. For the sake of non-repetition, I redirect you to The config.yml, but keep in mind that the loading method is called loadLang while the get is getLang.

Configuration checking

BearCommands provides a system to automatically check and correct YAML files. You can access it by using the ConfigUtils class which provides various static functions to work with. The most important one is the loadConfiguration:

    /**
     * Loads a YAML file from the plugin/<plugin-name> folder into memory.
     * If the file does not exist, it will be created by copying the content from
     * the resources of the .jar file.
     * @param plugin: an instance of the main plugin class.
     * @param dataFolder: the plugin/<plugin-name> folder.
     * @param configName: the name of the YAML file in the resources.
     * @param resultFile: the name of the YAML file in the plugin/<plugin-name> folder.
     * @param autoFix: if true, this option will trigger the automatic fix if the file requires it.
     *
     * @return an instance of Configuration, wrapping the loaded configuration file.
     */
    public static Configuration loadConfiguration(IBearPlugin<?> plugin, File dataFolder, 
                                                  String configName, String resultFile, boolean autoFix) throws IOException {
        /* ... */
    }

This function is responsible for loading the default config.yml and messages.yml, but can be used for any configuration required. If errors are found, they will be logged as warnings in the console. If autoFix is true, the system will try to correct this mistake, by saving a backup of the previous file and overriding them.

Custom configuration files

To create a custom configuration file, you can follow the guidelines of BearCommands, by creating new methods and overriding the loadAll method:

package it.fulminazzo.testplugin;

import it.angrybear.Bukkit.SimpleBearPlugin;
import it.angrybear.Objects.Configurations.Configuration;

public class TestPlugin extends SimpleBearPlugin {
    // NOTE: the Configuration class should be the one provided by BearCommands.
    private Configuration myCustomConfiguration;

    @Override
    public void loadAll() throws Exception {
        // It is suggested to first load the config.yml and messages.yml file.
        super.loadAll();
        loadMyCustomConfiguration();
    }

    public void loadMyCustomConfiguration() throws Exception {
        // If true, check and correct my-custom-configuration.yml.
        this.myCustomConfiguration = loadGeneral("my-custom-configuration.yml", true);
    }

    public Configuration getMyCustomConfiguration() {
        return myCustomConfiguration;
    }
}