Config Mappings

With SmallRye Config Mappings, it is possible to group multiple configuration properties in a single interface that share the same prefix.

Usage

A Config Mapping requires an interface with minimal metadata configuration:

@ConfigMapping(prefix = "server")
interface Server {
    String host();

    int port();
}

The Server interface is able to map configurations with the name server.host into the Server.host() method and server.port into Server.port() method. The configuration property name to lookup is built from the prefix, and the method name with . (dot) as the separator.

Registration

Registration of Config Mapping aware interface happens automatically in CDI aware environments with the @ConfigMapping annotation. In non-CDI environments, the Config Mapping may be registered via SmallRyeConfigBuilder#withMapping. In this case, the @ConfigMapping is completely optional.

Retrieval

To retrieve the Config Mapping instance in CDI environments, a simple @Inject of the Config Mapping interface is enough:

@Inject
Server server;

static void businessMethod() {
    String host = server.host();
}

In non-CDI environments, to retrieve the Config Mapping instance, the API io.smallrye.config.SmallRyeConfig#getConfigMapping may be used:

Server server = config.getConfigMapping(Server.class);

Features

The SmallRye Config Mapping supports the following set of features:

  • Automatic conversion of the configuration type.

  • Nested Config Mapping groups.

  • Validate if configuration properties exist in the startup.

  • Support for Map, Optional and primitive types.

Additionally, the annotations @WithName, @WithDefault, @WithConverter may be used to override the default behaviours of Config Mapping interfaves.

Examples

Simple Config Mapping

interface Server {
    String host();

    int port();
}

Nested Config Mapping

interface ServerSub {
    @WithParentName
    ServerSubHostAndPort subHostAndPort();

    @WithParentName
    ServerSubName subName();
}

interface ServerSubHostAndPort {
    String host();

    int port();
}

interface ServerSubName {
    String name();
}

Types Config Mapping

public interface SomeTypes {
    @WithName("int")
    int intPrimitive();

    @WithName("int")
    Integer intWrapper();

    @WithName("long")
    long longPrimitive();

    @WithName("long")
    Long longWrapper();

    @WithName("float")
    float floatPrimitive();

    @WithName("float")
    Float floatWrapper();

    @WithName("double")
    double doublePrimitive();

    @WithName("double")
    Double doubleWrapper();

    @WithName("char")
    char charPrimitive();

    @WithName("char")
    Character charWrapper();

    @WithName("boolean")
    boolean booleanPrimitive();

    @WithName("boolean")
    Boolean booleanWrapper();
}

Optional Config Mapping

public interface Optionals {
    Optional<Server> server();

    Optional<String> optional();

    @WithName("optional.int")
    OptionalInt optionalInt();
}

Collections Config Mapping

public interface CollectionTypes {
    @WithName("strings")
    List<String> listStrings();

    @WithName("ints")
    List<Integer> listInts();
}

public interface Maps {
    @WithParentName
    Map<String, Server> server();

    Map<String, String> anotherServer();
}

Defaults Config Mapping

public interface Defaults {
    @WithDefault("foo")
    String foo();

    @WithDefault("bar")
    String bar();
}

Converter Config Mapping

public interface Converters {
    @WithConverter(FooBarConverter.class)
    String foo();
}

public static class FooBarConverter implements Converter<String> {
    @Override
    public String convert(final String value) {
        return "bar";
    }
}