From 4e8592ffc5b91a3e8e39f378825cf3f2bce4c3ef Mon Sep 17 00:00:00 2001 From: Madhura Bhave Date: Fri, 14 Jul 2017 12:03:11 -0700 Subject: [PATCH] Update documentation with new relaxed rules Closes gh-9025 --- spring-boot-docs/src/main/asciidoc/howto.adoc | 11 +++--- .../main/asciidoc/spring-boot-features.adoc | 34 ++++++++++++++++--- 2 files changed, 33 insertions(+), 12 deletions(-) diff --git a/spring-boot-docs/src/main/asciidoc/howto.adoc b/spring-boot-docs/src/main/asciidoc/howto.adoc index ea9358b5d2..5855bc6006 100644 --- a/spring-boot-docs/src/main/asciidoc/howto.adoc +++ b/spring-boot-docs/src/main/asciidoc/howto.adoc @@ -74,12 +74,9 @@ rules of thumb: properties, thus `ServerProperties` has `prefix="server"` and its configuration properties are `server.port`, `server.address` etc. In a running Actuator app look at the `configprops` endpoint. -* Look for use of `RelaxedPropertyResolver` to pull configuration values explicitly out of the - `Environment`. It often is used with a prefix. -* Look for `@Value` annotations that bind directly to the `Environment`. This is less - flexible than the `RelaxedPropertyResolver` approach, but does allow some relaxed binding, - specifically for OS environment variables (so `CAPITALS_AND_UNDERSCORES` are synonyms - for `period.separated`). +* Look for uses of the `bind` method on the `Binder` to pull configuration values explicitly out of the + `Environment` in a relaxed manner. It is often is used with a prefix. +* Look for `@Value` annotations that bind directly to the `Environment`. * Look for `@ConditionalOnExpression` annotations that switch features on and off in response to SpEL expressions, normally evaluated with placeholders resolved from the `Environment`. @@ -483,7 +480,7 @@ The appendix includes an <> example with a list of the most common properties supported by Spring Boot. The definitive list comes from searching the source code for `@ConfigurationProperties` and `@Value` annotations, as well as the occasional use of -`RelaxedPropertyResolver`. +`Binder`. diff --git a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc index 54109b24f0..5798b0ccd2 100644 --- a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc +++ b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc @@ -1100,15 +1100,40 @@ The following properties names can all be used: |Standard camel case syntax. |`person.first-name` -|Dashed notation, recommended for use in `.properties` and `.yml` files. +|Kebab-case, recommended for use in `.properties` and `.yml` files. |`person.first_name` |Underscore notation, alternative format for use in `.properties` and `.yml` files. -|`PERSON_FIRST_NAME` +|`PERSON_FIRSTNAME` |Upper case format. Recommended when using a system environment variables. |=== +NOTE: The `prefix` value for the annotation must be in kebab-case, ie, lowercase and separated by `-`. + +.relaxed binding rules per property source +[cols="2,4,4"] +|=== +| Property Source | Simple | List + +|Properties Files +|Camel-case, kebab-case or underscore notation +|Standard list syntax using `[ ]` or comma-separated values + +|YAML Files +|Camel-case, kebab-case or underscore notation +|Standard YAML list syntax or comma-separated values + +|Environment Variables +|Upper case format with underscore as the delimiter. `_` should not be used within a property name +|Numeric values surrounded by underscores. eg: `MY_FOO_1_BAR = my.foo[1].bar` + +|System properties +|Camel-case, kebab-case or underscore notation +|Standard list syntax using `[ ]` or comma-separated values +|=== + +TIP: We recommend that, when possible, properties are stored in lowercase kebab format. i.e. `my.property-name=foo` [[boot-features-external-config-conversion]] @@ -1671,9 +1696,8 @@ use the `defaultValue` attribute. ---- -TIP: The `RelaxedPropertyResolver` is used to access `Environment` properties. If specify -the `source` in dashed notation (`my-property-name`) all the relaxed variations will be -tried (`myPropertyName`, `MY_PROPERTY_NAME` etc). +NOTE: The `source` must be specified using kebab-case (`my.property-name`). However, properties can be added to the +`Environment` using the relaxed rules.