{"id":6425,"date":"2020-09-10T08:10:25","date_gmt":"2020-09-10T12:10:25","guid":{"rendered":"http:\/\/springframework.guru\/?p=6425"},"modified":"2024-10-21T06:43:37","modified_gmt":"2024-10-21T10:43:37","slug":"java-bean-properties-binding","status":"publish","type":"post","link":"https:\/\/springframework.guru\/java-bean-properties-binding\/","title":{"rendered":"Properties Binding with Spring: Simplify Configuration with @ConfigurationProperties"},"content":{"rendered":"

Introduction<\/h2>\n

In this <\/span>article<\/a>,<\/span> we explained why we should externalise our application configuration data. We also provided configuration examples that use various methods supported by Spring Boot. Within these methods was the Java bean properties binding but it was less detailed. Therefore in this article, we are going to give more details about using the payment service in the previous <\/span>article<\/span><\/a>.\u00a0<\/span><\/p>\n

Our payment service requires merchant information which consists of many fields. We are not going to use @Value<\/code> annotation because it will be cumbersome work. Using @Value<\/code> requires us to annotate each and every property with @Value<\/code>. Our code will look untidy if we do so. A workaround is to group the merchant details together in a POJO class. This POJO class is the one referred to as Java Bean. Its properties will be bound to the configuration file data when annotated with @ConfigurationProperties<\/code>.It will be easier for us to maintain these properties because they are at a single place and our code will be cleaner. Let us take a look at the comparison between @Value<\/code> and @ConfigurationProperties<\/code> annotations.<\/span><\/p>\n

Features<\/h2>\n

The table below shows the features supported by each of the configuration methods provided by the annotations,\u00a0 @Value<\/code> and @ConfigurationProperties<\/code>.<\/span><\/p>\n\n\n\n\n\n\n\n
Feature<\/strong><\/td>\n@ConfigurationProperties<\/strong><\/td>\n@Value<\/strong><\/td>\n<\/tr>\n
Type-safety<\/td>\nYES<\/td>\nNO<\/td>\n<\/tr>\n
Relaxed-binding<\/td>\nYES<\/td>\nNO<\/td>\n<\/tr>\n
Meta-data support<\/td>\nYES<\/td>\nNO<\/td>\n<\/tr>\n
SpEL Evaluation<\/td>\nNO<\/td>\nYES<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

This comparison shows that the@ConfigurationProperties<\/code> ticks more boxes compared to @Value<\/code>. It is a better option for our use-case that involves many configuration properties.<\/span><\/p>\n

Properties Binding<\/h2>\n

In order for us to understand how the Java Bean Properties binding works and how it is configured. We will use a step by step guide using the payments service from the previous article<\/a><\/span>. <\/span>The payment service shall be receiving payments made by customers for vendor services provided. This implies that we will be dealing with more than one vendor each with a unique merchant account. We must be able to identify the merchant account for each transaction request received.<\/span><\/p>\n

Properties Names<\/h3>\n

Let us first list the individual properties of the merchant account. Let us indicate the data type of each so that it becomes easy for us to set up its configuration in a Spring Application using a POJO class and the @ConfigurationProperties<\/code> annotation.<\/span><\/p>\n\n\n\n\n\n\n\n\n\n
Configuration\/Setting<\/strong><\/td>\nName of property<\/strong><\/td>\nData type of property value<\/strong><\/td>\nProperty type<\/strong><\/td>\n<\/tr>\n
Merchant Account<\/td>\nmerchantaccount<\/td>\nkey\/value(Map)<\/td>\nObject<\/td>\n<\/tr>\n
<\/td>\nname<\/td>\nString<\/td>\n<\/td>\n<\/tr>\n
<\/td>\nusername<\/td>\nString<\/td>\n<\/td>\n<\/tr>\n
<\/td>\ncode<\/td>\nString<\/td>\n<\/td>\n<\/tr>\n
<\/td>\nnumber<\/td>\nNumber<\/td>\n<\/td>\n<\/tr>\n
<\/td>\ncurrency<\/td>\nString<\/td>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

We have identified the properties that we will use to get configuration values. Now let us create our properties file. In our case, we will use the YAML<\/code> <\/span>format.<\/span><\/p>\n

application.yml<\/em><\/p>\n

name: Maureen Sindiso Mpofu\nusername: momoe\ncode: MCA1230\nnumber: 771222279\ncurrency: ZWL<\/pre>\n
Properties Grouping<\/h3>\n
We now have our properties file, the next step is to bind them. To do this, first of all, we will create a Java<\/code><\/span>class as indicated below.<\/span><\/p>\n
public class MerchantAccount {\n private String name;\n private String username;\n private String code;\n private int number;\n private String currency;\n\n public String getName() {\n  return name;\n }\n\n public void setName(String name) {\n  this.name = name;\n }\n\n public String getUsername() {\n  return username;\n }\n\n public void setUsername(String username) {\n  this.username = username;\n }\n \n public String getCode() {\n  return code;\n }\n\n public void setCode(String code) {\n  this.code = code;\n }\n\n public int getNumber() {\n  return number;\n }\n\n public void setNumber(int number) {\n  this.number = number;\n }\n\n public String getCurrency() {\n  return currency;\n }\n\n public void setCurrency(String currency) {\n  this.currency = currency;\n }\n}<\/pre>\n
Enabling Java Bean Properties Binding<\/h3>\n
There are many ways of binding our properties defined in our configuration file to our Java<\/code> <\/span>class we created in the previous section<\/span>. We will annotate our Java<\/code> class with @ConfigurationProperties<\/code>. Inside this annotation, we will also specify the prefix of our properties so that Spring will be able to identify them in the properties file. In our case, the prefix is “merchantacccount”. The following are ways we can use to enable properties binding.<\/span><\/p>\n
Annotating the Java bean class with @Component<\/h4>\n
@Component\n@ConfigurationProperties(prefix = \"merchantaccount\")\npublic class MerchantAccount {\n   private String name;\n   private String userName;\n   private String code;\n   private int number;\n   private String currency;\n\n   \/\/getters and setters\n\n}\n<\/pre>\n
Declaring it as a bean in the Spring configuration class<\/h3>\n
This method is commonly used in scenarios where we want to bind the properties to third-party components.\u00a0 This is because most of the time we have no control of these third-party components. In the example below the merchant account class can be considered as a third-party component.<\/span><\/p>\n
@Configuration\npublic class PropertyConfigurations {\n    \n   @Bean\n   @ConfigurationProperties(prefix = \"merchantaccount\")\n   public MerchantAccount merchantAccount(){ \n      return new MerchantAccount();\n   }\n    \/\/other beans\n\n}\n<\/pre>\n
Using @EnableConfigurationproperties annotation<\/h3>\n
When using this method, we must also specify the configuration classes as indicated below. Let us say we had another configuration class for connection settings then we can include it as well in this same annotation as indicated below.<\/p>\n
@SpringBootApplication \n@EnableConfigurationProperties({MerchantAccount.class, ConnectionSettings.class})\npublic class MyApplication {\n   \n}\n<\/pre>\n
Using @EnableConfigurationpropertiesScan annotation<\/h3>\n
This method will scan the package passed in the annotation. Any classes annotated with  @ConfigurationProperties<\/code><\/span> found in this package will be bound automatically.<\/p>\n
@SpringBootApplication \n@EnableConfigurationPropertiesScan(\u201ccom.springframeworkguru\u201d)\npublic class MyApplication {\n}<\/pre>\n
Relaxed Binding<\/h2>\n
In our example, the property name \u201cusername\u201d in our Java<\/code> class matches the one defined in our configuration file. However, it is also possible to have different forms of property names in the configuration file for instance \u201cusername\u201d can also be represented as below. This is known as relaxed binding.<\/span><\/p>\n
merchantaccount:\n username: momoe        \/\/exact match\n userName: momoe        \/\/standard camel case\n user-name: momoe       \/\/kebab case recommended for use in .properties or .yml files\n user_name: momoe       \/\/underscore notation an alternative to kebab notation\n USER_NAME: momoe   \/\/uppercase format recommended when using system environment variables\n\n<\/pre>\n
Constructor Binding<\/h2>\n
Take a look at this article<\/a> for more details.<\/p>\n
Properties Conversion<\/h2>\n
When binding external properties to the @ConfigurationProperty<\/code> annotated Java Beans, Spring Boot attempts to match them to the target type. However, it is also possible to provide a custom type converter. There are various ways of providing a custom converter. Let us look at them in the following sections.<\/span><\/p>\n
@ConfigurationPropertiesBinding annotation<\/h3>\n
First of all, we need to specify a property to our Java bean that has no default converter. Let us add a property of type LocalDateTime.<\/span><\/p>\n
@ConfigurationProperties(prefix = \"merchantaccount\")\npublic class MerchantAccount {\n   private String name;\n   private String username;\n   private String code;\n   private int number;\n   private String currency;\n   private final LocalDateTime localDateTime;\n   \n   public LocalDateTime getLocalDateTime() {\n     return localDateTime;\n    }\n   public void setLocalDateTime(LocalDateTime localDateTime) {\n    this.localDateTime = localDateTime;\n    }\n\/\/other getters and setters\n}\n<\/pre>\n
Then configure its value in our external configuration file.<\/span><\/p>\n
merchantaccount:\n name: Maureen Sindiso Mpofu\n username: momoe\n code: MCA1230\n number: 771222279\n currency: ZWL\n localDateTime: 2011-12-03T10:15:30\n<\/pre>\n
We must provide a custom converter so that we do not get a binding exception during application startup. We will use the annotation @ConfigurationPropertiesBinding<\/code> <\/span>as shown below. This custom converter will convert the String input type in our configuration file to a LocalDateTime<\/code> . Take note that we must register this converter as a bean indicated by @Component<\/code> annotation.<\/span><\/p>\n
@Component\n@ConfigurationPropertiesBinding\npublic class LocalDateTimeConverter implements Converter<String,LocalDateTime> {\n\n   @Override\n   public LocalDateTime convert(String s) {\n       return LocalDateTime.parse(s, DateTimeFormatter.ISO_LOCAL_DATE_TIME);\n   }\n}\n<\/pre>\n
Conversion Service bean<\/h3>\n
We can use the ConversionService bean instead of the @ConfigurationPropertiesBinding<\/code> annotation. Spring picks up a ConversionService and uses it whenever type conversion needs to be performed. This conversion service is like any other bean thus can be injected into other beans and invoked directly. The default ConversionService<\/code> can convert between strings, numbers, enums, collections, maps, and other common types.<\/span><\/p>\n
However, there are other converters that are not provided by default for instance conversion to LocalDateTime<\/code>. We can supplement the default converter with our own custom converter by defining a conversion service bean as indicated below. We only added our custom converter through the factory bean.<\/span><\/p>\n
@Bean\npublic  ConversionServiceFactoryBean conversionService(){\n  ConversionServiceFactoryBean conversionServiceFactoryBean= new ConversionServiceFactoryBean();\n  Set<Converter> converters = new HashSet<>();\n  converters.add(new CustomLocalDateTimeConverter());\n   conversionServiceFactoryBean.setConverters(converters);\n  return conversionServiceFactoryBean;\n}\n<\/pre>\n
After we have defined our conversion service bean, Spring will be able to bind the value of LocalDateTime<\/code> provided in our properties configuration file.<\/span><\/p>\n
CustomEditorConfigurer<\/h3>\n
If we had declared a field of type java.util.Date then we must tell Spring how it will bind the Date value specified in the property configuration file to this type. We can do this by\u00a0 configuring Spring\u2019s built-in\u00a0 CustomDateEditor<\/code>\u00a0class as indicated below.<\/span><\/p>\n
public class CustomLocalDateTimeEditorRegistrar implements PropertyEditorRegistrar {\n   @Override\n   public void registerCustomEditors(PropertyEditorRegistry propertyEditorRegistry) {\n       propertyEditorRegistry.registerCustomEditor(Date.class,\n               new CustomDateEditor(new SimpleDateFormat(\"yyyy-MM-dd\"),false));\n   }\n}\n<\/pre>\n
We then register it through the CustomeditorConfigurer<\/code>\u00a0 bean factory class as indicated below.<\/span><\/p>\n
@Bean\npublic CustomEditorConfigurer customEditorConfigurer(){\n   CustomEditorConfigurer customEditorConfigurer = new CustomEditorConfigurer();\n   PropertyEditorRegistrar[] registrars = {new CustomLocalDateTimeEditorRegistrar()};\n   customEditorConfigurer.setPropertyEditorRegistrars(registrars);\n   return customEditorConfigurer;\n}\n<\/pre>\n
Duration Conversion<\/h3>\n
Spring supports duration expressions. Let us add two more properties to our Java-bean class that are of type java.time.Duration<\/code>\u00a0 i.e session timeout and read timeout.<\/span><\/p>\n
@ConfigurationProperties(prefix = \"merchantaccount\")\npublic class MerchantAccount {\n    private final Duration sessionTimeout;\n    private final Duration readTimeout;\n    \/\/other properties\n    public Duration getSessionTimeout() {\n      return sessionTimeout;\n    }\n   public void setSessionTimeout(Duration sessionTimeout) {\n     this.sessionTimeout = sessionTimeout;\n   }\n   public Duration getReadTimeout() {\n   return readTimeout;\n  }\n  public void setReadTimeout(Duration readTimeout) {\n   this.readTimeout = readTimeout;\n  } \n   \/\/ setters and getters of other fields\n}\n<\/pre>\n
Then in our properties file let us specify their values as indicated below.<\/span><\/p>\n
merchantaccount:\n    sessionTimeout: 15\n    readTimeout: 10<\/pre>\n
When we execute our application, the default unit for both session timeout and read timeout in milliseconds. This default unit can be overridden using either of the methods defined below.<\/span><\/p>\n
@DurationUnit annotation<\/h4>\n
We can use the @DurationUnit<\/code>\u00a0 annotation directly on the field. We noticed that in some Spring boot versions this annotation does not work with constructor binding,\u00a0 the default unit takes precedence. A workaround is to use setters.<\/span><\/p>\n
@ConfigurationProperties(prefix = \"merchantaccount\")\npublic class MerchantAccount {\n    @DurationUnit(ChronoUnit.SECONDS)\n    private Duration readTimeout;\n    \/\/other fields\n}\n<\/pre>\n
Coupling value and unit<\/h4>\n
This is more readable. In the properties file, we can append the unit symbols to the value. Let us reset our read timeout and session timeout values to seconds. We do this by appending ‘s’ to their values in our configuration file as indicated below.<\/span><\/p>\n
merchantaccount:\n    sessionTimeout: 15s\n    readTimeout: 10s<\/pre>\n
The supported units are:<\/span><\/p>\n