Tutorial Easily manage configuration files

Discussion in 'Resources' started by teej107, Nov 12, 2015.

Thread Status:
Not open for further replies.
  1. Offline

    teej107

    YAML! It's Bukkit's chosen file format for plugins to store its information. When I first started using the Bukkit API, it took me too long to figure out how to use the Configuration API. This Configuration API Reference page helped a lot. Using the Bukkit's Config API is a lot like using a Map with a save, load and a few fancy getter methods (It does use a LinkedHashMap to handle the data).

    Here are the JavaDocs links for some of the commonly used classes in the Configuration API
    Now to tell you the truth, a lot of code that I've seen on the forums that handles configs can be very prone to mistakes and/or violates DRY. This tutorial will show you how to manage the plugin's config and custom configurations with ease.

    ____________________________________________________________________
    Clearing up a few misunderstandings
    ____________________________________________________________________
    Editing your config with style!

    Editing the plugin's config.yml or a custom one is very much the same. However when using a custom config, please please please use a separate class to represent the custom config. It'll make them easier to manage and is OOP appropriate.

    Creating a custom config class can be easily done following the steps found in Bukkit's Configuration API Reference or you may use a starter template I made that can be found here.

    To start, the class with the config could either be your JavaPlugin class or a custom config class. They should already have a FileConfiguration object that is obtainable inside.
    For the sake of this tutorial, I will refer to the FileConfiguration as "config" for either getConfig() in JavaPlugin or the value returned by loadConfiguration(File).

    I like to create a final String field for each path in the config. I will assign the String field value a path in the config.

    Code:
        private static final String HOME = "home";
        private static final String WELCOME_MESSAGE = "welcome-message";
        private static final String KILLS = "kills";
        private static final String SOME_STRING_LIST = "some-string-list";
    Now to reference a path in the config, we can just use the String constants we just created.
    Next we need to create getters to get the value from the path!

    Code:
        public World getHome()
        {
            return Bukkit.getWorld(config.getString(HOME));
        }
    
        public String getWelcomeMessage()
        {
            return ChatColor.translateAlternateColorCodes('&', config.getString(WELCOME_MESSAGE));
        }
    
        public int getKills()
        {
            return config.getInt(KILLS);
        }
    
        public List<String> getSomeStringList()
        {
            return config.getStringList(SOME_STRING_LIST);
        }
    Note: Make sure a NullPointerException won't happen when converting values to a different Object. One way prevent this is by adding default values.

    Now we can simply get values from the config!
    What if you need to set values though in code? Well setters can take care of that!

    Code:
        public void setHome(World world)
        {
            config.set(HOME, world.getName());
        }
    
        public void setWelcomeMessage(String s)
        {
            config.set(WELCOME_MESSAGE, s);
        }
    
        public void setKills(int i)
        {
            config.set(KILLS, i);
        }
    
        public void setSomeStringList(List<String> list)
        {
            config.set(SOME_STRING_LIST, list);
        }
    Now you can simply set values in the config by code!

    These methods of setting and getting values from the config take advantage of OOP and help reduce stupid mistakes that can be made when dealing with configurations.

    The code I have shown as an example is part of a custom configuration class that can be found here. This can be easily fitted for JavaPlugin's config. Always remember to save the config!

    If you think I missed something or have some input on the tutorial, please leave a comment. I appreciate constructive criticism.
     
    Last edited: Nov 30, 2015
  2. Offline

    Mrs. bwfctower

    I think it would also be worthy to put something about how saving the config will remove comments, because some people might not know what's up with that.

    But great tutorial, lots of good info xD
     
    kaif21 and teej107 like this.
Thread Status:
Not open for further replies.

Share This Page