1. Introduction
One handy feature of Spring Boot is externalized configuration and easy access to properties defined in properties files. They also provide you the flexibility to tune your application from a single place.
In this article, you’ll learn how to define and use external configurations in Spring Boot with a very simple annotation-based API called @ConfigurationProperties.
@ConfigurationProperties bind external configurations to a strongly typed bean in your application code. You can inject and use this bean throughout your application code just like any other spring bean.
2. Setup
This article uses a fairly standard setup. We start by adding spring-boot-starter-parent as the parent in our pom.xml:
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.1.7.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
To be able to validate properties defined in the file, we also need an implementation of JSR-303. hibernate-validator is one of them.
Let’s add it to our pom.xml as well:
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-validator</artifactId>
<version>6.0.16.Final</version>
</dependency>
The getting started with Hibernate Validator page has more details.
3. @Value
Normally, we use the @Value to inject the .properties value one by one, this is good for small and simple structure .properties files. For example,
generic.properties file
email=support@dailycodebuffer.com
appName= Spring Boot Configuration Properties
@Component
@PropertySource("classpath:generic.properties")
public class GenericProperties {
@Value("${appName}")
private String appName;
@Value("${email}")
private String email;
public String getAppName() {
return appName;
}
public void setAppName(String appName) {
this.appName = appName;
}
public String getEmail() {
return email;
}
public void setEmail(String email) {
this.email = email;
}
}
The equivalent in @ConfigurationProperties
@Component
@PropertySource("classpath:generic.properties")
@ConfigurationProperties
public class GenericConfigProperties {
private String appName;
private String email;
public String getAppName() {
return appName;
}
public void setAppName(String appName) {
this.appName = appName;
}
public String getEmail() {
return email;
}
public void setEmail(String email) {
this.email = email;
}
}
Spring uses some relaxed rules for binding properties. So the following variations are all bound to the property appName:
appName
appname
app_name
app-name
APP_NAME
4. @ConfigurationProperties
Now, for the complex structure below. How we are going to map this complex .properties file structure to POJO classes. We have created GlobalApplication.properties file.
#App
app.menus[0].title=Home
app.menus[0].name=Home
app.menus[0].path=/
app.menus[1].title=Login
app.menus[1].name=Login
app.menus[1].path=/login
app.compiler.timeout=5
app.compiler.output-folder=/temp/
app.error=/error/
Now, Let’s see how we have mapped all these properties to the POJO class with the @ConfigurationProperties annotation.
@PropertySource("classpath:GlobalApplication.properties")
@ConfigurationProperties("app") // prefix app, find app.* values
public class GlobalApplicationProperties {
private String error;
private List<Menu> menus = new ArrayList<>();
private Compiler compiler = new Compiler();
public static class Menu {
private String name;
private String path;
private String title;
//getters and setters
@Override
public String toString() {
return "Menu{" +
"name='" + name + '\'' +
", path='" + path + '\'' +
", title='" + title + '\'' +
'}';
}
}
public static class Compiler {
private String timeout;
private String outputFolder;
//getters and setters
@Override
public String toString() {
return "Compiler{" +
"timeout='" + timeout + '\'' +
", outputFolder='" + outputFolder + '\'' +
'}';
}
}
}
Note:
@ConfigurationProperties supports both .properties and .yml file.
5. Nesting in @ConfigurationProperties
We can have nested properties in Lists, Maps, and Classes.
Let’s look at the example
public class Credential {
private String email;
private String password;
public String getEmail() {
return email;
}
public void setEmail(String email) {
this.email = email;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
}
We also update the NestedProperties class to use a List, a Map and the Credential class:
public class NestedProperties {
private String appName;
private int port;
private List<String> user;
private Map<String, String> additionalHeaders;
private Credential credential;
@Override
public String toString() {
return "NestedProperties{" +
"appName='" + appName + '\'' +
", port=" + port +
", user=" + user +
", additionalHeaders=" + additionalHeaders +
", credential=" + credential +
'}';
}
// getters and setters
}
The following properties file will set all the fields.
#Simple properties
mail.appName=Spring Boot Config Properties
mail.port=9090
#List properties
mail.user[0]=user1@mail.com
mail.user[1]=user2@mail.com
#Map Properties
mail.additionalHeaders.redelivery=true
mail.additionalHeaders.secure=true
#Object properties
mail.credentials.email=dummy@email.com
mail.credentials.password=password
6. Using @ConfigurationProperties on a @Bean Method
We can also use @ConfigurationProperties annotation on @Bean-annotated methods.
This approach may be particularly useful when we want to bind properties to a third-party component that’s outside of our control.
Let’s create a simple Book class that we’ll use in the next example:
public class Book {
private String bookTitle;
private Double price;
private String isbn;
//getters and setters
}
Now, let’s see how we can use @ConfigurationProperties on a @Bean method to bind externalized properties to the Item instance:
@Configuration
public class BeanConfigProperties {
@Bean
@ConfigurationProperties(prefix = "book")
public Book book()
{
return new Book();
}
}
#Book
book.bookTitle= New Book
book.price= 150
book.isbn = 3523634523f3423
7. Property Validation
@ConfigurationProperties provides validation of properties using the JSR-303 format. This allows all sorts of neat things. Let’s see an example.
public class Book {
@NotBlank
@Length(min = 3, max = 20)
private String bookTitle;
@Min(50)
@Max(2000)
private Double price;
private String isbn;
}
public class Credential {
@Pattern(regexp = "^[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,6}$")
private String email;
private String password;
}
This helps us reduce a lot of if-else conditions in our code and makes it look much cleaner and concise.
If any of these validations fail then the main application would fail to start with an IllegalStateException.
The Hibernate Validation framework uses standard Java bean getters and setters, so it’s important that we declare getters and setters for each of the properties.
8. Property Conversion
@ConfigurationProperties support conversion for multiple types to bind the properties to their corresponding beans.
8.1. Duration
We’ll start with looking at converting properties into Duration objects.
Here we have two fields of type Duration:
@ConfigurationProperties(prefix = "conversion")
public class PropertyConversion {
private Duration timeInDefaultUnit;
private Duration timeInNano;
...
}
And our properties file:
conversion.timeInDefaultUnit=100
conversion.timeInNano=20ns
As a result, the field timeInDefaultUnit will have a value of 10 milliseconds and timeInNano will have a value of 20 nanoseconds.
The supported units are ns, us, ms, s, m, h and d for nanoseconds, microseconds, milliseconds, seconds, minutes, hours and days respectively.
The default unit is milliseconds, which means if we don’t specify a unit next to the numeric value, Spring will convert the value to milliseconds.
We can also override default unit using @DurationUnit:
@DurationUnit(ChronoUnit.DAYS)
private Duration timeInDays;
and the corresponding property:
conversion.timeInDays=4
8.2. DataSize
Similarly, Spring Boot @ConfigurationProperties supports DataSize type conversion.
Let’s add 3 fields of type DataSize:
private DataSize sizeInDefaultUnit;
@DataSizeUnit(DataUnit.GIGABYTES)
private DataSize sizeInGB;
private DataSize sizeInTB;
and the corresponding properties:
conversion.sizeInDefaultUnit=400
conversion.sizeInGB=2
conversion.sizeInTB=4TB
In this case, the sizeInDefaultUnit value will be 300 bytes, as the default unit is bytes.
The supported units are B, KB, MB, GB and TB. We can also override the default unit using @DataSizeUnit.
8.3. Custom Converter
We can also add our own custom Converter to support converting a property to a specific class type.
Let’s add a simple class Book:
public class Book {
@NotBlank
@Length(min = 3, max = 20)
private String bookTitle;
@Min(50)
@Max(2000)
private Double price;
private String isbn;
//getters and setters
}
And we’ll create a custom converter to convert this property:
conversion.book = Book1,150,4354354353
We will need to implement the Converter interface, then use @ConfigurationPropertiesBinding annotation to register our custom Converter:
@Component
@ConfigurationPropertiesBinding
public class BookConverter implements Converter<String, Book> {
@Override
public Book convert(String s) {
String[] data = s.split(",");
return new Book(data[0], Double.parseDouble(data[1]), data[2]);
}
}
9. Profile Specific Configuration Properties
In addition to the standard application.properties file, Spring Boot also allows you to define profile-specific properties with the following naming convention –
application-{profile}.properties
The profile specific property files are loaded from the same location as the application.properties file, with profile-specific properties always overriding the default ones.
To illustrate this, Let’s define some profile-specific property files, and override some of the default properties –
application-dev.properties
spring.application.name=Spring Boot Tutorial - DEVELOPMENT
application-staging.properties
spring.application.name=Spring Boot Tutorial - STAGGING
application-prod.properties
spring.application.name=Spring Boot Tutorial
Now, we need to activate a spring profile so that the corresponding properties file is loaded by spring boot.
Activating a Spring Profile
You can set active profiles in many ways –
1. Using Application Properties
The default application.properties file is always loaded by Spring Boot. You can set active profiles in the application.properties file by adding the following property –
spring.profiles.active=staging
After adding the above property, Spring Boot will load application-staging.properties file as well, and override properties with the new values specified there.
2. Using Command line argument
You can set active profiles on startup by providing the spring.profiles.active command line argument like this –
# Packaging the app
mvn clean package -Dspring.profiles.active=staging
mvn spring-boot:run -Dspring.profiles.active=dev
3. Using Environment Variable
Lastly, you can also set active profiles using the SPRING_PROFILES_ACTIVE environment variable-
export SPRING_PROFILES_ACTIVE=prod
10. Conclusion
We have explored the @ConfigurationProperties annotation and saw some of the handy features it provides like relaxed binding and Bean Validation.
As usual, the code is available over on Github.
