Defining properties

Each configurable value is represented as a property in ConfigMe. As we saw in the Technical Overview, properties are defined as constants in classes that implement the SettingsHolder interface:

public class TitleConfig implements SettingsHolder {

    public static final Property<String> TITLE_TEXT =
        new StringProperty("title.text", "-Default-");

    public static final Property<Integer> TITLE_SIZE =
        new IntegerProperty("title.size", 10);

    private TitleConfig() {
        // prevent instantiation
    }
}

Your configuration's properties can be put into multiple settings holder classes.

Defining properties

Properties are usually defined by statically imported methods of PropertyInitializer. Each property defines the path at which it's located in the configuration file, along with the default value to fall back to in case it's not available in the configuration file.

import static ch.jalu.configme.properties.PropertyInitializer.newProperty;

public class TitleConfig implements SettingsHolder {

    public static final Property<String> TITLE_TEXT =
        newProperty("title.text", "-Default-");

    public static final Property<Integer> TITLE_SIZE =
        newProperty("title.size", 10);

    private TitleConfig() {
        // prevent instantiation
    }
}

This produces an initial YML configuration that looks as such:

title:
    text: '-Default-
    size: 10

Specifying comments

Comments can be specified for each property, as well as any paths in between.

On properties

Comments are added to properties with the @Comment annotation:

public class TitleConfig implements SettingsHolder {

    @Comment("The text the title will have")
    public static final Property<String> TITLE_TEXT =
        newProperty("title.text", "-Default-");

    @Comment({
      "The font size of the title.",
      "The default is 10."
    })
    public static final Property<Integer> TITLE_SIZE =
        newProperty("title.size", 10);

    private TitleConfig() {
        // prevent instantiation
    }
}

Whenever the configuration is saved to the file, it will generate something like this:

title:
    # The text the title will have
    text: '-Default-'
    # The font size of the title.
    # The default is 10.
    size: 10

On sections

Define comments for intermediate paths by overriding the method registerComments from the SettingsHolder interface.

public class TitleConfig implements SettingsHolder {

    public static final Property<String> TITLE_TEXT =
        newProperty("title.text", "-Default-");

    public static final Property<Integer> TITLE_SIZE =
        newProperty("title.size", 10);

    private TitleConfig() {
        // prevent instantiation
    }

    @Override
    public void registerComments(CommentsConfiguration conf) {
        conf.setComment("title", "This section defines the title that will be displayed");
    }
}

Whenever the configuration is saved to the file, it will generate something like this:

# This section defines the title that will be displayed
title:
    text: '-Default-'
    size: 10

You can add a header of comments by setting comments for the path of empty string:

    @Override
    public void registerComments(CommentsConfiguration conf) {
        conf.setComment("",
            "Configuration file for my application", "For help, please visit https://example.org");
    }

Available property types

Many property types come out of the box. Typically you create them with PropertyInitializer.

As a non-exhaustive list, the following property types are available:

• String property
• Number properties (integer, double)
• Boolean property
• Enum property
• Bean property (map to a JavaBean)

Then, with a component type of any of the above:

• List property
• Map property (where the key type is always String and the value type is configurable)
• Array property

Property hierarchy