@ConfigurationProperties in Spring Boot

Introduction to @ConfigurationProperties

In Spring Boot, @ConfigurationProperties is a powerful annotation-driven feature that allows you to externalize configuration properties from your code to properties files, YAML files, environment variables, or command-line arguments. This feature simplifies the process of configuring your Spring Boot applications and promotes separation of configuration concerns.

In this guide, we will explore how to use the @ConfigurationProperties annotation to effectively manage configuration properties in Spring Boot applications.

Prerequisites

Before diving into the usage of @ConfigurationProperties, ensure that you have a basic understanding of Spring Boot and its configuration.

Defining Configuration Properties

To start using @ConfigurationProperties, you need to define a configuration class and annotate it with @Component and @ConfigurationProperties. This class will represent a container for your configuration properties.

Let’s create a simple example of a configuration class to hold database-related properties:

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Component
@ConfigurationProperties(prefix = "database")
public class DatabaseConfig {
    private String url;
    private String username;
    private String password;

    // Getters and setters
}

In this example, we have defined a DatabaseConfig class annotated with @Component and @ConfigurationProperties(prefix = "database"). The prefix attribute specifies the common prefix for all configuration properties related to the database.

Configuring Properties

Next, you need to configure the properties in your application’s configuration file (application.properties or application.yml). For our example, let’s use application.properties:

database.url=jdbc:mysql://localhost:3306/mydb
database.username=myuser
database.password=mypassword

In this configuration, we have defined properties with the database prefix, matching the prefix defined in the DatabaseConfig class.

Accessing Configuration Properties

To access the configured properties, you can simply inject the DatabaseConfig bean into your components or services:

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class DatabaseService {
    private final DatabaseConfig databaseConfig;

    @Autowired
    public DatabaseService(DatabaseConfig databaseConfig) {
        this.databaseConfig = databaseConfig;
    }

    public void printDatabaseConfig() {
        System.out.println("URL: " + databaseConfig.getUrl());
        System.out.println("Username: " + databaseConfig.getUsername());
        System.out.println("Password: " + databaseConfig.getPassword());
    }
}

In this example, the DatabaseService class injects the DatabaseConfig bean using constructor injection. It then prints the configured database properties.

Advanced Usage of @ConfigurationProperties

Type Conversion and Validation

@ConfigurationProperties supports automatic type conversion and validation of properties. You can leverage Spring’s conversion and validation mechanisms to ensure that the configured values are of the correct types and meet certain constraints.

Let’s enhance our DatabaseConfig class to include validation for the url property:

import org.hibernate.validator.constraints.URL;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

import javax.validation.constraints.NotBlank;

@Component
@ConfigurationProperties(prefix = "database")
public class DatabaseConfig {
    @URL
    @NotBlank
    private String url;

    private String username;
    private String password;

    // Getters and setters
}

In this example, we’ve added @URL and @NotBlank annotations to the url property. These annotations validate that the URL is not blank and conforms to a valid URL format.

Nested Configuration Properties

You can also use @ConfigurationProperties with nested classes to represent more complex configuration structures. Let’s extend our example to include a nested ConnectionPool configuration:

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Component
@ConfigurationProperties(prefix = "database")
public class DatabaseConfig {
    private String url;
    private String username;
    private String password;
    private ConnectionPool connectionPool = new ConnectionPool();

    // Getters and setters

    public ConnectionPool getConnectionPool() {
        return connectionPool;
    }

    public static class ConnectionPool {
        private int maxConnections;
        private int minConnections;

        // Getters and setters
    }
}

In this example, we’ve introduced a nested ConnectionPool class within DatabaseConfig. This allows us to group related properties under the connectionPool prefix.

Using Configuration Metadata

@ConfigurationProperties generates metadata that can be used for documentation and hints in IDEs. To enable this feature, add the @EnableConfigurationProperties annotation to one of your @Configuration classes:

import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableConfigurationProperties(DatabaseConfig.class)
public class AppConfig {
    // Configuration-related beans and settings
}

Property Binding with @Value

While @ConfigurationProperties is commonly used for binding externalized configuration, you can also use the @Value annotation to bind individual properties directly to fields in your beans:

import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

@Component
public class MyComponent {
    @Value("${my.property}")
    private String myProperty;

    // Other bean methods
}

In this example, the @Value annotation binds the value of the property named my.property to the myProperty field.

Conclusion

The @ConfigurationProperties annotation in Spring Boot provides a versatile and powerful way to manage configuration properties in your applications. From simple properties to complex nested configurations, you can externalize and organize your configuration settings for better maintenance and flexibility. By leveraging type conversion, validation, and metadata generation, @ConfigurationProperties enhances the development and management of Spring Boot applications. Whether you’re working on a small project or a large-scale application, understanding and utilizing @ConfigurationProperties can greatly improve your configuration management practices.