Introduce Spring property for the default property placeholder escape character

[sbrannen]

Overview

Spring Framework 6.2 introduced support for an escape character (by default \) for property placeholders (see #9628).

However, there is currently no way to escape the escape character (see #34315) or disable escape character support (see below).

For example, given a username property configured with the value of Jane.Smith and a DOMAIN\${username} configuration string, property placeholder replacement used to result in DOMAIN\Jane.Smith prior to 6.2. (See also: Microsoft Windows Down-Level Logon Name).

After 6.2, property placeholder replacement results in DOMAIN${username}. Similarly, an attempt to escape the escape character via DOMAIN\\${username} results in DOMAIN\${username}.

In theory, one should be able to disable use of an escape character altogether, and that is currently possible by invoking setEscapeCharacter(null) on AbstractPropertyResolver and PlaceholderConfigurerSupport (the superclass of PropertySourcesPlaceholderConfigurer).

However, in reality, there are two hurdles.

1. An invocation of setEscapeCharacter(null) on a PropertySourcesPlaceholderConfigurer applies to its internal top-level PropertySourcesPropertyResolver but not to any nested PropertySourcesPropertyResolver, which means that the null escape character cannot be effectively applied.
2. Users may not have an easy way to explicitly set the escape character to null for a PropertyResolver or PropertySourcesPlaceholderConfigurer.
   • For example, Spring Boot auto-configures a PropertySourcesPlaceholderConfigurer with the default escape character enabled.

Point #1 will be addressed by #34861.

This issue therefore aims to address point #2.

Proposal

To allow developers to easily revert to the pre-6.2 behavior without changes to code or configuration strings, we plan to introduce a property for use with SpringProperties that can globally set the default escape character that is automatically configured in AbstractPropertyResolver and PlaceholderConfigurerSupport.

Developers will still be able to configure an explicit escape character in AbstractPropertyResolver and PlaceholderConfigurerSupport if they choose to do so.

Proposed property name: spring.placeholder.escapeCharacter.default

Setting the property to a string containing more than one character should result in an exception.

Disabling the default escape character

Setting the property to an empty string will set the default escape character to null, effectively disabling the default support for escape characters.

spring.placeholder.escapeCharacter.default =

Setting a custom default escape character

Setting the property to any other character will set the default escape character to that specific character.

spring.placeholder.escapeCharacter.default = ~

Related Issues

• Support escaping prefix and separator in property placeholders [SPR-4953] #9628
• Introduce support for escaping the escape character for property placeholders #34315
• Escaped placeholders are evaluated if the PropertySource has placeholder support #34326
• PropertySourcesPlaceholderConfigurer placeholder resolution fails in several scenarios #34861