Java / Maven

@Configuration and @ConfigurationBuilder

Learn how to use @Configuration and @ConfigurationBuilder annotations to configure declared properties.

Nirav Assar

On this guide

In this section

Getting Started

In this guide, we will create a Micronaut application written in Java.

In this guide, you will learn how to use the annotations @ConfigurationProperties, @ConfigurationBuilder, and @EachProperty to consume configured properties in a Micronaut application. These annotations allow declared values to be injected into a bean for use in the application.

What you will need

To complete this guide, you will need the following:

Some time on your hands
A decent text editor or IDE (e.g. IntelliJ IDEA)
JDK 21 or greater installed with JAVA_HOME configured appropriately

Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

Download and unzip the source

Writing the Application

Create an application using the Micronaut Command Line Interface or with Micronaut Launch.

mn create-app example.micronaut.micronautguide \
    --features=serialization-jackson,graalvm \
    --build=maven \
    --lang=java \
    --test=junit

Note	If you don’t specify the `--build` argument, Gradle with the Kotlin DSL is used as the build tool. If you don’t specify the `--lang` argument, Java is used as the language. If you don’t specify the `--test` argument, JUnit is used for Java and Kotlin, and Spock is used for Groovy.

The previous command creates a Micronaut application with the default package example.micronaut in a directory named micronautguide.

If you use Micronaut Launch, select Micronaut Application as application type and add serialization-jackson, and graalvm features.

Note	If you have an existing Micronaut application and want to add the functionality described here, you can view the dependency and configuration changes from the specified features, and apply those changes to your application.

Diff

Setup IntelliJ IDEA to develop Micronaut Applications.

Team Configuration with @ConfigurationProperties

Imagine a feature where you can configure a sports team in a declarative manner. The team has a few attributes like team name, color, and players.

src/main/resources/application.properties

team.name=Steelers
team.color=Black
team.player-names[0]=Mason Rudolph
team.player-names[1]=James Connor

With Micronaut Framework, you can use the @ConfigurationProperties annotation to bind the configuration into a bean. Each property that matches the configuration in application.properties will call the setter in the bean. The bean will then be available for injection in the application.

java/src/main/java/example/micronaut/TeamConfiguration.java

@ConfigurationProperties("team")
public class TeamConfiguration {
    private String name;
    private String color;
    private List<String> playerNames;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getColor() {
        return color;
    }

    public void setColor(String color) {
        this.color = color;
    }

    public List<String> getPlayerNames() {
        return playerNames;
    }

    public void setPlayerNames(List<String> playerNames) {
        this.playerNames = playerNames;
    }
}

Test @ConfigurationProperties

Let’s validate that the bean is available in the application context and is created with the values declared in the application.properties.

java/src/test/java/example/micronaut/TeamConfigurationTest.java

@Test
void testTeamConfiguration() {
    List<String> names = Arrays.asList("Nirav Assar", "Lionel Messi");
    Map<String, Object> items = new HashMap<>();
    items.put("team.name", "evolution");
    items.put("team.color", "green");
    items.put("team.player-names", names);

    ApplicationContext ctx = ApplicationContext.run(items); // 
    TeamConfiguration teamConfiguration = ctx.getBean(TeamConfiguration.class);

    assertEquals("evolution", teamConfiguration.getName());
    assertEquals("green", teamConfiguration.getColor());
    assertEquals(names.size(), teamConfiguration.getPlayerNames().size());
    names.forEach(name -> assertTrue(teamConfiguration.getPlayerNames().contains(name)));

    ctx.close();
}

1	Set up configuration properties for the test to use

Team Admin Builder with @ConfigurationBuilder

The Builder pattern is a great way to build configuration objects incrementally. Read about the Builder pattern in this DZone article to learn more. Micronaut Framework supports the Builder pattern with @ConfigurationBuilder.

Suppose you want to add team administrators to a team. The team administration is composed by using a builder pattern object. You can add a coach, manager, and president to the team.

src/main/resources/application.properties

team.name=Steelers
team.color=Black
team.player-names[0]=Mason Rudolph
team.player-names[1]=James Connor
team.team-admin.manager=Nirav Assar 
team.team-admin.coach=Mike Tomlin
team.team-admin.president=Dan Rooney

1	The `manager` property is an example of an element that will be built.

The TeamAdmin object abides by the Builder pattern.

java/src/main/java/example/micronaut/TeamAdmin.java

package example.micronaut;

public class TeamAdmin { // 

    private String manager;
    private String coach;
    private String president;

    // should use the builder pattern to create the object
    private TeamAdmin() {
    }

    public String getManager() {
        return manager;
    }

    public void setManager(String manager) {
        this.manager = manager;
    }

    public String getCoach() {
        return coach;
    }

    public void setCoach(String coach) {
        this.coach = coach;
    }

    public String getPresident() {
        return president;
    }

    public void setPresident(String president) {
        this.president = president;
    }

    public static Builder builder() {
        return new Builder();
    }

    public static class Builder { // 
        private String manager;
        private String coach;
        private String president;

        // 
        public Builder withManager(String manager) {
            this.manager = manager;
            return this;
        }

        public Builder withCoach(String coach) {
            this.coach = coach;
            return this;
        }

        public Builder withPresident(String president) {
            this.president = president;
            return this;
        }

        public TeamAdmin build() { // 
            TeamAdmin teamAdmin = new TeamAdmin();
            teamAdmin.manager = this.manager;
            teamAdmin.coach = this.coach;
            teamAdmin.president = this.president;
            return teamAdmin;
        }

        public String getManager() {
            return manager;
        }

        public String getCoach() {
            return coach;
        }

        public String getPresident() {
            return president;
        }
    }
}

1	`TeamAdmin` is the configuration object that consumes the declared properties.
2	The builder object is used to incrementally construct the object.
3	An example of a builder method, where an attribute is set and then the builder itself is returned.
4	The final `build()` method creates the `TeamAdmin` object.

At the bottom of TeamConfiguration, add the inner class TeamAdmin.Builder and annotate it with @ConfigurationBuilder. This tells Micronaut Framework that configuration can be read and an object can be constructed using the Builder pattern.

Note	The builder is used only here, so call `builder.build()` later to get the `TeamAdmin` object. In this guide, the JUnit test calls `builder.build()`.

java/src/main/java/example/micronaut/TeamConfiguration.java

package example.micronaut;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import io.micronaut.context.annotation.ConfigurationBuilder;
import io.micronaut.context.annotation.ConfigurationProperties;
import io.micronaut.serde.annotation.Serdeable;

import java.util.List;

@Serdeable // 
@JsonIgnoreProperties("builder") // 
@ConfigurationProperties("team")
public class TeamConfiguration {
    private String name;
    private String color;
    private List<String> playerNames;

    public TeamConfiguration() {
    }

    @ConfigurationBuilder(prefixes = "with", configurationPrefix = "team-admin") // 
    protected TeamAdmin.Builder builder = TeamAdmin.builder(); // 

    public TeamAdmin.Builder getBuilder() {
        return builder;
    }

    public void setBuilder(TeamAdmin.Builder builder) {
        this.builder = builder;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getColor() {
        return color;
    }

    public void setColor(String color) {
        this.color = color;
    }

    public List<String> getPlayerNames() {
        return playerNames;
    }

    public void setPlayerNames(List<String> playerNames) {
        this.playerNames = playerNames;
    }
}

1	Declare the `@Serdeable` annotation at the type level in your source code to allow the type to be serialized or deserialized.
2	Mark the builder as being ignored during serialization.
3	`prefixes` tells Micronaut Framework to find methods that are prefixed by `with`; `configurationPrefix` allows the developer to customize the `application.properties` element.
4	Instantiate the builder object so it can be populated with configuration values.

Test @ConfigurationBuilder

Validate that @ConfigurationBuilder is applied properly with the following JUnit test. The test format is similar to previous tests.

java/src/test/java/example/micronaut/TeamConfigurationTest.java

@Test
void testTeamConfigurationBuilder() {
    List<String> names = Arrays.asList("Nirav Assar", "Lionel Messi");
    Map<String, Object> items = new HashMap<>();
    items.put("team.name", "evolution");
    items.put("team.color", "green");
    items.put("team.team-admin.manager", "Jerry Jones"); // 
    items.put("team.team-admin.coach", "Tommy O'Neill");
    items.put("team.team-admin.president", "Mark Scanell");
    items.put("team.player-names", names);

    ApplicationContext ctx = ApplicationContext.run(items);
    TeamConfiguration teamConfiguration = ctx.getBean(TeamConfiguration.class);
    TeamAdmin teamAdmin = teamConfiguration.builder.build(); // 

    assertEquals("evolution", teamConfiguration.getName());
    assertEquals("green", teamConfiguration.getColor());
    assertEquals("Nirav Assar", teamConfiguration.getPlayerNames().get(0));
    assertEquals("Lionel Messi", teamConfiguration.getPlayerNames().get(1));

    // check the builder has values set
    assertEquals("Jerry Jones", teamConfiguration.builder.getManager());
    assertEquals("Tommy O'Neill", teamConfiguration.builder.getCoach());
    assertEquals("Mark Scanell", teamConfiguration.builder.getPresident());

    // check the object can be built
    assertEquals("Jerry Jones", teamAdmin.getManager()); // 
    assertEquals("Tommy O'Neill", teamAdmin.getCoach());
    assertEquals("Mark Scanell", teamAdmin.getPresident());

    ctx.close();
}

1	Properties that will invoke the builder methods on `TeamAdmin.Builder`.
2	The builder object is now configured, so run `build()` on it to create the `TeamAdmin` object.
3	Verify the object is created with the `application.properties` properties.

Stadiums with @EachProperty

Micronaut Framework is also able to read a list of related configurations. Imagine you would like to declare stadiums and their attributes.

src/main/resources/application.properties

stadium.coors.city=Denver 
stadium.coors.size=50000
stadium.pnc.city=Pittsburgh
stadium.pnc.size=35000

1	This element will be the name of the bean. It must be lower kebab-case.

You can use @EachProperty to cycle through the configuration and read each nested clause as a bean. The higher-level property will be parameterized as the name.

java/src/main/java/example/micronaut/StadiumConfiguration.java

package example.micronaut;

import io.micronaut.context.annotation.EachProperty;
import io.micronaut.context.annotation.Parameter;
import io.micronaut.serde.annotation.Serdeable;

@Serdeable // 
@EachProperty("stadium") // 
public class StadiumConfiguration {
    private String name; // 
    private String city;
    private Integer size;

    public StadiumConfiguration(@Parameter String name) { // 
        this.name = name;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getCity() {
        return city;
    }

    public void setCity(String city) {
        this.city = city;
    }

    public Integer getSize() {
        return size;
    }

    public void setSize(Integer size) {
        this.size = size;
    }
}

1	Declare the `@Serdeable` annotation at the type level in your source code to allow the type to be serialized or deserialized.
2	Establish the top layer of configuration.
3	`name` is read from the property key and sent as a parameter to the bean.

Test @EachProperty

Validate the configuration with a test. Notice multiple beans are created from the configuration. In a controller, you can inject a particular StadiumConfiguration instance bean by using the @Named parameter with a qualifier name.

java/src/test/java/example/micronaut/StadiumConfigurationTest.java

package example.micronaut;

import io.micronaut.context.ApplicationContext;
import io.micronaut.inject.qualifiers.Qualifiers;
import org.junit.jupiter.api.Test;

import java.util.HashMap;
import java.util.Map;

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

public class StadiumConfigurationTest {

    @Test
    void testStadiumConfiguration() {
        Map<String, Object> items = new HashMap<>();
        items.put("stadium.fenway.city", "Boston"); // 
        items.put("stadium.fenway.size", 60000);
        items.put("stadium.wrigley.city", "Chicago"); // 
        items.put("stadium.wrigley.size", 45000);

        ApplicationContext ctx = ApplicationContext.run(items);

        // 
        StadiumConfiguration fenwayConfiguration = ctx.getBean(StadiumConfiguration.class, Qualifiers.byName("fenway"));
        StadiumConfiguration wrigleyConfiguration = ctx.getBean(StadiumConfiguration.class, Qualifiers.byName("wrigley"));

        assertEquals("fenway", fenwayConfiguration.getName());
        assertEquals(60000, fenwayConfiguration.getSize());
        assertEquals("wrigley", wrigleyConfiguration.getName());
        assertEquals(45000, wrigleyConfiguration.getSize());

        ctx.close();
    }
}

1	Multiple configurations can be declared for the same class.
2	Since there are multiple beans, a `Qualifier` must be sent to retrieve a bean.

Running the Application

To run the application, use the ./mvnw mn:run command, which starts the application on port 8080.

Controller

Configuration beans can be injected into the application just like any other beans. As a demonstration, create a controller where the beans are constructor injected. The StadiumConfiguration class has two instances, so for injection you need to use the @Named annotation with a qualifier name to specify the bean.

java/src/main/java/example/micronaut/MyController.java

package example.micronaut;

import io.micronaut.core.annotation.Nullable;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;

import jakarta.inject.Named;

@Controller("/my")
public class MyController {

    private final TeamConfiguration teamConfiguration;
    private final StadiumConfiguration stadiumConfiguration;

    public MyController(@Nullable TeamConfiguration teamConfiguration,
                        @Nullable @Named("pnc") StadiumConfiguration stadiumConfiguration) { // 
        this.teamConfiguration = teamConfiguration;
        this.stadiumConfiguration = stadiumConfiguration;
    }

    @Get("/team")
    public TeamConfiguration team() {
        return this.teamConfiguration;
    }

    @Get("/stadium")
    public  StadiumConfiguration stadium() {
        return this.stadiumConfiguration;
    }
}

1	Injection of configuration beans; `@Named` annotation is needed to choose which `StadiumConfiguration` instance is retrieved.

Note	In the browser go to http://localhost:8080/my/team and http://localhost:8080/my/stadium.

Add test:

java/src/test/java/example/micronaut/MyControllerTest.java

package example.micronaut;

import io.micronaut.http.HttpRequest;
import io.micronaut.http.client.HttpClient;
import io.micronaut.http.client.annotation.Client;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import org.junit.jupiter.api.Test;

import jakarta.inject.Inject;

import java.util.Arrays;
import java.util.List;

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

@MicronautTest
public class MyControllerTest {

    @Inject
    @Client("/")
    HttpClient client;

    @Test
    void testMyTeam() {
        TeamConfiguration teamConfiguration = client.toBlocking()
                .retrieve(HttpRequest.GET("/my/team"), TeamConfiguration.class);
        assertEquals("Steelers", teamConfiguration.getName());
        assertEquals("Black", teamConfiguration.getColor());
        List<String> expectedPlayers = Arrays.asList("Mason Rudolph", "James Connor");
        assertEquals(expectedPlayers.size(), teamConfiguration.getPlayerNames().size());
        expectedPlayers.forEach(name -> assertTrue(teamConfiguration.getPlayerNames().contains(name)));
    }

    @Test
    void testMyStadium() {
        StadiumConfiguration conf = client.toBlocking()
                .retrieve(HttpRequest.GET("/my/stadium"), StadiumConfiguration.class);
        assertEquals("Pittsburgh", conf.getCity());
        assertEquals(35000, conf.getSize());
    }
}

Generate a Micronaut Application Native Executable with GraalVM

We will use GraalVM, an advanced JDK with ahead-of-time Native Image compilation, to generate a native executable of this Micronaut application.

Compiling Micronaut applications ahead of time with GraalVM significantly improves startup time and reduces the memory footprint of JVM-based applications.

Note	Only Java and Kotlin projects support using GraalVM’s `native-image` tool. Groovy relies heavily on reflection, which is only partially supported by GraalVM.

GraalVM Installation

The easiest way to install GraalVM on Linux or Mac is to use SDKMan.io.

Java 25

sdk install java 25.0.2-graal

For installation on Windows, or for a manual installation on Linux or Mac, see the GraalVM Getting Started documentation.

The previous command installs Oracle GraalVM, which is free to use in production and free to redistribute, at no cost, under the GraalVM Free Terms and Conditions.

Alternatively, you can use the GraalVM Community Edition:

Java 25

sdk install java 25.0.2-graalce

Native Executable Generation

To generate a native executable using Maven, run:

./mvnw package -Dpackaging=native-image

The native executable is created in the target directory and can be run with target/micronautguide.

It is possible to customize the name of the native executable or pass additional build arguments using the Maven plugin for GraalVM Native Image building. Declare the plugin as follows:

pom.xml

<plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-maven-plugin</artifactId>
    <version>0.11.5</version>
    <configuration>
         
         <imageName>mn-graalvm-application</imageName>
        <buildArgs>
          
          <buildArg>-Ob</buildArg>
        </buildArgs>
    </configuration>
</plugin>

1	The native executable name will now be `mn-graalvm-application`.
2	It is possible to pass extra build arguments to `native-image`. For example, `-Ob` enables the quick build mode.

You can invoke the controller exposed by the native executable:

curl http://localhost:8080/my/stadium
curl http://localhost:8080/my/team

Next Steps

Visit Micronaut Application Configuration to learn more.

Help with the Micronaut Framework

The Micronaut Foundation sponsored the creation of this Guide. A variety of consulting and support services are available.

License

Note	All guides are released with an Apache License 2.0 for the code and a Creative Commons Attribution 4.0 license for the writing and media (images).