@ConfigurationProperties for type-safe config in Spring Boot

Introduction

@ConfigurationProperties helps you read settings from files like application.properties or application.yml into Java objects. This makes it easy and safe to use configuration values in your code without mistakes.

You want to group related configuration settings into one Java class.

You need to avoid using many @Value annotations for each config property.

You want to validate configuration values automatically.

You want clear and easy-to-maintain configuration code.

You want to use nested properties in a structured way.

Syntax

Spring Boot

@ConfigurationProperties(prefix = "your.prefix")
public class YourConfig {
    private String property;
    // getters and setters
}

The prefix matches the start of property names in your config files.

You must add @EnableConfigurationProperties or use @ConfigurationPropertiesScan to activate binding.

Examples

This binds properties like app.name and app.timeout from your config files.

Spring Boot

@ConfigurationProperties(prefix = "app")
public class AppProperties {
    private String name;
    private int timeout;

    // getters and setters
}

This shows nested properties like server.port and server.security.enabled.

Spring Boot

@ConfigurationProperties(prefix = "server")
public class ServerProperties {
    private int port;
    private Security security;

    public static class Security {
        private boolean enabled;
        // getters and setters
    }

    // getters and setters
}

Sample Program

This example shows a simple config class that reads app.name and app.timeout from application.properties. Spring Boot automatically fills the fields when the app starts.

Spring Boot

package com.example.demo.config;

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

@Component
@ConfigurationProperties(prefix = "app")
public class AppConfig {
    private String name;
    private int timeout;

    public String getName() {
        return name;
    }

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

    public int getTimeout() {
        return timeout;
    }

    public void setTimeout(int timeout) {
        this.timeout = timeout;
    }
}

// In application.properties:
// app.name=MyApp
// app.timeout=30

// Usage in another component:
// @Autowired
// private AppConfig appConfig;
// System.out.println(appConfig.getName()); // prints MyApp
// System.out.println(appConfig.getTimeout()); // prints 30

Important Notes

Make sure to add @Component or register the config class as a bean so Spring can create it.

Use standard getters and setters for Spring to bind properties correctly.

You can validate properties by adding @Validated and validation annotations like @NotNull.

Summary

@ConfigurationProperties lets you map config files to Java classes easily.

It groups related settings and reduces errors from manual property reading.

Works well with nested properties and supports validation.

Practice

1. What is the main purpose of using @ConfigurationProperties in a Spring Boot application?

easy

A. To create REST endpoints automatically

B. To bind external configuration properties to a Java class for type-safe access

C. To define database entities

D. To handle HTTP requests and responses

Solution

1. Step 1: Understand the role of @ConfigurationProperties

   This annotation is used to map properties from configuration files (like application.properties or application.yml) into Java classes.

2. Step 2: Identify the benefit of type-safe access

   By binding properties to a class, you avoid manual parsing and get compile-time checking of property names and types.

3. Final Answer:

   To bind external configuration properties to a Java class for type-safe access -> Option B

4. Quick Check:

   @ConfigurationProperties = type-safe config binding [OK]

Hint: Remember: @ConfigurationProperties maps config to Java class [OK]

Common Mistakes:

• Confusing @ConfigurationProperties with REST controllers
• Thinking it creates database entities
• Assuming it handles HTTP requests

2. Which of the following is the correct way to enable @ConfigurationProperties support in a Spring Boot application?

easy

A. Add @RestController on the configuration class

B. Annotate the class with @Entity

C. Annotate the class with @Component or use @EnableConfigurationProperties on a configuration class

D. Use @Service annotation on the properties class

Solution

1. Step 1: Identify how Spring Boot detects @ConfigurationProperties classes

   Spring Boot requires the class to be a Spring bean, which can be done by annotating it with @Component or by enabling it via @EnableConfigurationProperties.

2. Step 2: Recognize incorrect annotations

   @Entity is for JPA entities, @RestController is for web controllers, and @Service is for service layer beans, none of which enable configuration properties binding.

3. Final Answer:

   Annotate the class with @Component or use @EnableConfigurationProperties on a configuration class -> Option C

4. Quick Check:

   Enable with @Component or @EnableConfigurationProperties [OK]

Hint: Use @Component or @EnableConfigurationProperties to activate binding [OK]

Common Mistakes:

• Using @Entity or @RestController instead of @Component
• Forgetting to register the properties class as a bean
• Assuming @Service enables configuration binding

3. Given the following configuration class and properties, what will be the value of appProperties.getTimeout()?

application.yml:
app:
  timeout: 5000

Java class:
@ConfigurationProperties(prefix = "app")
public class AppProperties {
    private int timeout;
    public int getTimeout() { return timeout; }
    public void setTimeout(int timeout) { this.timeout = timeout; }
}

medium

A. 5000

B. 0

C. null

D. Throws an exception

Solution

1. Step 1: Match property prefix and field

   The prefix 'app' matches the class prefix, and 'timeout' matches the field name, so the value 5000 binds correctly.

2. Step 2: Understand default value and binding

   Since the property is set in the YAML, the field will be set to 5000, not the default 0 or null.

3. Final Answer:

   5000 -> Option A

4. Quick Check:

   Property value binds correctly = 5000 [OK]

Hint: Match prefix and field names exactly for binding [OK]

Common Mistakes:

• Assuming default 0 because of missing @Value
• Confusing null with primitive int default
• Expecting exception without validation

4. Consider this configuration class:

@ConfigurationProperties(prefix = "server")
public class ServerConfig {
    private String host;
    private int port;

    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; }
}

If the application.yml contains:

server:
  host: localhost
  port: notANumber

What will happen when Spring Boot starts?

medium

A. Port is set to 0 by default, application starts normally

B. Application starts, port is set to string 'notANumber'

C. Port is ignored, host is set, application starts with warning

D. Application fails to start with a binding exception due to invalid port value

Solution

1. Step 1: Analyze property type mismatch

   The 'port' field is an int, but the YAML provides a non-numeric string 'notANumber', causing a type mismatch.

2. Step 2: Understand Spring Boot binding behavior

   Spring Boot throws a binding exception on startup if it cannot convert the property to the required type.

3. Final Answer:

   Application fails to start with a binding exception due to invalid port value -> Option D

4. Quick Check:

   Invalid type causes startup failure [OK]

Hint: Type mismatch in config causes startup failure [OK]

Common Mistakes:

• Assuming default values are used silently
• Expecting warnings instead of errors
• Thinking string can be assigned to int field

5. You want to create a nested configuration properties class to map this YAML:

app:
  security:
    enabled: true
    roles:
      - USER
      - ADMIN

Which of the following Java class structures correctly uses @ConfigurationProperties to map this nested config?

hard

A. public class AppProperties {
private Security security;
public static class Security {
private boolean enabled;
private List<String> roles;
// getters and setters
}
// getters and setters
}

@ConfigurationProperties(prefix = "app")
@Component
public class AppProperties {}

B. @ConfigurationProperties(prefix = "app.security")
@Component
public class Security {
private boolean enabled;
private List<String> roles;
// getters and setters
}

C. @ConfigurationProperties(prefix = "app")
@Component
public class AppProperties {
private boolean enabled;
private List<String> roles;
// getters and setters
}

D. @ConfigurationProperties(prefix = "security")
@Component
public class Security {
private boolean enabled;
private List<String> roles;
// getters and setters
}

Solution

1. Step 1: Understand nested property mapping

   To map nested properties, create a nested class inside the main properties class and define fields matching the nested keys.

2. Step 2: Match prefix and class structure

   The prefix 'app' matches the root, and the nested Security class maps the 'security' subtree with 'enabled' and 'roles'. The main class must be annotated with @ConfigurationProperties and registered as a bean.

3. Step 3: Evaluate options

   public class AppProperties { private Security security; public static class Security { private boolean enabled; private List<String> roles; // getters and setters } // getters and setters } @ConfigurationProperties(prefix = "app") @Component public class AppProperties {} correctly nests Security inside AppProperties and uses prefix 'app'. @ConfigurationProperties(prefix = "app.security") @Component public class Security { private boolean enabled; private List<String> roles; // getters and setters } uses prefix 'app.security' but does not nest. @ConfigurationProperties(prefix = "app") @Component public class AppProperties { private boolean enabled; private List<String> roles; // getters and setters } flattens properties incorrectly. @ConfigurationProperties(prefix = "security") @Component public class Security { private boolean enabled; private List<String> roles; // getters and setters } uses wrong prefix.

4. Final Answer:

   Option A with nested Security class inside AppProperties and prefix 'app' -> Option A

5. Quick Check:

   Nested class + prefix 'app' = correct mapping [OK]

Hint: Use nested classes for nested config with root prefix [OK]

Common Mistakes:

• Using wrong prefix for nested properties
• Flattening nested properties into one class
• Not annotating main class with @ConfigurationProperties