Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 38 ยท Configuration and Validation

Typed Configuration with @ConfigurationProperties

Bind groups of settings to typed Java classes with @ConfigurationProperties, @EachProperty and immutable records. Includes runnable binding stand-ins.

Injecting ten separate @Value strings gets messy fast: names are repeated, types are scattered and nothing documents which settings belong together. Micronaut's answer is typed configuration. You write a small class whose fields mirror a section of your YAML, annotate it, and the framework fills it in.

The real Micronaut code is shown read-only. The runnable examples are Java stand-ins that bind a flat property map to a record and to a family of named configurations, so you can see the mechanics without the framework.

@ConfigurationProperties

Take this section of application.yml:

YAML
app:
  mail:
    host: smtp.example.org
    port: 587
    from: [email protected]
    use-tls: true

A class with the matching prefix receives every key under it:

Java
import io.micronaut.context.annotation.ConfigurationProperties;

@ConfigurationProperties("app.mail")
public class MailConfiguration {

    private String host = "localhost";
    private int port = 25;
    private String from;
    private boolean useTls;

    // getters and setters follow the usual bean pattern
    public String getHost() { return host; }
    public void setHost(String host) { this.host = host; }
    public int getPort() { return port; }
    public void setPort(int port) { this.port = port; }
    public String getFrom() { return from; }
    public void setFrom(String from) { this.from = from; }
    public boolean isUseTls() { return useTls; }
    public void setUseTls(boolean useTls) { this.useTls = useTls; }
}

The class is itself a bean, so any other bean can ask for it in its constructor. The kebab-case key use-tls is bound to the camel-case property useTls, and defaults in the field initializers survive when the key is absent.

Immutable configuration with records

Mutable setters invite bugs, so modern Micronaut lets you bind through a constructor. Use @ConfigurationProperties on an interface, a record or an @ConfigurationInject constructor:

Java
import io.micronaut.context.annotation.ConfigurationProperties;
import io.micronaut.core.annotation.Nullable;

@ConfigurationProperties("app.mail")
public record MailSettings(String host, int port, String from, boolean useTls,
                           @Nullable String replyTo) {}

Constructor parameters without a value and without @Nullable make startup fail with a clear message, which is exactly the behaviour you want for required settings. Combine this with validation annotations from Bean Validation to also enforce ranges and formats.

Nested configuration

Related sub-objects become nested classes or records. With app.mail.retry.attempts and app.mail.retry.delay, a nested type named Retry inside the configuration class is bound to the retry prefix automatically:

Java
@ConfigurationProperties("app.mail")
public record MailSettings(String host, Retry retry) {

    @ConfigurationProperties("retry")
    public record Retry(int attempts, java.time.Duration delay) {}
}

Duration values accept friendly text such as 500ms, 5s or 1m. Sizes accept 10MB. Lists are written as YAML lists or comma-separated strings.

@EachProperty: many named configurations

Sometimes you do not know how many entries there are. A service may talk to several databases or several mail providers, each with the same shape but a different name:

YAML
app:
  clients:
    billing:
      url: https://billing.example.org
      timeout: 3s
    inventory:
      url: https://inventory.example.org
      timeout: 1s

@EachProperty("app.clients") creates one bean per child key, and @Parameter receives the key itself:

Java
import io.micronaut.context.annotation.EachProperty;
import io.micronaut.context.annotation.Parameter;

@EachProperty("app.clients")
public class ClientSettings {
    private final String name;
    private String url;
    private java.time.Duration timeout;

    public ClientSettings(@Parameter String name) { this.name = name; }
    // getters and setters ...
}

Each bean is also available with a qualifier equal to its name, so @Named("billing") ClientSettings billing injects the right one, and List<ClientSettings> injects them all. This is exactly how Micronaut's own data sources and HTTP clients are configured.

Which annotation?

@Value One value. Great for a default.
@ConfigurationProperties One group under a prefix.
1 / 2

Try it: binding a flat map to a record

The stand-in below uses reflection on a record to bind the dotted keys under a prefix. Real Micronaut does this at compile time, without reflection, which matters for native images, but the idea is identical.

Java Bind properties to a record

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Try it: one bean per named child

This stand-in groups keys of the shape app.clients.NAME.field the way @EachProperty does.

Java Imitating @EachProperty

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Design tips

  • Name the prefix after the feature (app.mail), not the class.
  • Give optional settings sensible defaults and mark them @Nullable only when null is meaningful.
  • Keep one configuration type per concern so tests can replace it easily; see Mocking and Test Resources.
  • Use Duration and DataSize types instead of raw numbers, so units are never ambiguous.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does @ConfigurationProperties("app.mail") do?

    The prefix selects a section of the merged configuration, and its keys are bound to the properties or constructor parameters.
  2. 2. How does the key use-tls reach a Java property?

    Kebab-case keys map to camel-case property names.
  3. 3. When do you choose @EachProperty?

    @EachProperty creates a bean for every child key, and @Parameter supplies the key name.
  4. 4. What happens when a required constructor parameter of a configuration record has no value?

    Unless the parameter is nullable or has a default, a missing value is a configuration error reported at startup.

Summary

  • @ConfigurationProperties binds a prefix to a class, interface or record.
  • Records give immutable, constructor-validated configuration.
  • Nested types bind to nested prefixes; Duration and sizes understand units.
  • @EachProperty creates one bean per named child, with @Parameter receiving the name.
  • Typed configuration groups related settings and fails fast on mistakes.

Next: Conditional Beans with @Requires