Generic Top

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2:

>> CHECK OUT THE COURSE

1. Introduction

One very useful 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.

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.1.RELEASE</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>

The latest version of Spring Boot can be found on the maven central here.

In order 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.13.Final</version>
</dependency>

The getting started with Hibernate Validator page has more details, and the latest version of hibernate-validator can be found here.

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 important that we declare setters for each of the properties.

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. Property Validation

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

So let us 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 is important that we declare getters and setters for each of the properties.

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

Generic bottom

I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2:

>> CHECK OUT THE COURSE

newest oldest most voted
Notify of
sanjeev kumar
Guest
sanjeev kumar

Very nice article. Could you please share how to load properties files which are located in external directories and sub directories.
I tried
@PropertySource(value=”file:W:\myHome\Env\conf, W:\myHome\Env\conf\spring)
I am only providing the path & under that path are various properties file which I would like to load.

Also in application.properties I did this
spring.config.location=file:W:\myHome\Env\conf, W:\myHome\Env\conf\spring
But it is not working.
Could you please suggest.
Thank you

Grzegorz Piwowarek
Guest
Grzegorz Piwowarek

It’s definitely possible. On your place, I would try to setup PropertySourcesPlaceholderConfigurer bean properly. Then it should be easy to access those properties

sanjeev kumar
Guest
sanjeev kumar

Thank you. I tried this
@Bean
public static PropertySourcesPlaceholderConfigurer propertySources() {
PropertySourcesPlaceholderConfigurer ppConfig = new PropertySourcesPlaceholderConfigurer();
Resource[] resources = new ClassPathResource[]
{ new ClassPathResource( “W:\myHome\Env\conf\spring” ) };
ppConfig.setLocations( resources );
return ppConfig;
}
Class path resource W:/myHome/Env/conf/spring cannot be opened because it does not exist. The path is correct.

Grzegorz Piwowarek
Guest
Grzegorz Piwowarek

Try FileSystemResource instead of ClassPathResource. It’s not the classpath anymore 🙂

Colin Ma
Guest
Colin Ma

hey Grrzegorz I have a property in my property file. The property is:
a.b.c;

In my property class I have

@RefreshScope
@Configuration
@ConfigurationProperties(prefix = “a”)

According to the article, because of relaxed binding I should be able to do something like:

private Sting aB; //or a_b

I then set up getters and setters, but it’s not being read in at all as expected. I have other properties such as a.d and a.e that are being read in properly, so I know the initial set up is correct.

Any idea what might be the issue?

Grzegorz Piwowarek
Guest
Grzegorz Piwowarek

If you have a property “a.b.c”, it expects some nested object “b” to be there (and have a field “c” in it). Just like with theCredentials credentialsat the end of the section 2.

Try using a properties entry of “a.b” and defining a field

private String b;

Colin Ma
Guest
Colin Ma

if I do have the private String b how do i access the .c?

Grzegorz Piwowarek
Guest
Grzegorz Piwowarek

In this case, you can’t. It needs to be an object that has a field “c”.

Revisit section 2, there you have a property entry:
mail.credentials.username=john

and it works only because there is a Credentials object that has a field “username”.

In other words, your example would work if you had a field:
private MyCustomObject b;
And MyCustomObject would need to have a field “c”.

Srinivas T
Guest
Srinivas T

Is it possible to use @ConfigurationProperties in non boot applications? I have following scenario: – I have developed a framework jar module for Mongo db persistence, this framwork is responsible to connect to DB and provides api’s to the clients. In this framework I have configuration object which has the Mongo DB connection and other details. I have used @Value annotation to load the properties from client application (Non boot application) configuration (Actual parent application which uses framework jar) and everything works fine. – Now I want to use this same framework jar with Spring boot application where I will… Read more »

Grzegorz Piwowarek
Guest
Grzegorz Piwowarek

Well, @ConfigurationProperties comes from the boot package so if you do not have a Boot on your classpath, it should not be there. So how come can you use it in a non-boot application?

The scenario you are describing is tricky but it should be doable – check the YamlPropertiesFactoryBean class. Maybe you could try using for loading properties using the “oldschool” Spring way? In this case, it would work in boot and non-boot environments

sirine beji
Guest
sirine beji

I need to externalize the parameters set in my application.properties using environmental variables. This is my application.properties file:

spring.datasource.url= jdbc:mysql://${MYSQL_URL}:${MYSQL_PORT}/${MYSQL_DBNAME}
spring.datasource.username= ${MYSQL_USERNAME}
spring.datasource.password= ${MYSQL_PASSWORD}
spring.datasource.driver-class-name= com.mysql.jdbc.Driver
spring.jpa.hibernate.ddl-auto= update
spring.jpa.properties.hibernate.dialect= org.hibernate.dialect.MySQL5Dialect
And those ${—} are Environmental Variables. But when I try to run my application I get this error:

Property: spring.datasource.url
Value: jdbc:mysql://${MYSQL_URL}:${MYSQL_PORT}/${MYSQL_DBNAME}
Origin: class path resource [application.properties]:1:24
Reason: Could not resolve placeholder ‘MYSQL_URL’ in value “jdbc:mysql://${MYSQL_URL}:

Grzegorz Piwowarek
Guest
Grzegorz Piwowarek

You do not need to bind them to a properties file. You can simply inject them directly using @Value(“${MYSQL_USERNAME}”)