Configuration to object mapping

[tamaro-skaljic]

Hey guys!

I like the possibility to configure my Quarkus applications through mapping configuration to objects.

How to do this

• An interface annotated with @ConfigMapping and optionally some other annotations for validation and so on.

package de.tamaroskaljic.application;

import io.smallrye.config.ConfigMapping;
import io.smallrye.config.WithDefault;

import javax.validation.constraints.Min;

@ConfigMapping(prefix = "application")
public interface Configuration {
    Passwords passwords();

    interface Passwords {
        @WithDefault("8")
        @Min(0)
        Integer minLength();

        @WithDefault("64")
        @Min(0)
        Integer maxLength();
    }
}

• some class that @Injects the Configuration. For example:

package de.tamaroskaljic.application;

import io.quarkus.test.junit.QuarkusTest;
import org.junit.jupiter.api.Test;

import javax.inject.Inject;

import static org.junit.jupiter.api.Assertions.assertEquals;

@QuarkusTest
public class ConfigurationTest {
    @Inject
    Configuration configuration;

    @Test
    public void minAndMaxLengthOfPasswords() {
        assertEquals(8, configuration.passwords().minLength());
        assertEquals(64, configuration.passwords().maxLength());
    }
}

Unfortunately I've encountered some drawbacks.

• I can retrieve only configuration values, not the keys.

  • So it's not possible to use them e.g.
    • in a message of an exception (for faster troubleshooting) or
    • to alert through a failed assertion during tests when a key changes (for 3rd-party compatibility reasons).
  • Not being able to access the keys, and therefore creating a class with a bunch of static strings, would violate the DRY & SSOT principles and requires a lot of manually created boilerplate code. It would be more convenient to wrap each ConfigurationPropery in e.g. a java.util.AbstractMap.SimpleEntry<K,V> or java.lang.Record to access both keys and values.

• I didn't find a way to change the configuration properties during runtime.

• Values resolved via the @ConfigMapping annotation cannot be accessed from a static context.

  • So it's not possible to use them e.g.
    • in annotations (especially you can't configure JPA validation annotations) and
    • in all other static contexts. Even not when you annotate it with @StaticInitSafe.
  • The only solution for accessing the configuration in static contexts that i've found is to access it programmatically - which is not very practical.
  • I wish I could annotate a class like an interface and instead of instance methods, static members are provided.

Just like this

@ConfigMapping(prefix = "application")
public final class Configuration {
    static Passwords passwords;

    public static final class Passwords {
        @WithDefault("8")
        @Min(0)
        static Integer minLength;

        @WithDefault("64")
        @Min(0)
        static Integer maxLength;
    }
}

What do you think of my ideas? Do you know any solutions for them? Did I miss something? Or are my thoughts all garbage? Feel free to join the discussion.

[radcortez]

• I can retrieve only configuration values, not the keys.

There are some ways to retrieve the keys programmatically:

# retrieves all keys
ConfigProvider.getInstance().getPropertyNames(); 

# retrieves all keys from a mapping class
io.smallrye.config.ConfigMappings#getProperties(ConfigClassWithPrefix)

• So it's not possible to use them e.g.

  • in a message of an exception (for faster troubleshooting) or

Mappings are populated at the application start. If there is an error in loading, exceptions are thrown with the proper key names that caused the issue.

* to alert through a failed assertion during tests when a key changes (for 3rd-party compatibility reasons).

What exactly do you want to test here? Can you give me an example?

• Not being able to access the keys, and therefore creating a class with a bunch of static strings, would violate the DRY & SSOT principles and requires a lot of manually created boilerplate code. It would be more convenient to wrap each ConfigurationPropery in e.g. a java.util.AbstractMap.SimpleEntry<K,V> or java.lang.Record to access both keys and values.

The problem is that not every key is static. We support Map, meaning that a segment of the configuration key name is dynamic to represet the Map key. In Collections, you can have indexed values in the format [*]. Yes, it could be possible, just not something that we have seen people asking for until now.

• I didn't find a way to change the configuration properties during runtime.

Configuration is immutable, and we don't support reloading it. We had that discussion many times and while we understand the use case, we also think it raises a lot of issues. For instance, how do we deal with changing a jdbc connection?

• Values resolved via the @ConfigMapping annotation cannot be accessed from a static context.

  • So it's not possible to use them e.g.

    • in annotations (especially you can't configure JPA validation annotations) and

The use case is definitely interesting. This would require an additional level of integration between Config and Bean Validation. Maybe we can think of a way to make this generic to be read from any annotation. Just not sure how useful that would be. A lot of these annotations are read during the build and code is generated during compile time, so any configuration change would require a rebuild of the application.

* in all other static contexts. Even not when you annotate it with [@StaticInitSafe](https://quarkus.io/guides/config-mappings#static-init).

@StaticInitSafe is intended to mark Config classes to be initialized during static init. For instance, think on a database ConfigSource. This source cannot start during static init, because the database services only become available on runtime.

• The only solution for accessing the configuration in static contexts that i've found is to access it programmatically - which is not very practical.

Yes, you can either inject it in CDI contexts or get it programmatically. How would you like to access it in static contexts?

• I wish I could annotate a class like an interface, and instead of instance methods, static members are provided.

We had to go with instances because a mapping or nested mapping can represent a different root, but with the same keys of configuration.

Just like this
What do you think of my ideas? Do you know any solutions for them? Did I miss something? Or are my thoughts all garbage? Feel free to join the discussion.

Thank you for the ideas. I've tried to address all the points. We are more than happy to keep improving the configuration mechanism. Mappings are recent (maybe 1 year old now), and they are only becoming stable and mainstream in the last couple of months. We are giving some time for people to adjust and migrate.

There is also a Jakarta Config specification group: https://github.com/eclipse-ee4j/config, working right now to make a configuration standard, where some of these ideas were also discussed. I recommend you to join if possible and help us with that :)