Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 36 ยท Config and Profiles

Typed Configuration with @ConfigMapping

Group related Quarkus settings into a type-safe interface with @ConfigMapping, nested groups, defaults, lists, maps and Bean Validation, then inject it anywhere.

@ConfigProperty is fine for one or two values. Once a feature has ten settings, a pile of annotated fields becomes hard to read and easy to get wrong. Quarkus recommends @ConfigMapping: you describe the settings as a Java interface, and Quarkus creates the implementation, fills it from configuration, validates it and lets you inject it like any bean.

This lesson builds on properties and profiles. You will map a prefix to an interface, nest groups, use defaults, Optional, lists and maps, and add validation. Real Quarkus code is read-only here; the TryIts reproduce the mapping idea with plain Java so you can watch how the structure is built.

An interface per feature

Java
import io.smallrye.config.ConfigMapping;
import io.smallrye.config.WithDefault;
import java.time.Duration;
import java.util.List;
import java.util.Optional;

@ConfigMapping(prefix = "shop")
public interface ShopConfig {

    String name();

    @WithDefault("EUR")
    String currency();

    Optional<String> supportEmail();

    List<String> countries();

    Checkout checkout();

    interface Checkout {
        @WithDefault("15m")
        Duration sessionTimeout();

        @WithDefault("3")
        int maxRetries();
    }
}
PROPERTIES
shop.name=Bookshop
shop.countries=DE,FR,ES
shop.checkout.session-timeout=20m

Rules the mapping follows:

  • The prefix plus the method name gives the key. A camel-case method name becomes a kebab-case key: supportEmail() reads shop.support-email, and sessionTimeout() reads shop.checkout.session-timeout.
  • A nested interface is a group. Its keys get the parent name in front.
  • @WithDefault gives a value when none is configured. Optional<T> makes a key optional. Everything else is required and checked at startup.
  • List<T> reads a comma-separated value (or indexed keys shop.countries[0]=DE). Map<String, T> reads one key per entry, which suits things like named clients.

Use it by injecting the interface:

Java
@ApplicationScoped
public class PriceFormatter {

    private final ShopConfig config;

    public PriceFormatter(ShopConfig config) {
        this.config = config;
    }

    public String format(long cents) {
        return String.format("%d.%02d %s", cents / 100, cents % 100, config.currency());
    }
}

The older style @ConfigProperties classes still exist, but @ConfigMapping is the one Quarkus extensions use for their own settings and the one to choose for new code. Mapping interfaces are immutable by design, so a bean cannot change a setting by accident.

From keys to a type

Properties shop.checkout.max-retries=5
Interface @ConfigMapping(prefix = shop)
Injected Constructor injection, immutable.

Quarkus generates the implementation at build time.

1 / 2

Maps, nested lists and groups

A Map of groups is the standard way to configure several named things, such as several HTTP clients or payment providers:

Java
@ConfigMapping(prefix = "payments")
public interface PaymentsConfig {

    Map<String, Provider> providers();

    interface Provider {
        String url();
        @WithDefault("5s")
        Duration timeout();
    }
}
PROPERTIES
payments.providers.stripe.url=https://api.example.test/stripe
payments.providers.paypal.url=https://api.example.test/paypal
payments.providers.paypal.timeout=10s

The map key (stripe, paypal) comes from the middle of the property name. Adding a provider is only a configuration change; no code is touched.

Java Stand-in: build a typed tree from flat keys

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.

Validation

Add the Hibernate Validator extension (quarkus-hibernate-validator) and constraints on mapping methods are checked at startup:

Java
@ConfigMapping(prefix = "limits")
public interface LimitsConfig {

    @Min(1) @Max(1000)
    @WithDefault("50")
    int pageSize();

    @NotBlank
    String adminGroup();

    @Pattern(regexp = "[A-Z]{2}")
    String homeCountry();
}

A wrong value, say limits.page-size=5000, stops the application with a message that names the key and the broken rule. This is much better than finding out when a loop runs forever.

Java Stand-in: validate at startup, collect every problem

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.

Profiles and mappings

Mappings work with profiles with no extra code: %dev.shop.currency=USD changes the value ShopConfig.currency() returns in dev mode. For tests, you can also supply the mapping with a test profile or by writing a small implementation of the interface, because it is just an interface.

Custom converters

If a value needs a special type, such as Money from "12.50 EUR", write a Converter<Money> and register it in META-INF/services/org.eclipse.microprofile.config.spi.Converter (or annotate with @Priority and use @RegisterForReflection for native builds). Most applications never need this because Duration, URI, Path, Locale, enum and Optional are built in.

Common mistakes

  • Using snake_case or camelCase keys in the file. The key must be kebab-case: max-retries, not maxRetries.
  • Forgetting that a nested interface needs a method in its parent, and that its keys get the parent's name as a segment.
  • Putting @ConfigMapping on a class instead of an interface.
  • Using the same prefix in two mappings for overlapping keys: pick one owner per prefix.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which property key does the method supportEmail() read in a mapping with prefix shop?

    Camel-case method names are converted to kebab-case keys.
  2. 2. What makes a mapping value optional?

    A value with neither a default nor Optional is required and must be configured, or startup fails.
  3. 3. How do you configure several named payment providers without changing code?

    Map keys come from the property names, so adding a provider is a configuration change only.
  4. 4. What is a benefit of validation annotations on a mapping?

    Constraints run when the mapping is created at startup, so bad configuration never reaches production traffic.

Summary

  • @ConfigMapping(prefix = ...) turns related keys into an immutable, injectable interface.
  • Methods are kebab-cased into keys; nested interfaces are groups; Map handles named entries.
  • @WithDefault and Optional make values optional; everything else is required.
  • Add Hibernate Validator constraints to reject bad configuration at startup.

Next: Secrets, Validation and Config Sources