# Mapping configuration to objects

With config mappings it is possible to group multiple configuration properties in a single interface that share the same prefix.

<a id="config-mappings"></a>
## `@ConfigMapping`

A config mapping requires a public interface with minimal metadata configuration and annotated with the `@io.smallrye.config.ConfigMapping` annotation.

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

    int port();
}
```

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

> [!NOTE]
> If a mapping fails to match a configuration property a `NoSuchElementException` is thrown, unless the mapped element is an `Optional`.

### Registration

When a Quarkus application starts, a config mapping can be registered twice. One time for *STATIC INIT* and a second time for *RUNTIME INIT*:

#### STATIC INIT

Quarkus starts some of its services during static initialization, and `Config` is usually one of the first things that is created. In certain situations it may not be possible to correctly initialize a config mapping. For instance, if the mapping requires values from a custom `ConfigSource`. For this reason, any config mapping requires the annotation `@io.quarkus.runtime.configuration.StaticInitSafe` to mark the mapping as safe to be used at this stage. Learn more about [registration](/guides/config-extending-support/index.md#custom-config-source) of a custom `ConfigSource`.

##### Example

```java
@StaticInitSafe
@ConfigMapping(prefix = "server")
public interface Server {
    String host();

    int port();
}
```

#### RUNTIME INIT

The *RUNTIME INIT* stage happens after *STATIC INIT*. There are no restrictions at this stage, and any config mapping is added to the `Config` instance as expected.

### Retrieval

A config mapping interface can be injected into any CDI aware bean:

```java
class BusinessBean {
    @Inject
    Server server;

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

In non-CDI contexts, use the API `io.smallrye.config.SmallRyeConfig#getConfigMapping` to retrieve the config mapping instance:

```java
SmallRyeConfig config = ConfigProvider.getConfig().unwrap(SmallRyeConfig.class);
Server server = config.getConfigMapping(Server.class);
```

### Nested groups

A nested mapping provides a way to subgroup other config properties:

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

    int port();

    Log log();

    interface Log {
        boolean enabled();

        String suffix();

        boolean rotate();
    }
}
```

**application.properties**

```properties
server.host=localhost
server.port=8080
server.log.enabled=true
server.log.suffix=.log
server.log.rotate=false
```

The method name of a mapping group acts as sub-namespace to the configurations properties.

### Overriding property names

#### `@WithName`

If a method name, or a property name do not match with each other, the `@WithName` annotation can override the method name mapping and use the name supplied in the annotation:

```java
@ConfigMapping(prefix = "server")
public interface Server {
    @WithName("name")
    String host();

    int port();
}
```

**application.properties**

```properties
server.name=localhost
server.port=8080
```

#### `@WithParentName`

The `@WithParentName` annotation allows the configuration mapping property to inherit its container name, simplifying the configuration property name required to match the mapping:

```java
@ConfigMapping(prefix = "server")
interface Server {
    @WithParentName
    ServerHostAndPort hostAndPort();

    @WithParentName
    ServerInfo info();
}

interface ServerHostAndPort {
    String host();

    int port();
}

interface ServerInfo {
    String name();
}
```

**application.properties**

```properties
server.host=localhost
server.port=8080
server.name=konoha
```

Without the `@WithParentName` the method `name()` requires the configuration property `server.info.name`. Because we use `@WithParentName`, the `info()` mapping will inherit the parent name from `Server` and `name()` maps to `server.name` instead.

#### NamingStrategy

Method names in camelCase map to kebab-case property names:

```java
@ConfigMapping(prefix = "server")
public interface Server {
    String theHost();

    int thePort();
}
```

**application.properties**

```properties
server.the-host=localhost
server.the-port=8080
```

The mapping strategy can be adjusted by setting `namingStrategy` value in the `@ConfigMapping` annotation:

```java
@ConfigMapping(prefix = "server", namingStrategy = ConfigMapping.NamingStrategy.VERBATIM)
public interface ServerVerbatimNamingStrategy {
    String theHost();

    int thePort();
}
```

**application.properties**

```properties
server.theHost=localhost
server.thePort=8080
```

The `@ConfigMapping` annotation support the following naming strategies with the following enum values:

- `KEBAB_CASE` (default) - The method name is derived by replacing case changes with a dash to map the configuration property, i.e. `theHost` maps to `the-host`.
- `VERBATIM` - The method name is used as is to map the configuration property, i.e. `theHost` maps to `theHost`.
- `SNAKE_CASE` - The method name is derived by replacing case changes with an underscore to map the configuration property, i.e. `theHost` maps to `the_host`.

### Conversions

A config mapping class support automatic conversions of all types available for conversion in `Config`:

```java
@ConfigMapping
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();
}
```

**application.properties**

```properties
int=9
long=9999999999
float=99.9
double=99.99
char=c
boolean=true
```

This is also valid for `Optional` and friends:

```java
@ConfigMapping
public interface Optionals {
    Optional<Server> server();

    Optional<String> optional();

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

    interface Server {
        String host();

        int port();
    }
}
```

In this case, the mapping won't fail if there is no configuration property to match the mapping.

#### `@WithConverter`

The `@WithConverter` annotation provides a way to set a `Converter` to use in a specific mapping:

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

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

**application.properties**

```properties
foo=foo
```

A call to `Converters.foo()` results in the value `bar`.

#### Collections ====

A config mapping is also able to map collections types `List` and `Set`:

```java
@ConfigMapping(prefix = "server")
public interface ServerCollections {
    Set<Environment> environments();

    interface Environment {
        String name();

        List<App> apps();

        interface App {
            String name();

            List<String> services();

            Optional<List<String>> databases();
        }
    }
}
```

**application.properties**

```properties
server.environments[0].name=dev
server.environments[0].apps[0].name=rest
server.environments[0].apps[0].services=bookstore,registration
server.environments[0].apps[0].databases=pg,h2
server.environments[0].apps[1].name=batch
server.environments[0].apps[1].services=stock,warehouse
```

The `List` or `Set` mappings can use [indexed properties](/guides/config-reference/index.md#indexed-properties) to map configuration values in mapping groups. For collection with simple element types like `String`, their configuration value is a comma separated string.

> [!NOTE]
> Only the `List` mapping can maintain element order. Hence, with `Set` mappings the element order is not maintained from the configuration files but is random.

#### Maps ====

A config mapping is also able to map a `Map`:

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

    int port();

    Map<String, String> form();
}
```

**application.properties**

```properties
server.host=localhost
server.port=8080
server.form.login-page=login.html
server.form.error-page=error.html
server.form.landing-page=index.html
```

The configuration property needs to specify an additional name to act as the key. In this case the `form()` `Map` will contain three elements with the keys `login-page`, `error-page` and `landing-page`.

It also works for groups:

```java
@ConfigMapping(prefix = "server")
public interface Servers {
    @WithParentName
    Map<String, Server> allServers();
}

public interface Server {
    String host();

    int port();

    String login();

    String error();

    String landing();
}
```

**application.properties**

```properties
server."my-server".host=localhost
server."my-server".port=8080
server."my-server".login=login.html
server."my-server".error=error.html
server."my-server".landing=index.html
```

In this case the `allServers()` `Map` will contain one `Server` element with the key `my-server`.

### Defaults

The `@WithDefault` annotation allows to set a default property into a mapping (and prevent and error if the configuration value is not available in any `ConfigSource`):

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

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

No configuration properties required. The `Defaults.foo()` will return the value `foo` and `Defaults.bar()` will return the value `bar`.

### Validation

A config mapping may combine annotations from [Bean Validation](https://beanvalidation.org) to validate configuration values:

```java
@ConfigMapping(prefix = "server")
public interface Server {
    @Size(min = 2, max = 20)
    String host();

    @Max(10000)
    int port();
}
```

> [!WARNING]
> For validation to work, the `quarkus-hibernate-validator` extension is required, and it is performed automatically.

### Mocking

A mapping interface implementation is not a proxy, so it cannot be mocked directly with `@InjectMock` like other CDI beans. One trick is to make it proxyable with a producer method:

```java
public class ServerMockProducer {
    @Inject
    Config config;

    @Produces
    @ApplicationScoped
    @io.quarkus.test.Mock
    Server server() {
        return config.unwrap(SmallRyeConfig.class).getConfigMapping(Server.class);
    }
}
```

The `Server` can be injected as a mock into a Quarkus test class with `@InjectMock`:

```java
@QuarkusTest
class ServerMockTest {
    @InjectMock
    Server server;

    @Test
    void localhost() {
        Mockito.when(server.host()).thenReturn("localhost");
        assertEquals("localhost", server.host());
    }
}
```

> [!NOTE]
> The mock is just an empty shell without any actual configuration values.

If the goal is to only mock certain configuration values and retain the original configuration, the mocking instance requires a spy:

```java
@ConfigMapping(prefix = "app")
@Unremovable
public interface AppConfig {
    @WithDefault("app")
    String name();

    Info info();

    interface Info {
        @WithDefault("alias")
        String alias();
        @WithDefault("10")
        Integer count();
    }
}

public static class AppConfigProducer {
    @Inject
    Config config;

    @Produces
    @ApplicationScoped
    @io.quarkus.test.Mock
    AppConfig appConfig() {
        AppConfig appConfig = config.unwrap(SmallRyeConfig.class).getConfigMapping(AppConfig.class);
        AppConfig appConfigSpy = Mockito.spy(appConfig);
        AppConfig.Info infoSpy = Mockito.spy(appConfig.info());
        Mockito.when(appConfigSpy.info()).thenReturn(infoSpy);
        return appConfigSpy;
    }
}
```

The `AppConfig` can be injected as a mock into a Quarkus test class with `@Inject`:

```java
@QuarkusTest
class AppConfigTest {
    @Inject
    AppConfig appConfig;

    @Test
    void localhost() {
        Mockito.when(appConfig.name()).thenReturn("mocked-app");
        assertEquals("mocked-app", server.host());

        Mockito.when(appConfig.info().alias()).thenReturn("mocked-alias");
        assertEquals("mocked-alias", server.info().alias());
    }
}
```

> [!NOTE]
> Nested elements need to be spied individually by Mockito.
