1. Quick Start

Add the Dependency

Maven

<project>
    <repositories>

        <repository>
            <!-- Using Maven Central Repository for secure and stable updates, though synchronization might be needed. -->
            <id>maven</id>
            <name>Maven Central</name>
            <url>https://repo1.maven.org/maven2</url>
        </repository>

        <repository>
            <!-- Using GitHub dependencies for real-time updates, configuration required (recommended). -->
            <id>configured</id>
            <name>GitHub Packages</name>
            <url>https://maven.pkg.github.com/CarmJos/configured</url>
        </repository>

    </repositories>
</project>

<project>
    <dependencies>
        <!-- Basic implementation part, requiring custom implementation of “Provider” and “Wrapper”. -->
        <dependency>
            <groupId>cc.carm.lib</groupId>
            <artifactId>configured-core</artifactId>
            <version>[LATEST RELEASE]</version>
            <scope>compile</scope>
        </dependency>

        <!-- YAML file-based implementation, compatible with all Java environments. -->
        <dependency>
            <groupId>cc.carm.lib</groupId>
            <artifactId>configured-yaml</artifactId>
            <version>[LATEST RELEASE]</version>
            <scope>compile</scope>
        </dependency>

        <!-- JSON file-based implementation, compatible with all Java environments. -->
        <dependency>
            <groupId>cc.carm.lib</groupId>
            <artifactId>configured-gson</artifactId>
            <version>[LATEST RELEASE]</version>
            <scope>compile</scope>
        </dependency>

    </dependencies>
</project>

Gradle

For Kotlin DSL:

repositories {

    // Using Maven Central Repository for secure and stable updates, though synchronization might be needed.
    mavenCentral()

    // Using GitHub dependencies for real-time updates, configuration required (recommended).
    maven("https://maven.pkg.github.com/CarmJos/configured")

}

dependencies {

    // Basic implementation part, requiring custom implementation of “Provider” and “Wrapper”.
    implementation("cc.carm.lib:configured-core:[LATEST RELEASE]")

    // YAML file-based implementation, compatible with all Java environments.
    implementation("cc.carm.lib:configured-yaml:[LATEST RELEASE]")

    // JSON file-based implementation, compatible with all Java environments.
    implementation("cc.carm.lib:configured-gson:[LATEST RELEASE]")

}

For Groovy DSL:

repositories {

    // Using Maven Central Repository for secure and stable updates, though synchronization might be needed.
    mavenCentral()

    // Using GitHub dependencies for real-time updates, configuration required (recommended).
    maven { url 'https://maven.pkg.github.com/CarmJos/configured' }

}

dependencies {

    // Basic implementation part, requiring custom implementation of “Provider” and “Wrapper”.
    implementation "cc.carm.lib:configured-core:[LATEST RELEASE]"

    // YAML file-based implementation, compatible with all Java environments.
    implementation "cc.carm.lib:configured-yaml:[LATEST RELEASE]"

    // JSON file-based implementation, compatible with all Java environments.
    implementation "cc.carm.lib:configured-gson:[LATEST RELEASE]"

}

Create a Configuration Interface

For the demo configuration file, we create a corresponding Java interface named DemoConfig:

@ConfigPath(root = true) // To define this as the root configuration interface
public interface DemoConfig extends Configuration { // "extends Configuration" required
    @HeaderComments("Database configuration") // header comment(s)
    interface DATABASE extends Configuration { // as section, "extends Configuration" required
        /*
         * field name: "host"
         * default value: "localhost"
         * inline comment: "Database host address"
         *
         * preview: "host: localhost # Database host address"
         */
        @InlineComment("Database host address") // inline comment
                ConfiguredValue<String> HOST = ConfiguredValue.of("localhost");

        @InlineComment("Database port")
        ConfiguredValue<Integer> PORT = ConfiguredValue.of(3306);

        ConfiguredValue<String> USERNAME = ConfiguredValue.of("root");

        ConfiguredValue<String> PASSWORD = ConfiguredValue.of("password");

        ConfiguredValue<String> NAME = ConfiguredValue.of("my_database");

        interface POOL extends Configuration {
            ConfiguredValue<Integer> MAX_COLLECTIONS = ConfiguredValue.of(10);

            ConfiguredValue<Integer> MIN_COLLECTIONS = ConfiguredValue.of(1);

            ConfiguredValue<Long> TIMEOUT = ConfiguredValue.of(3000L);
        }
    }

    interface SERVER extends Configuration {
        ConfiguredValue<Integer> PORT = ConfiguredValue.of(8080);

        ConfiguredValue<Boolean> SSL_ENABLED = ConfiguredValue.of(false);

        interface SSL extends Configuration {
            ConfiguredValue<String> KEY_PATH = ConfiguredValue.of("/path/to/keystore");

            ConfiguredValue<String> KEY_PASSWORD = ConfiguredValue.of("keystore_password");
        }
    }

    interface LOGGING extends Configuration {
        ConfiguredValue<String> LEVEL = ConfiguredValue.of("INFO");

        ConfiguredValue<String> FILE = ConfiguredValue.of("/var/logs/app.log");
    }
}

In most case, we use "ConfiguredSomething" to hold the specific values. And in those classes, we usually have static build functions like:

• of(Instance) to create a new instance with a default value.
• with(Type) to create a new instance with a specific type.
• builderOf(Type) to create a builder for complex types.
• ... and more different methods for different types.

Create a Holder

void onAppLoad(){
    // Use YAML for example.
    ConfigurationHolder<YAMLSource> holder = YAMLConfigFactory.from("/path/to/config.yml")
            .indent(2) // optional, 2 is default
            // and more...
            .build();
}

Initialize the Configuration

void onAppStart(){
    holder.initialize(DemoConfig.class);
}

Just use it

void foo(){

    // get the original value in the config. (with no defaults)
    String host = DemoConfig.DATABASE.HOST.get();

    //  get the original value (with Optional<>) in the config. (with no defaults)
    Optional<@Nullable Integer> optMaxConnections = DemoConfig.DATABASE.POOL.MAX_COLLECTIONS.optional();

    // get the resolved value (with defaults if not set in config) in the config.
    Integer port = DemoConfig.DATABASE.PORT.resolve();
    
}

reload from config file:

void reload(){
    try{
        holder.reload();
    }catch(Exception e){
        throw new RuntimeException(e);
    }
}

modify and save:

void set(){
    DemoConfig.SERVER.PORT.set(8081);
    try{
        holder.save();
    }catch(Exception e){
        throw new RuntimeException(e);
    }
}