[Spring] @Value Annotation

Src: A Quick Guide to Spring @Value | Baeldung Noted: 2023-08-23

Overview

The @Value Spring annotation can be used for injecting values into fields in Spring-managed beans, and it can be applied at the field or constructor/method parameter level.

Setting Up the Application

To configure a simple Spring application configuration class for describe this annotation. We needs a properties file to define the values we want to inject with the @Value annotation. And so, we'll first need to define a @PropertySource in our configuration class — with the properties file name.

Let's define the properties file:

value.from.file=Value got from the file
priority=high
listOfValues=A,B,C

Usage Examples

Valued

As a basic and mostly useless example, we can only inject “string value” from the annotation to the field:

@Value("string value")
private String stringValue;

上面語法在 annotation 直接給值, 將 stringValue 設為 "string value", 效果和 private String stringValue = "string value" 是一樣的. 實務上並無使用 annotation 的意義.

PropertySource

Using the @PropertySource annotation allows us to work with values from properties files with the @Value annotation.

In the following example, we get Value got from the file assigned to the field:

@Value("${value.from.file}")
private String valueFromFile;

類似 BASH 的字串處理, 字串中的 ${VARIABLE} 會先行解析為對應的值. 而 Spring Framework 中會找尋 application properties 是否存在對應的 Key.

System properties

We can also set the value from system properties with the same syntax.

Let's assume that we have defined a system property named systemValue:

@Value("${systemValue}")
private String systemValue;

Default value

Default values can be provided for properties that might not be defined. Here, the value some default will be injected:

@Value("${unknown.param:some default}")
private String someDefault;

@Value annotation 各種物件 default value 的進一步介紹可參考 @Value Defaults

Properties priority

If the same property is defined as a system property and in the properties file, then the system property would be applied.

Suppose we had a property priority defined as a system property with the value System property and defined as something else in the properties file. The value would be System property:

@Value("${priority}")
private String prioritySystemProperty;

在 Sprint Framework 中, System property 的優先度高於其他設定, 若有多個 property 中有相同名字, 會以 System property 為引用的值.

List / Array

To inject a bunch of values, it would be convenient to define them as comma-separated values for the single property in the properties file or as a system property and to inject into an array.

In the first section, we defined comma-separated values in the listOfValues of the properties file, so the array values would be [“A”, “B”, “C”]:

@Value("${listOfValues}")
private String[] valuesArray;

Advanced Examples With SpEL

We can also use SpEL expressions to get the value.

If we have a system property named priority, then its value will be applied to the field:

@Value("#{systemProperties['priority']}")
private String spelValue;

If we have not defined the system property, then the null value will be assigned.

上面語法讀取 systemProperties 中的 priority 來注入使用. 透過 SpEL 來讀取 property 可避免多個 property 有相同 key 導致執行時錯誤.

若 PropertySource 中有 priority 的值為 "propertySource priority", 而 systemProperty 中找不到 priority:

@Value("${priority}")
private String priorityProperty;

@Value("#{systemProperties['priority']}")
private String spelValue;

priorityProperty 的值為 "propertySource priority", 而 spelValue 為 null.

default value

The default value in the SpEL expression a bit complex then behind, some default value for the field if the system property is not defined:

@Value("#{systemProperties['unknown'] ?: 'some default'}")
private String spelSomeDefault;

from other beans

Suppose we have a bean named someBean with a field someValue equal to 10. Then, 10 will be assigned to the field:

@Value("#{someBean.someValue}")
private Integer someBeanValue;

List

We can manipulate properties to get a List of values, here, a list of string values A, B, and C:

@Value("#{'${listOfValues}'.split(',')}")
private List<String> valuesList;

Using @Value With Maps

We can also use the @Value annotation to inject a Map property.

First, we'll need to define the property in the {key: ‘value' } form in our properties file:

valuesMap={key1: '1', key2: '2', key3: '3'}

Note that the values in the Map must be in single quotes.

Now we can inject this value from the property file as a Map:

@Value("#{${valuesMap}}")
private Map<String, Integer> valuesMap;

If we need to get the value of a specific key in the Map, all we have to do is add the key's name in the expression:

@Value("#{${valuesMap}.key1}")
private Integer valuesMapKey1;

If we're not sure whether the Map contains a certain key, we should choose a safer expression that will not throw an exception but set the value to null when the key is not found:

@Value("#{${valuesMap}['unknownKey']}")
private Integer unknownMapKey;

We can also set default values for the properties or keys that might not exist:

@Value("#{${unknownMap : {key1: '1', key2: '2'}}}")
private Map<String, Integer> unknownMap;

@Value("#{${valuesMap}['unknownKey'] ?: 5}")
private Integer unknownMapKeyWithDefaultValue;

Map entries can also be filtered before injection.

Let's assume we need to get only those entries whose values are greater than one:

@Value("#{${valuesMap}.?[value>'1']}")
private Map<String, Integer> valuesMapFiltered;

We can also use the @Value annotation to inject all current system properties:

@Value("#{systemProperties}")
private Map<String, String> systemPropertiesMap;

Using @Value With Constructor Injection

When we use the @Value annotation, we're not limited to a field injection. We can also use it together with constructor injection.

Let's see this in practice:

@Component
@PropertySource("classpath:values.properties")
public class PriorityProvider {

    private String priority;

    @Autowired
    public PriorityProvider(@Value("${priority:normal}") String priority) {
        this.priority = priority;
    }

    // standard getter
}

In the above example, we inject a priority directly into our PriorityProvider‘s constructor.

Note that we also provide a default value in case the property isn't found.

Using @Value With Setter Injection

Analogous to the constructor injection, we can also use @Value with setter injection.

Let's take a look:

@Component
@PropertySource("classpath:values.properties")
public class CollectionProvider {

    private List<String> values = new ArrayList<>();

    @Autowired
    public void setValues(@Value("#{'${listOfValues}'.split(',')}") List<String> values) {
        this.values.addAll(values);
    }

    // standard getter
}

We use the SpEL expression to inject a list of values into the setValues method.

Using @Value With Records

Java 14 introduced records to facilitate the creation of an immutable class. The Spring framework supports @Value for record injection since version 6.0.6:

@Component
@PropertySource("classpath:values.properties")
public record PriorityRecord(@Value("${priority:normal}") String priority) {}

Here, we inject the value directly into the record's constructor.

Conclusion

This article examined the various possibilities of using the @Value annotation with simple properties defined in the file, with system properties, and with properties calculated with SpEL expressions.

As always, the example application is available on the GitHub project.

See Also

• GitHub project
• Value Defaults