Add support for escaping prefix and separator in property placeholders

Closes gh-9628
Closes gh-26268

Author: snicoll

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

@@ -101,8 +101,8 @@ 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`, or `setValueSeparator` to customize
-placeholders.
+`setPlaceholderPrefix`, `setPlaceholderSuffix`, `setValueSeparator`, or
+`setEscapeCharacter` to customize placeholders.
 
 NOTE: Spring Boot configures by default a `PropertySourcesPlaceholderConfigurer` bean that
 will get properties from `application.properties` and `application.yml` files.

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -100,6 +100,8 @@ public abstract class PlaceholderConfigurerSupport extends PropertyResourceConfi
 	/** Default value separator: {@value}. */
 	public static final String DEFAULT_VALUE_SEPARATOR = ":";
 
+	/** Default escape character: {@value}. */
+	public static final Character DEFAULT_ESCAPE_CHARACTER = '\\';
 
 	/** Defaults to {@value #DEFAULT_PLACEHOLDER_PREFIX}. */
 	protected String placeholderPrefix = DEFAULT_PLACEHOLDER_PREFIX;
@@ -111,6 +113,10 @@ public abstract class PlaceholderConfigurerSupport extends PropertyResourceConfi
 	@Nullable
 	protected String valueSeparator = DEFAULT_VALUE_SEPARATOR;
 
+	/** Defaults to {@value #DEFAULT_ESCAPE_CHARACTER}. */
+	@Nullable
+	protected Character escapeCharacter = DEFAULT_ESCAPE_CHARACTER;
+
 	protected boolean trimValues = false;
 
 	@Nullable
@@ -151,6 +157,17 @@ public void setValueSeparator(@Nullable String valueSeparator) {
 		this.valueSeparator = valueSeparator;
 	}
 
+	/**
+	 * Specify the escape character to use to ignore placeholder prefix
+	 * or value separator, or {@code null} if no escaping should take
+	 * place.
+	 * <p>Default is {@value #DEFAULT_ESCAPE_CHARACTER}.
+	 * @since 6.2
+	 */
+	public void setEscapeCharacter(@Nullable Character escsEscapeCharacter) {
+		this.escapeCharacter = escsEscapeCharacter;
+	}
+
 	/**
 	 * Specify whether to trim resolved values before applying them,
 	 * removing superfluous whitespace from the beginning and end.

Diff for: spring-beans/src/main/java/org/springframework/beans/factory/config/PropertyPlaceholderConfigurer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -234,7 +234,8 @@ private class PlaceholderResolvingStringValueResolver implements StringValueReso
 
 		public PlaceholderResolvingStringValueResolver(Properties props) {
 			this.helper = new PropertyPlaceholderHelper(
-					placeholderPrefix, placeholderSuffix, valueSeparator, ignoreUnresolvablePlaceholders);
+					placeholderPrefix, placeholderSuffix, valueSeparator,
+					ignoreUnresolvablePlaceholders, escapeCharacter);
 			this.resolver = new PropertyPlaceholderConfigurerResolver(props);
 		}
 

Diff for: spring-context/src/main/java/org/springframework/context/support/PropertySourcesPlaceholderConfigurer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -193,6 +193,7 @@ protected void processProperties(ConfigurableListableBeanFactory beanFactoryToPr
 		propertyResolver.setPlaceholderPrefix(this.placeholderPrefix);
 		propertyResolver.setPlaceholderSuffix(this.placeholderSuffix);
 		propertyResolver.setValueSeparator(this.valueSeparator);
+		propertyResolver.setEscapeCharacter(this.escapeCharacter);
 
 		StringValueResolver valueResolver = strVal -> {
 			String resolved = (this.ignoreUnresolvablePlaceholders ?

Diff for: spring-context/src/test/java/org/springframework/context/annotation/PropertySourceAnnotationTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -40,6 +40,7 @@
 import org.springframework.core.io.support.EncodedResource;
 import org.springframework.core.io.support.PropertiesLoaderUtils;
 import org.springframework.core.io.support.PropertySourceFactory;
+import org.springframework.util.PlaceholderResolutionException;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
@@ -132,7 +133,7 @@ void withCustomFactoryAsMeta() {
 	void withUnresolvablePlaceholder() {
 		assertThatExceptionOfType(BeanDefinitionStoreException.class)
 				.isThrownBy(() -> new AnnotationConfigApplicationContext(ConfigWithUnresolvablePlaceholder.class))
-				.withCauseInstanceOf(IllegalArgumentException.class);
+				.withCauseInstanceOf(PlaceholderResolutionException.class);
 	}
 
 	@Test

Diff for: spring-context/src/test/java/org/springframework/context/config/ContextNamespaceHandlerTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -28,6 +28,7 @@
 import org.springframework.context.support.GenericXmlApplicationContext;
 import org.springframework.core.io.ClassPathResource;
 import org.springframework.mock.env.MockEnvironment;
+import org.springframework.util.PlaceholderResolutionException;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
@@ -136,7 +137,7 @@ void propertyPlaceholderLocationWithSystemPropertyMissing() {
 		assertThatExceptionOfType(FatalBeanException.class).isThrownBy(() ->
 				new ClassPathXmlApplicationContext("contextNamespaceHandlerTests-location-placeholder.xml", getClass()))
 			.havingRootCause()
-			.isInstanceOf(IllegalArgumentException.class)
+			.isInstanceOf(PlaceholderResolutionException.class)
 			.withMessage("Could not resolve placeholder 'foo' in value \"${foo}\"");
 	}
 

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

@@ -37,6 +37,7 @@
 import org.springframework.core.io.Resource;
 import org.springframework.core.testfixture.env.MockPropertySource;
 import org.springframework.mock.env.MockEnvironment;
+import org.springframework.util.PlaceholderResolutionException;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
@@ -170,7 +171,7 @@ void ignoreUnresolvablePlaceholders_falseIsDefault() {
 		assertThatExceptionOfType(BeanDefinitionStoreException.class)
 			.isThrownBy(() -> ppc.postProcessBeanFactory(bf))
 			.havingCause()
-				.isExactlyInstanceOf(IllegalArgumentException.class)
+				.isExactlyInstanceOf(PlaceholderResolutionException.class)
 				.withMessage("Could not resolve placeholder 'my.name' in value \"${my.name}\"");
 	}
 
@@ -201,8 +202,8 @@ public void ignoreUnresolvablePlaceholdersInAtValueAnnotation__falseIsDefault()
 		assertThatExceptionOfType(BeanCreationException.class)
 			.isThrownBy(context::refresh)
 			.havingCause()
-				.isExactlyInstanceOf(IllegalArgumentException.class)
-				.withMessage("Could not resolve placeholder 'enigma' in value \"${enigma}\"");
+				.isExactlyInstanceOf(PlaceholderResolutionException.class)
+				.withMessage("Could not resolve placeholder 'enigma' in value \"${enigma}\" <-- \"${my.key}\"");
 	}
 
 	@Test

Diff for: spring-core/spring-core.gradle

@@ -102,6 +102,7 @@ dependencies {
 	testImplementation("jakarta.xml.bind:jakarta.xml.bind-api")
 	testImplementation("org.jetbrains.kotlinx:kotlinx-serialization-json")
 	testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-reactor")
+	testImplementation("org.mockito:mockito-core")
 	testImplementation("org.skyscreamer:jsonassert")
 	testImplementation("org.xmlunit:xmlunit-assertj")
 	testImplementation("org.xmlunit:xmlunit-matchers")

Diff for: spring-core/src/main/java/org/springframework/core/env/AbstractEnvironment.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -521,6 +521,11 @@ public void setValueSeparator(@Nullable String valueSeparator) {
 		this.propertyResolver.setValueSeparator(valueSeparator);
 	}
 
+	@Override
+	public void setEscapeCharacter(@Nullable Character escapeCharacter) {
+		this.propertyResolver.setEscapeCharacter(escapeCharacter);
+	}
+
 	@Override
 	public void setIgnoreUnresolvableNestedPlaceholders(boolean ignoreUnresolvableNestedPlaceholders) {
 		this.propertyResolver.setIgnoreUnresolvableNestedPlaceholders(ignoreUnresolvableNestedPlaceholders);

Diff for: spring-core/src/main/java/org/springframework/core/env/AbstractPropertyResolver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -61,6 +61,9 @@ public abstract class AbstractPropertyResolver implements ConfigurablePropertyRe
 	@Nullable
 	private String valueSeparator = SystemPropertyUtils.VALUE_SEPARATOR;
 
+	@Nullable
+	private Character escapeCharacter = SystemPropertyUtils.ESCAPE_CHARACTER;
+
 	private final Set<String> requiredProperties = new LinkedHashSet<>();
 
 
@@ -121,6 +124,19 @@ public void setValueSeparator(@Nullable String valueSeparator) {
 		this.valueSeparator = valueSeparator;
 	}
 
+	/**
+	 * Specify the escape character to use to ignore placeholder prefix
+	 * or value separator, or {@code null} if no escaping should take
+	 * place.
+	 * <p>The default is "\".
+	 * @since 6.2
+	 * @see org.springframework.util.SystemPropertyUtils#ESCAPE_CHARACTER
+	 */
+	@Override
+	public void setEscapeCharacter(@Nullable Character escapeCharacter) {
+		this.escapeCharacter = escapeCharacter;
+	}
+
 	/**
 	 * Set whether to throw an exception when encountering an unresolvable placeholder
 	 * nested within the value of a given property. A {@code false} value indicates strict
@@ -232,7 +248,7 @@ protected String resolveNestedPlaceholders(String value) {
 
 	private PropertyPlaceholderHelper createPlaceholderHelper(boolean ignoreUnresolvablePlaceholders) {
 		return new PropertyPlaceholderHelper(this.placeholderPrefix, this.placeholderSuffix,
-				this.valueSeparator, ignoreUnresolvablePlaceholders);
+				this.valueSeparator, ignoreUnresolvablePlaceholders, this.escapeCharacter);
 	}
 
 	private String doResolvePlaceholders(String text, PropertyPlaceholderHelper helper) {

Diff for: spring-core/src/main/java/org/springframework/core/env/ConfigurablePropertyResolver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -74,6 +74,14 @@ public interface ConfigurablePropertyResolver extends PropertyResolver {
 	 */
 	void setValueSeparator(@Nullable String valueSeparator);
 
+	/**
+	 * Specify the escape character to use to ignore placeholder prefix
+	 * or value separator, or {@code null} if no escaping should take
+	 * place.
+	 * @since 6.2
+	 */
+	void setEscapeCharacter(@Nullable Character escapeCharacter);
+
 	/**
 	 * Set whether to throw an exception when encountering an unresolvable placeholder
 	 * nested within the value of a given property. A {@code false} value indicates strict

Diff for: spring-core/src/main/java/org/springframework/core/io/support/PropertySourceProcessor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -36,6 +36,7 @@
 import org.springframework.core.io.ResourceLoader;
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
+import org.springframework.util.PlaceholderResolutionException;
 import org.springframework.util.ReflectionUtils;
 
 /**
@@ -93,8 +94,8 @@ public void processPropertySource(PropertySourceDescriptor descriptor) throws IO
 				}
 			}
 			catch (RuntimeException | IOException ex) {
-				// Placeholders not resolvable (IllegalArgumentException) or resource not found when trying to open it
-				if (ignoreResourceNotFound && (ex instanceof IllegalArgumentException || isIgnorableException(ex) ||
+				// Placeholders not resolvable or resource not found when trying to open it
+				if (ignoreResourceNotFound && (ex instanceof PlaceholderResolutionException || isIgnorableException(ex) ||
 						isIgnorableException(ex.getCause()))) {
 					if (logger.isInfoEnabled()) {
 						logger.info("Properties location [" + location + "] not resolvable: " + ex.getMessage());