How does the library handle breaking changes(examples provided)?

[DavidTheExplorer]

Hello, the library looks awesome and I want to start using it, but I do have an important question... Imagine a plugin whose version is 1, and it created the following config:

Settings:
    # How much money is given to every player on the winner team
    Reward: 100

Everything is working well.\ After some time I want to release version 2 which not only rewards the top 3 players, but also each one gets a different amount of money:

Settings:
    # The rewards in decreasing order(first place gets the first amount, second place the second, etc)
    Rewards:
        - 100
        - 70
        - 50

Notice that:

• Reward was renamed to Rewards
• Rewards is now a list instead of a field

My question is how does the library handle this breaking change? What if the user doesn't specify a number to neither configs - does the library throw a descriptive error message, returns a default value, or ignores the setting(if it's within a list)?\ \ I'm asking these questions because my plugin is exactly in this situation and without clear answers I can't use your library... Thank you!

[Exlll]

Hey there!

I assume you have some basic setup that looks like this (or the equivalent that uses records):

@Configuration
public static final class Config {
    private Settings settings = new Settings();
}

@Configuration
public static final class Settings {
    @Comment("How much money...")
    private int reward = 100; // default value
}

and that you create and load the configuration using:

Path path = Paths.get("/tmp/config.yml");
Config config = YamlConfigurations.update(path, Config.class);

What you can do is remove some field and add a field with a different name:

@Configuration
public static final class Settings {
    @Comment("How much money...")
    private List<Integer> rewards = List.of(100, 70, 50); // default value
}

This is supported and the changes will be reflected in your configuration file when you call update. However, the previously set value(s) will not be carried over. That means that the new field will have its value set to the default value you assigned to it and the old field will simply be removed.

Just changing the type of a field without changing its name is currently not supported and will result in a type mismatch when loading the config, hence throwing an exception. (From perspective of this library, this case is the same as somebody setting a configuration value to a string while your class definition defines and integer or some other type.)

The exception thrown when somebody misconfigures the configuration file is hopefully detailed enough let one figure out where the problem is. For example, the exception that is thrown when somebody changes the first value in the list to a string looks like this:

de.exlll.configlib.ConfigurationException: Deserialization of value '{rewards=[SOME STRING, 70, 50]}' with type 'class java.util.LinkedHashMap' for field 'private de.exlll.configlib.ExampleTest$Settings de.exlll.configlib.ExampleTest$Config.settings' failed.
    ... 77 more
Caused by: de.exlll.configlib.ConfigurationException: Deserialization of value '[SOME STRING, 70, 50]' with type 'class java.util.ArrayList' for field 'private java.util.List de.exlll.configlib.ExampleTest$Settings.rewards' failed.
The type of the object to be deserialized does not match the type the deserializer expects.
    ... 77 more
Caused by: java.lang.ClassCastException: class java.lang.String cannot be cast to class java.lang.Number (java.lang.String and java.lang.Number are in module java.base of loader 'bootstrap')
    ... 80 more

What happens when a user doesn't define a value for a field is discussed in the Handling of missing and null values section.

---

I've been thinking about adding some versioning functionality that allows both of these cases: Changing the type of a field while allowing to carry over old values. But because this feature hasn't been requested yet, I haven't spent time on implementing it.

If you have any suggestions for improvements or would like any functionality to be added, let me know!

[Exlll]

Closing this issue since there are no further questions from its creator.