Spring Boot - @ConfigurationProperties Example

In Spring Boot, the @ConfigurationProperties annotation allows us to map the resource files such as properties or YAML files to Java Bean object.

This annotation is applied to a class or a @Bean method in a @Configuration class to map or validate the external properties or YAML files.

This post shows how to use the @ConfigurationProperties in Spring Boot application.

Tools and technologies used for this application are -

Spring Boot 1.5.8.RELEASE
Java SE 1.8
Maven 3.5.2
Eclipse Neon.3 (4.6.3)

Using @ConfigurationProperties in Spring Boot

First, you need to define some properties in your application.properties file as follows.

myapp.mail.to=sunil@example.com
myapp.mail.host=mail.example.com
myapp.mail.port=250

Second, create a bean class with setter and getter methods and annotated it with @ConfigurationProperties as annotation.

@ConfigurationProperties(prefix="myapp.mail")
public class MailProperties {

  private String to;
  private String host;
  private int port;

  //Setter and getter methods
}

Third, register the @ConfigurationProperties bean in your @Configuration class using the @EnableConfigurationProperties annotation.

@Configuration
@EnableConfigurationProperties(MailProperties.class)
public class SpringBootApp {
  
}

Mapping collection or array in @ConfigurationProperties

To map collection or array in @ConfigurationProperties bean, you need to define the comma-separated values (properties) in your application.properties file.

myapp.mail.cc=mike@example.com,david@example.com
myapp.mail.bcc=sumit@example.com,admin@example.com

In your bean class, you can use the List or array of String to map collection properties as follows.

@ConfigurationProperties(prefix="myapp.mail")
public class MailProperties {

  //...
  private String[] cc;
  private List<String> bcc;
  
  //Setter and getter methods
}

Mapping nested properties in @ConfigurationProperties

To map the nested properties, first define the some properties in your application.properties file as follows.

myapp.mail.credential.user-name=sunil1234
myapp.mail.credential.password=xyz@1234

In your @ConfigurationProperties bean, create a nested bean with setter and getter methods as follows.

@ConfigurationProperties(prefix="myapp.mail")
public class MailProperties {

  //...
  
  private Credential credential = new Credential();

  //...

  public class Credential {

    private String userName;
    private String password;

    //Setter and Getter methods

  }

}

Validating @ConfigurationProperties

To validate the properties of a @ConfigurationProperties, first you need to add the validation-api and hibernate-validator dependencies in your classpath.

If you are using maven, add the following dependencies in your pom.xml file.

<dependency>
  <groupId>org.hibernate.validator</groupId>
  <artifactId>hibernate-validator</artifactId>
  <version>6.0.5.Final</version>
</dependency>
<dependency>
  <groupId>javax.validation</groupId>
  <artifactId>validation-api</artifactId>
  <version>2.0.0.Final</version>
</dependency>

Second, annotate the @ConfigurationProperties bean class with @Validated annotation to be validated by Spring Boot.

Use the javax.validation constraint annotations to validate the properties of the @ConfigurationProperties bean.

@ConfigurationProperties(prefix="myapp.mail")
@Validated
public class MailProperties {
 
  @Email
  private String to;
  @NotBlank
  private String host;
   //...
   //...
}

To validate the nested properties, you must annotate the associated field as @Valid to trigger its validation.

@ConfigurationProperties(prefix="myapp.mail")
@Validated
public class MailProperties {

  //...

  @Valid
  private Credential credential = new Credential();

  //...

  public class Credential {
    @NotBlank
    private String userName;
    @Size(max = 15, min = 6)
    private String password;
    //...
  }

}

Complete Example

Open pom.xml file and add the following dependencies in it.

pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.boraji.tutorial.springboot</groupId>
  <artifactId>spring-boot-configuration-properties-example</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <name>Spring Boot Configuration Properties Example</name>
  <properties>
    <java.version>1.8</java.version>
  </properties>
  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>1.5.8.RELEASE</version>
  </parent>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter</artifactId>
    </dependency>

    <dependency>
      <groupId>org.hibernate.validator</groupId>
      <artifactId>hibernate-validator</artifactId>
      <version>6.0.5.Final</version>
    </dependency>
    <dependency>
      <groupId>javax.validation</groupId>
      <artifactId>validation-api</artifactId>
      <version>2.0.0.Final</version>
    </dependency>

  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</project>

application.properties

#Mapping single properties
myapp.mail.to=sunil@example.com
myapp.mail.host=mail.example.com
myapp.mail.port=250

#Mapping list or array
myapp.mail.cc=mike@example.com,david@example.com
myapp.mail.bcc=sumit@example.com,admin@example.com

#Mapping nested POJO class
myapp.mail.credential.user-name=sunil1234
myapp.mail.credential.password=xyz@1234

An equivalent YAML file will look like this -

application.yml

myapp: 
  mail: 
    to: sunil@example.com
    host: mail.example.com
    port: 250
    cc: 
      - mike@example.com
      - david@example.com
    bcc: 
      - sumit@example.com
      - admin@example.com
    credential:
      user-name: sunil1234
      password: xyz@1234

MailProperties.java

package com.boraji.tutorial.springboot.config;

import java.util.List;

import javax.validation.Valid;
import javax.validation.constraints.Email;
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.Size;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;

@ConfigurationProperties(prefix="myapp.mail")
@Validated
public class MailProperties {

  @Email
  private String to;
  @NotBlank
  private String host;
  private int port;
  private String[] cc;
  private List<String> bcc;

  @Valid
  private Credential credential = new Credential();

  //Setter and Getter methods

  public class Credential {
    @NotBlank
    private String userName;
    @Size(max = 15, min = 6)
    private String password;

    //Setter and Getter methods

  }

}

Create a simple MailService.java file to print the MailProperties's properties as follows.

MailService.java

package com.boraji.tutorial.springboot.service;

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

import com.boraji.tutorial.springboot.config.MailProperties;

@Component
public class MailService {
  
  @Autowired
  private MailProperties mailProperties;

  public void print() {
    System.out.println("Mail TO = " + mailProperties.getTo());
    System.out.println("HOST = " + mailProperties.getHost());
    System.out.println("PORT = " + mailProperties.getPort());
    System.out.println();
    
    //Print list or array
    System.out.println("Mail CC = " + String.join(", ", mailProperties.getCc()));
    System.out.println("Mail BCC = " + mailProperties.getBcc());
    System.out.println();
    
    //Print nested bean's properties
    System.out.println("User Name = " + mailProperties.getCredential().getUserName());
    System.out.println("Password = " + mailProperties.getCredential().getPassword());
  }
}

Create a main class to the test the @ConfigurationProperties bean.

SpringBootApp.java

package com.boraji.tutorial.springboot;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.ApplicationContext;

import com.boraji.tutorial.springboot.config.MailProperties;
import com.boraji.tutorial.springboot.service.MailService;

@SpringBootApplication
@EnableConfigurationProperties(MailProperties.class)
public class SpringBootApp {

  public static void main(String[] args) {
    ApplicationContext context = SpringApplication.run(SpringBootApp.class, args);
    MailService mailService = context.getBean(MailService.class);
    mailService.print();
  }
  
}