Relaxed Binding 2.0

Spring Boot Relaxed Binding 2.0

The purpose of this page is to describe in detail the new rules for binding properties from the environment as well as reading them from the environment.

Setting properties in the environment

Spring Boot allows you to configure properties for your application using properties files, YAML files, environment variables and command-line arguments. The relaxed rules for specifying properties in this manner remain unchanged. There are however some enhancements made to these rules:

Collections in environment variables:

The [ and ] characters cannot be used in environment variable names so instead a special form of _ is used. Any numeric value surrounded by underscores is converted to the [,] form. For example:

• MY_FOO_1_ = my.foo[1]

• MY_FOO_1_BAR = my.foo[1].bar

• MY_FOO_1_2_ = my.foo[1][2]`

In addition, if an environment variable ends in a number the trailing _ may be omitted:

• MY_FOO_1 = my.foo[1]

• MY_FOO_1_2 = my.foo[1][2]`

Comma-separated lists can be specified in a single line as:

• MY_FOO__ = a,b,c

Merging Collections:

If Collection properties are specified in multiple property sources, only the elements from the property source with the highest precedence will be used. Properties from different property sources will NOT be combined when binding to a Collection. For example, if a .properties file has

foo[0] = 1
foo[1] = 2

and the Environment has

foo=3,4

the bound collection will only contain the elements 3 and 4.

Reading properties from the environment

If you read properties from the environment in your application, you will now need to use the uniform name for the property.

A uniform name

• Is composed of elements separated in dots.

• The last dot separates the prefix from the property name.

• Must be alpha-numeric (a-z 0-9)

• Must be lowercase

• Hyphen to can be used to separate words.

• The only other characters permitted are [ and ] which are used to indicate indexes.

• Cannot start with a number.

For example a property as can be read from the environment as,

this.environment.containsProperty("spring.jpa.database-platform")

Note	Using the @Value annotation also requires specifying the properties in the uniform format.

Migration Path

The new Binding API has replaced a lot of the old classes used for relaxed binding and relaxed property resolution.

• The RelaxedDataBinder has been replaced by the Binder class. For example, the following POJO,

class FooProperties {

	private String bar;
	public String getBar() { ... }
        void setBar(String bar) { ... }
}

can be bound as follows:

Binder binder = Binder.get(environment);
FooProperties foo = binder.bind("foo", Bindable.of(FooProperties.class)).get();

Details about the bind method can be found in the javadoc.

• The RelaxedPropertyResolver which was used to resolve properties in a relaxed way has also been removed. Instead, properties should be read directly from the environment using the uniform format:

this.environment.containsProperty("spring.jpa.database-platform")

Constraints

• Collections must always be specified as a whole. Omitting indices will lead to an UnboundConfigurationPropertiesException For example, the following is not allowed,

foo[0] = a
foo[2] = b

• Properties from non-enumerable property sources cannot be bound in a relaxed manner.

• If a class annotated with @ConfigurationProperties needs to be validated, it must be annotated with @Validated.