Use new implementation in PropertyPlaceholderHelper

This commit removes the previous implementation in favor of the new
PlaceholderParser. The only noticeable side effect is that the exception
is no longer an IllegalArgumentException, but rather the dedicated
PlaceholderResolutionException.

See spring-projectsgh-9628

Author: snicoll

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.

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.

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);
 		}
 

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 ?

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

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}\"");
 	}
 

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

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);

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) {

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

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());