Skip to main content

9B5.Properties Binding

trydoforOriginalPracticePropertyAbout 1 min

9B5.Properties Binding

Lists common property binding in ConfigurationProperties.

Refer to Type-safe Configuration Propertiesopen in new window

9B5.1.Pojo JavaBean

  • Basic type fields, or use wrapper classes if null is need
  • Empty constructors, and good getters/setters specification
  • Setters can be omitted for the following types, which are not immutable
    • Map, new is recommended, emptyMap is available, null is not recommended
    • Collection, new is recommended, emptySet is available, null is not recommended
    • Array, new is recommended, null is not recommended
    • nested POJO, new is recommended, null is not recommended
  • null is not recommended because wings advocate NotNull and the default value
  • @ConstructorBinding is not recommended

9B5.2.Config 3rd Class

Classes that are not able or convenient to directly @ConfigurationProperties, with @Bean annotation.

@Bean
@ConfigurationProperties(prefix = "another")
public AnotherComponent anotherComponent() {
    return new AnotherComponent();
}

9B5.3.Property Key Style

Although Spring supports lax matching, for example,

  • kebab - my.main-project.person.first-name
  • camel - my.main-project.person.firstName
  • underscore - my.main-project.person.first_name
  • UPPER - MY_MAINPROJECT_PERSON_FIRSTNAME

In Wings, it is recommended to use all lowercase kebab for the config in properties. But for environment variables use all-caps UPPER.

The rules for environment variables are: ① replace ., ② remove -, ③ all-caps

  • spring.main.log-startup-info - SPRING_MAIN_LOGSTARTUPINFO
  • my.service[0].other - MY_SERVICE_0_OTHER

9B5.4.Map Key Style

Bind property my.map to the Map<String,String>, with the following key naming,

  • key1 - my.map.key1=value1
  • /key2 - my.map.[/key2]=value2
  • key3 - my.map./key3=value3
  • a.b - my.map.a.b=value4

Spring supports scalar values, including enum, java.lang.* (except for Object), and You can omit [], eg. in the a.b, and spring.mail.properties.mail.debug.

But Wings recommends

  • keys that are not easily confused can be used directly, otherwise it is recommended to use []
  • within the spring system, follow the spring style, eg. spring.mail

9B5.5.Merge or Overwrite Prop

If properties come from multiple config files, collections are completely overwritten and key-value pairs are merged by key

  • Array/List/Set - do not merge, completely overwrite the contents with appearance priority
  • Map/Pojo - merge, overwrite value by key with appearance priority

9B5.6.Duration and Period

Spring can handle java.time.Duration and Period with all lowercase units

  • @DurationUnit milliseconds by default

  • us - microseconds

  • ms - milliseconds, PT0.5S equals 500ms

  • s - seconds

  • m - minutes

  • h - hours

  • d - days

  • @PeriodUnit days by default

  • y - years

  • m - months

  • w - weeks

  • d - days

9B5.7.DataSize

Units are All Caps

  • @DataSizeUnit bytes by default
  • 'B' - bytes
  • 'KB' - kilobytes
  • 'MB' - megabytes
  • 'GB' - gigabytes
  • 'TB' - terabytes

9B5.8.Differ from @Value

  • @ConfigurationProperties - Relaxed binding, no SpEL support
  • @Value - only kebab format can use Relaxed binding, support SpEL

Important, @Value does not support type-safe complex type injection in prefix style, only single key and simple types.