Guide to @ConfigurationProperties in Spring Boot

1. Introduction

One handy feature of Spring Boot is externalized configuration and easy access to properties defined in properties files. An earlier article described various ways in which this can be done.

We are now going to explore the @ConfigurationProperties annotation in greater detail.

Further reading:

A Quick Guide to Spring @Value

Learn to use the Spring @Value annotation to configure fields from property files, system properties, etc.

Read more →

Properties with Spring and Spring Boot

Tutorial for how to work with properties files and property values in Spring.

Read more →

2. Setup

This article uses a fairly standard setup. We start by adding spring-boot-starter-parent as the parent in our pom.xml:

<!-- Inherit defaults from Spring Boot -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.1.3.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. Simple Properties

The official documentation advises that we isolate configuration properties into separate POJOs.

So let’s start by doing that:

@Configuration
@PropertySource("classpath:configprops.properties")
@ConfigurationProperties(prefix = "mail")
public class ConfigProperties {

    private String hostName;
    private int port;
    private String from;

    // standard getters and setters
}

We use @Configuration so that Spring creates a Spring bean in the application context.

We also use @PropertySource to define the location of our properties file. Otherwise, Spring uses the default location (classpath:application.properties).

@ConfigurationProperties works best with hierarchical properties that all have the same prefix. So we add a prefix of mail.

The Spring framework uses standard Java bean setters, so it is essential that we declare setters for each of the properties.

Note: If we don’t use @Configuration in the POJO, then we need to add @EnableConfigurationProperties(ConfigProperties.class) in the main Spring application class to bind the properties into the POJO:

@SpringBootApplication
@EnableConfigurationProperties(ConfigProperties.class)
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

That’s it! Spring will automatically bind any property defined in our property file that has the prefix mail and the same name as one of the fields in the ConfigProperties class.

Spring uses some relaxed rules for binding properties. So the following variations are all bound to the property hostName:

mail.hostName
mail.hostname
mail.host_name
mail.host-name
mail.HOST_NAME

We can use the following properties file to set all the fields:

#Simple properties
[email protected]
mail.port=9000
[email protected]

4. Nested Properties

We can have nested properties in Lists, Maps, and Classes.

Let us create a new Credentials class to use for some nested properties:

public class Credentials {
    private String authMethod;
    private String username;
    private String password;

    // standard getters and setters
}

We also update the ConfigProperties class to use a List, a Map and the Credentials class:

public class ConfigProperties {

    private String host;
    private int port;
    private String from;
    private List<String> defaultRecipients;
    private Map<String, String> additionalHeaders;
    private Credentials credentials;

    // standard getters and setters
}

The following properties file will set all the fields:

#Simple properties
[email protected]
mail.port=9000
[email protected]

#List properties
mail.defaultRecipients[0][email protected]
mail.defaultRecipients[1][email protected]

#Map Properties
mail.additionalHeaders.redelivery=true
mail.additionalHeaders.secure=true

#Object properties
mail.credentials.username=john
mail.credentials.password=password
mail.credentials.authMethod=SHA1

5. 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 Item class that we’ll use in the next example:

public class Item {
    private String name;
    private int size;

    // standard 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 ConfigProperties {

    @Bean
    @ConfigurationProperties(prefix = "item")
    public Item item() {
        return new Item();
    }
}

This way, any item-prefixed property will be mapped to the Item instance managed by the Spring context.

6. Property Validation

@ConfigurationProperties provides validation of properties using the JSR-303 format. This allows all sorts of neat things.

For example, let’s make the hostName property mandatory:

@NotBlank
private String hostName;

And the authMethod property from 1 to 4 characters long:

@Length(max = 4, min = 1)
private String authMethod;

And the port property from 1025 to 65536:

@Min(1025)
@Max(65536)
private int port;

Finally, the from property must match an email address format:

@Pattern(regexp = "^[a-z0-9._%+-][email protected][a-z0-9.-]+\\.[a-z]{2,6}$")
private String from;

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.

7. Property Conversion

@ConfigurationProperties support conversion for multiple types to bind the properties to their corresponding beans.

7.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=10
conversion.timeInNano=9ns

As a result, the field timeInDefaultUnit will have a value of 10 milliseconds and timeInNano will have a value of 9 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=2

7.2. DataSize

Similarly, Spring Boot @ConfigurationProperties supports DataSize type conversion.

Let’s add 3 fields of type DataSize:

private DataSize sizeInDefaultUnit;

private DataSize sizeInGB;

@DataSizeUnit(DataUnit.TERABYTES)
private DataSize sizeInTB;

and the corresponding properties:

conversion.sizeInDefaultUnit=300
conversion.sizeInGB=2GB
conversion.sizeInTB=4

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.

7.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 Employee:

public class Employee {
    private String name;
    private double salary;
}

And we’ll create a custom converter to convert this property:

conversion.employee=john,2000

to a filed of type Employee:

private Employee employee;

We will need to implement the Converter interface, then use @ConfigurationPropertiesBinding annotation to register our custom *Converter*:

@Component
@ConfigurationPropertiesBinding
public class EmployeeConverter implements Converter<String, Employee> {

    @Override
    public Employee convert(String from) {
        String[] data = from.split(",");
        return new Employee(data[0], Double.parseDouble(data[1]));
    }
}

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

Leave a Reply

Your email address will not be published.