Skip to content

Commit e533ce3

Browse files
committed
Merge branch '2.2.x'
Closes gh-21028
2 parents 636a476 + d27e437 commit e533ce3

File tree

1 file changed

+33
-3
lines changed

1 file changed

+33
-3
lines changed

spring-boot-project/spring-boot-docs/src/docs/asciidoc/spring-boot-features.adoc

Lines changed: 33 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -630,6 +630,7 @@ You can provide default values for your application in `application.properties`
630630
These default values can then be overridden at runtime with a different file located in one of the custom locations.
631631

632632
NOTE: If you use environment variables rather than system properties, most operating systems disallow period-separated key names, but you can use underscores instead (for example, configprop:spring.config.name[format=envvar] instead of configprop:spring.config.name[]).
633+
See <<boot-features-external-config-relaxed-binding-from-environment-variables>> for details.
633634

634635
NOTE: If your application runs in a container, then JNDI properties (in `java:comp/env`) or servlet context initialization parameters can be used instead of, or as well as, environment variables or system properties.
635636

@@ -1201,9 +1202,8 @@ NOTE: The `prefix` value for the annotation _must_ be in kebab case (lowercase a
12011202
| Standard YAML list syntax or comma-separated values
12021203

12031204
| Environment Variables
1204-
| Upper case format with underscore as the delimiter.
1205-
`_` should not be used within a property name
1206-
| Numeric values surrounded by underscores, such as `MY_ACME_1_OTHER = my.acme[1].other`
1205+
| Upper case format with underscore as the delimiter (see <<boot-features-external-config-relaxed-binding-from-environment-variables>>).
1206+
| Numeric values surrounded by underscores (see <<boot-features-external-config-relaxed-binding-from-environment-variables>>)`
12071207

12081208
| System properties
12091209
| Camel case, kebab case, or underscore notation
@@ -1212,6 +1212,10 @@ NOTE: The `prefix` value for the annotation _must_ be in kebab case (lowercase a
12121212

12131213
TIP: We recommend that, when possible, properties are stored in lower-case kebab format, such as `my.property-name=acme`.
12141214

1215+
1216+
1217+
[[boot-features-external-config-relaxed-binding-maps]]
1218+
===== Binding Maps
12151219
When binding to `Map` properties, if the `key` contains anything other than lowercase alpha-numeric characters or `-`, you need to use the bracket notation so that the original value is preserved.
12161220
If the key is not surrounded by `[]`, any characters that are not alpha-numeric or `-` are removed.
12171221
For example, consider binding the following properties to a `Map`:
@@ -1231,6 +1235,32 @@ The properties above will bind to a `Map` with `/key1`, `/key2` and `key3` as th
12311235
NOTE: For YAML files, the brackets need to be surrounded by quotes for the keys to be parsed properly.
12321236

12331237

1238+
[[boot-features-external-config-relaxed-binding-from-environment-variables]]
1239+
===== Binding from Environment Variables
1240+
Most operating systems impose strict rules around the names that can be used for environment variables.
1241+
For example, Linux shell variables can contain only letters (`a` to `z` or `A` to `Z`), numbers (`0` to `9`) or the underscore character (`_`).
1242+
By convention, Unix shell variables will also have their names in UPPERCASE.
1243+
1244+
Spring Boot's relaxed binding rules are, as much as possible, designed to be compatible with these naming restrictions.
1245+
1246+
To convert a property name in the canonical-form to an environment variable name you can follow these rules:
1247+
1248+
* Replace dots (`.`) with underscores (`_`).
1249+
* Remove any dashes (`-`).
1250+
* Convert to uppercase.
1251+
1252+
For example, the configuration property `spring.main.log-startup-info` would be an environment variable named `SPRING_MAIN_LOGSTARTUPINFO`.
1253+
1254+
NOTE: Underscores cannot be used to replace the dashes in property names.
1255+
If you attempt to use `SPRING_MAIN_LOG_STARTUP_INFO` with the example above, no value will be bound.
1256+
1257+
Environment variables can also be used when binding to object lists.
1258+
To bind to a `List`, the element number should be surrounded with underscores in the variable name.
1259+
1260+
For example, the configuration property `my.acme[0].other` would use an environment variable named `MY_ACME_0_OTHER`.
1261+
1262+
1263+
12341264
[[boot-features-external-config-complex-type-merge]]
12351265
==== Merging Complex Types
12361266
When lists are configured in more than one place, overriding works by replacing the entire list.

0 commit comments

Comments
 (0)