Introduce Spring property for the default property placeholder escape character #34865
Assignees
Labels
in: core
Issues in core modules (aop, beans, core, context, expression)
type: enhancement
A general enhancement
Milestone
Comments
sbrannen
added
in: core
sbrannen
changed the title
sbrannen
added a commit
to sbrannen/spring-framework
that referenced
this issue
May 13, 2025
Spring Framework 6.2 introduced support for an escape character for
property placeholders (by default '\'). However, as of Spring Framework
6.2.6, there was no way to either escape the escape character or disable
escape character support.
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 but now 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.
- As of 6.2.6, an invocation of setEscapeCharacter(null) on a
PropertySourcesPlaceholderConfigurer applied to its internal
top-level PropertySourcesPropertyResolver but not to any nested
PropertySourcesPropertyResolver, which means that the `null` escape
character could not be effectively applied.
- 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.
This first issue above has recently been addressed by spring-projectsgh-34861.
This commit therefore addresses the second issue as follows.
- To allow developers to easily revert to the pre-6.2 behavior without
changes to code or configuration strings, this commit introduces a
`spring.placeholder.escapeCharacter.default` property for use with
SpringProperties which globally sets the default escape character that
is automatically configured in AbstractPropertyResolver and
PlaceholderConfigurerSupport.
- Setting the property to an empty string sets the default escape
character to `null`, effectively disabling the default support for
escape characters.
spring.placeholder.escapeCharacter.default =
- Setting the property to any other character sets the default escape
character to that specific character.
spring.placeholder.escapeCharacter.default = ~
- Setting the property to a string containing more than one character
results in an exception.
- Developers are still able to configure an explicit escape character
in AbstractPropertyResolver and PlaceholderConfigurerSupport if they
choose to do so.
- Third-party components that wish to rely on the same feature can
invoke AbstractPropertyResolver.getDefaultEscapeCharacter() to obtain
the globally configured default escape character.
See spring-projectsgh-9628
See spring-projectsgh-34315
See spring-projectsgh-34861
Closes spring-projectsgh-34865
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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
usernameproperty configured with the value ofJane.Smithand aDOMAIN\${username}configuration string, property placeholder replacement used to result inDOMAIN\Jane.Smithprior 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 viaDOMAIN\\${username}results inDOMAIN\${username}.In theory, one should be able to disable use of an escape character altogether, and that is currently possible by invoking
setEscapeCharacter(null)onAbstractPropertyResolverandPlaceholderConfigurerSupport(the superclass ofPropertySourcesPlaceholderConfigurer).However, in reality, there are two hurdles.
setEscapeCharacter(null)on aPropertySourcesPlaceholderConfigurerapplies to its internal top-levelPropertySourcesPropertyResolverbut not to any nestedPropertySourcesPropertyResolver, which means that thenullescape character cannot be effectively applied.nullfor aPropertyResolverorPropertySourcesPlaceholderConfigurer.PropertySourcesPlaceholderConfigurerwith the default escape character enabled.Point
#1will 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
SpringPropertiesthat can globally set the default escape character that is automatically configured inAbstractPropertyResolverandPlaceholderConfigurerSupport.Developers will still be able to configure an explicit escape character in
AbstractPropertyResolverandPlaceholderConfigurerSupportif they choose to do so.Proposed property name:
spring.placeholder.escapeCharacter.defaultSetting 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
PropertySourcesPlaceholderConfigurerplaceholder resolution fails in several scenarios #34861The text was updated successfully, but these errors were encountered: