Introduce Spring property for default escape character for placeholders

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 gh-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 gh-9628
See gh-34315
See gh-34861
Closes gh-34865

Author: sbrannen

framework-docs/modules/ROOT/pages/appendix.adoc

@@ -103,6 +103,14 @@ for details.
 {spring-framework-api}++/objenesis/SpringObjenesis.html#IGNORE_OBJENESIS_PROPERTY_NAME++[`SpringObjenesis`]
 for details.
 
+| `spring.placeholder.escapeCharacter.default`
+| The default escape character for property placeholder support. If not set, `'\'` will
+be used. Can be set to a custom escape character or an empty string to disable support
+for an escape character. The default escape character be explicitly overridden in
+`PropertySourcesPlaceholderConfigurer` and subclasses of `AbstractPropertyResolver`. See
+{spring-framework-api}++/core/env/AbstractPropertyResolver.html#DEFAULT_PLACEHOLDER_ESCAPE_CHARACTER_PROPERTY_NAME++[`AbstractPropertyResolver`]
+for details.
+
 | `spring.test.aot.processing.failOnError`
 | A boolean flag that controls whether errors encountered during AOT processing in the
 _Spring TestContext Framework_ should result in an exception that fails the overall process.

framework-docs/modules/ROOT/pages/core/beans/annotation-config/value-annotations.adoc

@@ -101,8 +101,11 @@ NOTE: When configuring a `PropertySourcesPlaceholderConfigurer` using JavaConfig
 
 Using the above configuration ensures Spring initialization failure if any `${}`
 placeholder could not be resolved. It is also possible to use methods like
-`setPlaceholderPrefix`, `setPlaceholderSuffix`, `setValueSeparator`, or
-`setEscapeCharacter` to customize placeholders.
+`setPlaceholderPrefix()`, `setPlaceholderSuffix()`, `setValueSeparator()`, or
+`setEscapeCharacter()` to customize the placeholder syntax. In addition, the default
+escape character can be changed or disabled globally by setting the
+`spring.placeholder.escapeCharacter.default` property via a JVM system property (or via
+the xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism).
 
 NOTE: Spring Boot configures by default a `PropertySourcesPlaceholderConfigurer` bean that
 will get properties from `application.properties` and `application.yml` files.

framework-docs/modules/ROOT/pages/core/beans/factory-extension.adoc

@@ -314,7 +314,7 @@ Thus, marking it for lazy initialization will be ignored, and the
 
 
 [[beans-factory-placeholderconfigurer]]
-=== Example: The Class Name Substitution `PropertySourcesPlaceholderConfigurer`
+=== Example: Property Placeholder Substitution with `PropertySourcesPlaceholderConfigurer`
 
 You can use the `PropertySourcesPlaceholderConfigurer` to externalize property values
 from a bean definition in a separate file by using the standard Java `Properties` format.
@@ -341,7 +341,7 @@ with placeholder values is defined:
 
 The example shows properties configured from an external `Properties` file. At runtime,
 a `PropertySourcesPlaceholderConfigurer` is applied to the metadata that replaces some
-properties of the DataSource. The values to replace are specified as placeholders of the
+properties of the `DataSource`. The values to replace are specified as placeholders of the
 form pass:q[`${property-name}`], which follows the Ant, log4j, and JSP EL style.
 
 The actual values come from another file in the standard Java `Properties` format:
@@ -355,10 +355,13 @@ jdbc.password=root
 ----
 
 Therefore, the `${jdbc.username}` string is replaced at runtime with the value, 'sa', and
-the same applies for other placeholder values that match keys in the properties file.
-The `PropertySourcesPlaceholderConfigurer` checks for placeholders in most properties and
-attributes of a bean definition. Furthermore, you can customize the placeholder prefix, suffix,
-default value separator, and escape character.
+the same applies for other placeholder values that match keys in the properties file. The
+`PropertySourcesPlaceholderConfigurer` checks for placeholders in most properties and
+attributes of a bean definition. Furthermore, you can customize the placeholder prefix,
+suffix, default value separator, and escape character. In addition, the default escape
+character can be changed or disabled globally by setting the
+`spring.placeholder.escapeCharacter.default` property via a JVM system property (or via
+the xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism).
 
 With the `context` namespace, you can configure property placeholders
 with a dedicated configuration element. You can provide one or more locations as a

framework-docs/modules/ROOT/pages/languages/kotlin/spring-projects-in.adoc

@@ -190,7 +190,7 @@ NOTE: If you use Spring Boot, you should probably use
 instead of `@Value` annotations.
 
 As an alternative, you can customize the property placeholder prefix by declaring the
-following configuration bean:
+following `PropertySourcesPlaceholderConfigurer` bean:
 
 [source,kotlin,indent=0]
 ----
@@ -200,8 +200,10 @@ following configuration bean:
 	}
 ----
 
-You can customize existing code (such as Spring Boot actuators or `@LocalServerPort`)
-that uses the `${...}` syntax, with configuration beans, as the following example shows:
+You can support components (such as Spring Boot actuators or `@LocalServerPort`) that use
+the standard `${...}` syntax alongside components that use the custom `%{...}` syntax by
+declaring multiple `PropertySourcesPlaceholderConfigurer` beans, as the following example
+shows:
 
 [source,kotlin,indent=0]
 ----
@@ -215,6 +217,9 @@ that uses the `${...}` syntax, with configuration beans, as the following exampl
 	fun defaultPropertyConfigurer() = PropertySourcesPlaceholderConfigurer()
 ----
 
+In addition, the default escape character can be changed or disabled globally by setting
+the `spring.placeholder.escapeCharacter.default` property via a JVM system property (or
+via the xref:appendix.adoc#appendix-spring-properties[`SpringProperties`] mechanism).
 
 
 [[checked-exceptions]]

spring-beans/src/main/java/org/springframework/beans/factory/config/PlaceholderConfigurerSupport.java

@@ -20,6 +20,7 @@
 import org.springframework.beans.factory.BeanFactory;
 import org.springframework.beans.factory.BeanFactoryAware;
 import org.springframework.beans.factory.BeanNameAware;
+import org.springframework.core.env.AbstractPropertyResolver;
 import org.springframework.lang.Nullable;
 import org.springframework.util.StringValueResolver;
 import org.springframework.util.SystemPropertyUtils;
@@ -85,6 +86,7 @@
  *
  * @author Chris Beams
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 3.1
  * @see PropertyPlaceholderConfigurer
  * @see org.springframework.context.support.PropertySourcesPlaceholderConfigurer
@@ -101,7 +103,11 @@ public abstract class PlaceholderConfigurerSupport extends PropertyResourceConfi
 	/** Default value separator: {@value}. */
 	public static final String DEFAULT_VALUE_SEPARATOR = SystemPropertyUtils.VALUE_SEPARATOR;
 
-	/** Default escape character: {@code '\'}. */
+	/**
+	 * Default escape character: {@code '\'}.
+	 * @since 6.2
+	 * @see AbstractPropertyResolver#getDefaultEscapeCharacter()
+	 */
 	public static final Character DEFAULT_ESCAPE_CHARACTER = SystemPropertyUtils.ESCAPE_CHARACTER;
 
 
@@ -115,9 +121,11 @@ public abstract class PlaceholderConfigurerSupport extends PropertyResourceConfi
 	@Nullable
 	protected String valueSeparator = DEFAULT_VALUE_SEPARATOR;
 
-	/** Defaults to {@link #DEFAULT_ESCAPE_CHARACTER}. */
+	/**
+	 * The default is determined by {@link AbstractPropertyResolver#getDefaultEscapeCharacter()}.
+	 */
 	@Nullable
-	protected Character escapeCharacter = DEFAULT_ESCAPE_CHARACTER;
+	protected Character escapeCharacter = AbstractPropertyResolver.getDefaultEscapeCharacter();
 
 	protected boolean trimValues = false;
 
@@ -164,6 +172,7 @@ public void setValueSeparator(@Nullable String valueSeparator) {
 	 * {@linkplain #setPlaceholderPrefix(String) placeholder prefix} and the
 	 * {@linkplain #setValueSeparator(String) value separator}, or {@code null}
 	 * if no escaping should take place.
+	 * <p>The default is determined by {@link AbstractPropertyResolver#getDefaultEscapeCharacter()}.
 	 * @since 6.2
 	 */
 	public void setEscapeCharacter(@Nullable Character escapeCharacter) {

spring-context/src/test/java/org/springframework/context/support/PropertySourcesPlaceholderConfigurerTests.java

@@ -16,12 +16,15 @@
 
 package org.springframework.context.support;
 
+import java.lang.reflect.Field;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
 import java.util.Optional;
 import java.util.Properties;
 
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
@@ -37,7 +40,9 @@
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.context.annotation.Scope;
+import org.springframework.core.SpringProperties;
 import org.springframework.core.convert.support.DefaultConversionService;
+import org.springframework.core.env.AbstractPropertyResolver;
 import org.springframework.core.env.EnumerablePropertySource;
 import org.springframework.core.env.MutablePropertySources;
 import org.springframework.core.env.PropertySource;
@@ -47,12 +52,15 @@
 import org.springframework.core.testfixture.env.MockPropertySource;
 import org.springframework.mock.env.MockEnvironment;
 import org.springframework.util.PlaceholderResolutionException;
+import org.springframework.util.ReflectionUtils;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
+import static org.assertj.core.api.Assertions.assertThatIllegalArgumentException;
 import static org.assertj.core.api.Assertions.assertThatIllegalStateException;
 import static org.springframework.beans.factory.support.BeanDefinitionBuilder.genericBeanDefinition;
 import static org.springframework.beans.factory.support.BeanDefinitionBuilder.rootBeanDefinition;
+import static org.springframework.core.env.AbstractPropertyResolver.DEFAULT_PLACEHOLDER_ESCAPE_CHARACTER_PROPERTY_NAME;
 
 /**
  * Tests for {@link PropertySourcesPlaceholderConfigurer}.
@@ -667,6 +675,108 @@ private static DefaultListableBeanFactory createBeanFactory() {
 	}
 
 
+	/**
+	 * Tests that globally set the default escape character (or disable it) and
+	 * rely on nested placeholder resolution.
+	 */
+	@Nested
+	class GlobalDefaultEscapeCharacterTests {
+
+		private static final Field defaultEscapeCharacterField =
+				ReflectionUtils.findField(AbstractPropertyResolver.class, "defaultEscapeCharacter");
+
+		static {
+			ReflectionUtils.makeAccessible(defaultEscapeCharacterField);
+		}
+
+
+		@BeforeEach
+		void resetStateBeforeEachTest() {
+			resetState();
+		}
+
+		@AfterAll
+		static void resetState() {
+			ReflectionUtils.setField(defaultEscapeCharacterField, null, Character.MIN_VALUE);
+			setSpringProperty(null);
+		}
+
+
+		@Test  // gh-34865
+		void defaultEscapeCharacterSetToXyz() {
+			setSpringProperty("XYZ");
+
+			assertThatIllegalArgumentException()
+					.isThrownBy(PropertySourcesPlaceholderConfigurer::new)
+					.withMessage("Value [XYZ] for property [%s] must be a single character or an empty string",
+							DEFAULT_PLACEHOLDER_ESCAPE_CHARACTER_PROPERTY_NAME);
+		}
+
+		@Test  // gh-34865
+		void defaultEscapeCharacterDisabled() {
+			setSpringProperty("");
+
+			MockEnvironment env = new MockEnvironment()
+					.withProperty("user.home", "admin")
+					.withProperty("my.property", "\\DOMAIN\\${user.home}");
+
+			DefaultListableBeanFactory bf = createBeanFactory();
+			PropertySourcesPlaceholderConfigurer ppc = new PropertySourcesPlaceholderConfigurer();
+			ppc.setEnvironment(env);
+			ppc.postProcessBeanFactory(bf);
+
+			assertThat(bf.getBean(TestBean.class).getName()).isEqualTo("\\DOMAIN\\admin");
+		}
+
+		@Test  // gh-34865
+		void defaultEscapeCharacterSetToBackslash() {
+			setSpringProperty("\\");
+
+			MockEnvironment env = new MockEnvironment()
+					.withProperty("user.home", "admin")
+					.withProperty("my.property", "\\DOMAIN\\${user.home}");
+
+			DefaultListableBeanFactory bf = createBeanFactory();
+			PropertySourcesPlaceholderConfigurer ppc = new PropertySourcesPlaceholderConfigurer();
+			ppc.setEnvironment(env);
+			ppc.postProcessBeanFactory(bf);
+
+			// \DOMAIN\${user.home} resolves to \DOMAIN${user.home} instead of \DOMAIN\admin
+			assertThat(bf.getBean(TestBean.class).getName()).isEqualTo("\\DOMAIN${user.home}");
+		}
+
+		@Test  // gh-34865
+		void defaultEscapeCharacterSetToTilde() {
+			setSpringProperty("~");
+
+			MockEnvironment env = new MockEnvironment()
+					.withProperty("user.home", "admin\\~${nested}")
+					.withProperty("my.property", "DOMAIN\\${user.home}\\~${enigma}");
+
+			DefaultListableBeanFactory bf = createBeanFactory();
+			PropertySourcesPlaceholderConfigurer ppc = new PropertySourcesPlaceholderConfigurer();
+			ppc.setEnvironment(env);
+			ppc.postProcessBeanFactory(bf);
+
+			assertThat(bf.getBean(TestBean.class).getName()).isEqualTo("DOMAIN\\admin\\${nested}\\${enigma}");
+		}
+
+		private static void setSpringProperty(String value) {
+			SpringProperties.setProperty(DEFAULT_PLACEHOLDER_ESCAPE_CHARACTER_PROPERTY_NAME, value);
+		}
+
+		private static DefaultListableBeanFactory createBeanFactory() {
+			BeanDefinition beanDefinition = genericBeanDefinition(TestBean.class)
+					.addPropertyValue("name", "${my.property}")
+					.getBeanDefinition();
+			DefaultListableBeanFactory bf = new DefaultListableBeanFactory();
+			bf.registerBeanDefinition("testBean",beanDefinition);
+			return bf;
+		}
+
+	}
+
+
 	private static class OptionalTestBean {
 
 		private Optional<String> name;