Table of Contents

@Configuration and @ConfigurationBuilder

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

Authors: Nirav Assar

Micronaut Version: 4.6.3

1. Getting Started

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

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

2. What you will need

To complete this guide, you will need the following:

3. 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.

4. Writing the Application

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

mn create-app example.micronaut.micronautguide \
    --features=yaml,serialization-jackson,graalvm,kapt \
    --build=gradle \
    --lang=kotlin \
    --test=junit
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 yaml, serialization-jackson, graalvm, and kapt features.

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.

5. 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.

Since Micronaut Framework 4.0, to use YAML configuration, you have to add the YAML dependency.
src/main/resources/application.yml
team:
  name: 'Steelers'
  color: 'Black'
  player-names:
    - 'Mason Rudolph'
    - 'James Connor'

With the Micronaut framework, we can use the @ConfigurationProperties annotation to slurp the configuration into a bean. Each property that matches the configuration in the application.yml will call the setter in the bean. The bean will be subsequently available for injection in the application!

src/main/kotlin/example/micronaut/TeamConfiguration.kt
@ConfigurationProperties("team")
class TeamConfiguration  {
    var name: String? = null
    var color: String? = null
    var playerNames: List<String>? = null

5.1. Test @ConfigurationProperties

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

src/test/kotlin/example/micronaut/TeamConfigurationTest.kt
    @Test
    fun testTeamConfiguration() {
        val names = listOf("Nirav Assar", "Lionel Messi")
        val items = mapOf("team.name" to "evolution",
            "team.color" to "green",
            "team.player-names" to names)

        val ctx = ApplicationContext.run(items) (1)
        val teamConfiguration = ctx.getBean(TeamConfiguration::class.java)

        assertEquals("evolution", teamConfiguration.name)
        assertEquals("green", teamConfiguration.color)
        assertEquals(names.size, teamConfiguration.playerNames!!.size)

        names.forEach {
            assertTrue(teamConfiguration.playerNames!!.contains(it))
        }

        ctx.close()
    }
1 Set up configuration properties for the test to use

6. 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. The Framework supports the Builder pattern with @ConfigurationBuilder.

Let’s suppose we want to add team administrators to a team. The team administration is composed by using a builder pattern object. We can add a coach, manager and president to the team.

src/main/resources/application.yml
team:
  name: 'Steelers'
  color: 'Black'
  player-names:
    - 'Mason Rudolph'
    - 'James Connor'
  team-admin:
    manager: 'Nirav Assar' (1)
    coach: 'Mike Tomlin'
    president: 'Dan Rooney'
1 manager property is an example of an element that will be built

The TeamAdmin object abides by the Builder pattern.

src/main/kotlin/example/micronaut/TeamAdmin.kt
package example.micronaut

class TeamAdmin private constructor(
        val manager: String?,
        val coach: String?,
        val president: String?) { (1)
    data class Builder( (2)
            var manager: String? = null,
            var coach: String? = null,
            var president: String? = null) {
        fun withManager(manager: String) = apply { this.manager = manager } (3)
        fun withCoach(coach: String) = apply { this.coach = coach }
        fun withPresident(president: String) = apply { this.president = president }
        fun build() = TeamAdmin(manager, coach, president) (4)
    }
}
1 TeamAdmin is the configuration object which consumes the declared properties.
2 The builder object is used to incrementally construct the object.
3 An example of a builder method, where a attribute is set and then the builder itself is returned.
4 The final build() method creates the TeamAdmin object.

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

We are using the builder only here, so we will have to call builder.build() to actually get the TeamAdmin object, at a later time. In our case, we will call builder.build() in the JUnit test.
src/main/kotlin/example/micronaut/TeamConfiguration.kt
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

@Serdeable (1)
@JsonIgnoreProperties("builder") (2)
//tag::teamConfigClassNoBuilder[]
@ConfigurationProperties("team")
class TeamConfiguration  {
    var name: String? = null
    var color: String? = null
    var playerNames: List<String>? = null
//end::teamConfigClassNoBuilder[]
//tag::teamConfigClassBuilder[]
    @ConfigurationBuilder(prefixes = ["with"], configurationPrefix = "team-admin") (3)
    var builder = TeamAdmin.Builder() (4)
//end::teamConfigClassBuilder[]
}

//tag::gettersandsetters[]
//end::gettersandsetters[]
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 the Micronaut framework to find methods that are prefixed by with; configurationPrefix allows the developer to customize the application.yml element
4 Instantiate the builder object so it can be populated with configuration values.

6.1. Test @ConfigurationBuilder

We can validate @ConfigurationBuilder is applied properly with the following JUnit test. The test format is similar to previous tests.

src/test/kotlin/example/micronaut/TeamConfigurationTest.kt
    @Test
    fun testTeamConfigurationBuilder() {
        val names = listOf("Nirav Assar", "Lionel Messi")
        val items = mapOf("team.name" to "evolution",
            "team.color" to "green",
            "team.team-admin.manager" to "Jerry Jones", (1)
            "team.team-admin.coach" to "Tommy O'Neill",
            "team.team-admin.president" to "Mark Scanell",
            "team.player-names" to names)

        val ctx = ApplicationContext.run(items)
        val teamConfiguration = ctx.getBean(TeamConfiguration::class.java)
        val teamAdmin = teamConfiguration.builder.build() (2)

        assertEquals("evolution", teamConfiguration.name)
        assertEquals("green", teamConfiguration.color)
        assertEquals("Nirav Assar", teamConfiguration.playerNames!![0])
        assertEquals("Lionel Messi", teamConfiguration.playerNames!![1])

        // check the builder has values set
        assertEquals("Jerry Jones", teamConfiguration.builder.manager)
        assertEquals("Tommy O'Neill", teamConfiguration.builder.coach)
        assertEquals("Mark Scanell", teamConfiguration.builder.president)

        // check the object can be built
        assertEquals("Jerry Jones", teamAdmin.manager) (3)
        assertEquals("Tommy O'Neill", teamAdmin.coach)
        assertEquals("Mark Scanell", teamAdmin.president)
        ctx.close()
1 Properties which will invoke the builder methods on TeamAdmin.Builder
2 The builder object is now configured, so we must run build() on it to create the TeamAdmin object
3 Verify the object is created with the applicaton.yml properties

7. Stadiums with @EachProperty

The Micronaut framework is also able to read a "list" of configurations that are related. Imagine we would like to declare stadiums and their attributes.

src/main/resources/application.yml
stadium:
  coors: (1)
    city: 'Denver'
    size: 50000
  pnc:
    city: 'Pittsburgh'
    size: 35000
1 This element will be the name of the bean.

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

src/main/kotlin/example/micronaut/StadiumConfiguration.kt
package example.micronaut

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

@Serdeable (1)
@EachProperty("stadium") (2)
class StadiumConfiguration
constructor(@param:Parameter val name: String) {  (3)
    var city: String? = null
    var size: Int? = null
}
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 in from the property key and send as a parameter to the bean.

7.1. Test @EachProperty

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

src/test/kotlin/example/micronaut/StadiumConfigurationTest.kt
package example.micronaut

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

class StadiumConfigurationTest {
    @Test
    fun testStadiumConfiguration() {
        val items: MutableMap<String, Any> = HashMap()
        items["stadium.fenway.city"] = "Boston" (1)
        items["stadium.fenway.size"] = 60000
        items["stadium.wrigley.city"] = "Chicago" (1)
        items["stadium.wrigley.size"] = 45000

        val ctx = ApplicationContext.run(items)

        (2)
        val fenwayConfiguration = ctx.getBean(StadiumConfiguration::class.java, Qualifiers.byName("fenway"))
        val wrigleyConfiguration = ctx.getBean(StadiumConfiguration::class.java, Qualifiers.byName("wrigley"))

        assertEquals("fenway", fenwayConfiguration.name)
        assertEquals(60000, fenwayConfiguration.size)
        assertEquals("wrigley", wrigleyConfiguration.name)
        assertEquals(45000, wrigleyConfiguration.size)

        ctx.close()
    }
}
1 Multiple configurations can be declared for the same class.
2 Since there are multiple beans to retrieve a bean a Qualifier must be sent.

8. Running the Application

To run the application, use the ./gradlew run command, which starts the application on port 8080.

9. Controller

Configuration beans can be injected into the application with 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 we need to use the @Named annotation with a qualifier name to specify the bean.

src/main/kotlin/example/micronaut/MyController.kt
package example.micronaut

import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import jakarta.inject.Named

@Controller("/my")
class MyController(val teamConfiguration: TeamConfiguration,
                   @Named("pnc") val stadiumConfiguration: StadiumConfiguration) { (1)

    @Get("/team")
    fun team(): TeamConfiguration {
        return teamConfiguration
    }

    @Get("/stadium")
    fun stadium(): StadiumConfiguration {
        return stadiumConfiguration
    }
}
1 Injection of configuration beans; @Named annotation is needed to choose which StadiumConfiguration instance is retrieved.
In the browser go to http://localhost:8080/my/team and http://localhost:8080/my/stadium.

Add test:

src/test/kotlin/example/micronaut/MyControllerTest.kt
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.Assertions.assertEquals
import org.junit.jupiter.api.Assertions.assertTrue
import org.junit.jupiter.api.Test
import java.util.Arrays
import java.util.function.Consumer
import jakarta.inject.Inject

@MicronautTest
class MyControllerTest(@Client("/") val client: HttpClient) {

    @Test
    fun testMyTeam() {
        val teamConfiguration = client.toBlocking()
                .retrieve(HttpRequest.GET<Any>("/my/team"), TeamConfiguration::class.java)
        assertEquals("Steelers", teamConfiguration.name)
        assertEquals("Black", teamConfiguration.color)
        val expectedPlayers = Arrays.asList("Mason Rudolph", "James Connor")
        assertEquals(expectedPlayers.size, teamConfiguration.playerNames!!.size)
        expectedPlayers.forEach(Consumer { name: String? -> assertTrue(teamConfiguration.playerNames!!.contains(name!!)) })
    }

    @Test
    fun testMyStadium() {
        val conf = client.toBlocking()
                .retrieve(HttpRequest.GET<Any>("/my/stadium"), StadiumConfiguration::class.java)
        assertEquals("Pittsburgh", conf.city)
        assertEquals(35000, conf.size)
    }
}

10. Generate a Micronaut Application Native Executable with GraalVM

We will use GraalVM, the polyglot embeddable virtual machine, to generate a native executable of our Micronaut application.

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

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

10.1. GraalVM installation

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

Java 21
sdk install java 21.0.5-graal
Java 21
sdk use java 21.0.5-graal

For installation on Windows, or for 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 21
sdk install java 21.0.2-graalce
Java 21
sdk use java 21.0.2-graalce

10.2. Native executable generation

To generate a native executable using Gradle, run:

./gradlew nativeCompile

The native executable is created in build/native/nativeCompile directory and can be run with build/native/nativeCompile/micronautguide.

It is possible to customize the name of the native executable or pass additional parameters to GraalVM:

build.gradle
graalvmNative {
    binaries {
        main {
            imageName.set('mn-graalvm-application') (1)
            buildArgs.add('--verbose') (2)
        }
    }
}
1 The native executable name will now be mn-graalvm-application
2 It is possible to pass extra arguments to build the native executable

You can invoke the controller exposed by the native executable:

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

11. Next steps

Visit Micronaut Application Configuration to learn more.

12. Help with the Micronaut Framework

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

13. License

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