Provide support for deprecated auto-configuration classes

Support `AutoConfiguration.replacements` file that can be placed
alongside an `AutoConfiguration.imports` to replace deprecated
auto-configurations.

Closes gh-14860

Author: philwebb

spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/AutoConfigurationImportSelector.java

@@ -86,6 +86,8 @@ public class AutoConfigurationImportSelector implements DeferredImportSelector,
 
 	private static final String PROPERTY_NAME_AUTOCONFIGURE_EXCLUDE = "spring.autoconfigure.exclude";
 
+	private final Class<?> autoConfigurationAnnotation;
+
 	private ConfigurableListableBeanFactory beanFactory;
 
 	private Environment environment;
@@ -96,6 +98,17 @@ public class AutoConfigurationImportSelector implements DeferredImportSelector,
 
 	private volatile ConfigurationClassFilter configurationClassFilter;
 
+	private volatile AutoConfigurationReplacements autoConfigurationReplacements;
+
+	public AutoConfigurationImportSelector() {
+		this(null);
+	}
+
+	AutoConfigurationImportSelector(Class<?> autoConfigurationAnnotation) {
+		this.autoConfigurationAnnotation = (autoConfigurationAnnotation != null) ? autoConfigurationAnnotation
+				: AutoConfiguration.class;
+	}
+
 	@Override
 	public String[] selectImports(AnnotationMetadata annotationMetadata) {
 		if (!isEnabled(annotationMetadata)) {
@@ -179,11 +192,12 @@ protected Class<?> getAnnotationClass() {
 	 * @return a list of candidate configurations
 	 */
 	protected List<String> getCandidateConfigurations(AnnotationMetadata metadata, AnnotationAttributes attributes) {
-		ImportCandidates importCandidates = ImportCandidates.load(AutoConfiguration.class, getBeanClassLoader());
+		ImportCandidates importCandidates = ImportCandidates.load(this.autoConfigurationAnnotation,
+				getBeanClassLoader());
 		List<String> configurations = importCandidates.getCandidates();
 		Assert.notEmpty(configurations,
-				"No auto configuration classes found in "
-						+ "META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports. If you "
+				"No auto configuration classes found in " + "META-INF/spring/"
+						+ this.autoConfigurationAnnotation.getName() + ".imports. If you "
 						+ "are using a custom packaging, make sure that file is correct.");
 		return configurations;
 	}
@@ -227,7 +241,7 @@ protected Set<String> getExclusions(AnnotationMetadata metadata, AnnotationAttri
 		excluded.addAll(asList(attributes, "exclude"));
 		excluded.addAll(asList(attributes, "excludeName"));
 		excluded.addAll(getExcludeAutoConfigurationsProperty());
-		return excluded;
+		return getAutoConfigurationReplacements().replaceAll(excluded);
 	}
 
 	/**
@@ -268,6 +282,16 @@ private ConfigurationClassFilter getConfigurationClassFilter() {
 		return configurationClassFilter;
 	}
 
+	private AutoConfigurationReplacements getAutoConfigurationReplacements() {
+		AutoConfigurationReplacements autoConfigurationReplacements = this.autoConfigurationReplacements;
+		if (autoConfigurationReplacements == null) {
+			autoConfigurationReplacements = AutoConfigurationReplacements.load(this.autoConfigurationAnnotation,
+					this.beanClassLoader);
+			this.autoConfigurationReplacements = autoConfigurationReplacements;
+		}
+		return autoConfigurationReplacements;
+	}
+
 	protected final <T> List<T> removeDuplicates(List<T> list) {
 		return new ArrayList<>(new LinkedHashSet<>(list));
 	}
@@ -409,6 +433,8 @@ private static final class AutoConfigurationGroup
 
 		private AutoConfigurationMetadata autoConfigurationMetadata;
 
+		private AutoConfigurationReplacements autoConfigurationReplacements;
+
 		@Override
 		public void setBeanClassLoader(ClassLoader classLoader) {
 			this.beanClassLoader = classLoader;
@@ -430,7 +456,15 @@ public void process(AnnotationMetadata annotationMetadata, DeferredImportSelecto
 					() -> String.format("Only %s implementations are supported, got %s",
 							AutoConfigurationImportSelector.class.getSimpleName(),
 							deferredImportSelector.getClass().getName()));
-			AutoConfigurationEntry autoConfigurationEntry = ((AutoConfigurationImportSelector) deferredImportSelector)
+			AutoConfigurationImportSelector autoConfigurationImportSelector = (AutoConfigurationImportSelector) deferredImportSelector;
+			AutoConfigurationReplacements autoConfigurationReplacements = autoConfigurationImportSelector
+				.getAutoConfigurationReplacements();
+			Assert.state(
+					this.autoConfigurationReplacements == null
+							|| this.autoConfigurationReplacements.equals(autoConfigurationReplacements),
+					"Auto-configuration replacements must be the same for each call to process");
+			this.autoConfigurationReplacements = autoConfigurationReplacements;
+			AutoConfigurationEntry autoConfigurationEntry = autoConfigurationImportSelector
 				.getAutoConfigurationEntry(annotationMetadata);
 			this.autoConfigurationEntries.add(autoConfigurationEntry);
 			for (String importClassName : autoConfigurationEntry.getConfigurations()) {
@@ -452,7 +486,6 @@ public Iterable<Entry> selectImports() {
 				.flatMap(Collection::stream)
 				.collect(Collectors.toCollection(LinkedHashSet::new));
 			processedConfigurations.removeAll(allExclusions);
-
 			return sortAutoConfigurations(processedConfigurations, getAutoConfigurationMetadata()).stream()
 				.map((importClassName) -> new Entry(this.entries.get(importClassName), importClassName))
 				.toList();
@@ -467,7 +500,8 @@ private AutoConfigurationMetadata getAutoConfigurationMetadata() {
 
 		private List<String> sortAutoConfigurations(Set<String> configurations,
 				AutoConfigurationMetadata autoConfigurationMetadata) {
-			return new AutoConfigurationSorter(getMetadataReaderFactory(), autoConfigurationMetadata)
+			return new AutoConfigurationSorter(getMetadataReaderFactory(), autoConfigurationMetadata,
+					this.autoConfigurationReplacements::replace)
 				.getInPriorityOrder(configurations);
 		}
 

spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/AutoConfigurationReplacements.java

@@ -0,0 +1,133 @@
+/*
+ * Copyright 2012-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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.autoconfigure;
+
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStreamReader;
+import java.net.URL;
+import java.nio.charset.StandardCharsets;
+import java.util.Enumeration;
+import java.util.HashMap;
+import java.util.LinkedHashSet;
+import java.util.Map;
+import java.util.Properties;
+import java.util.Set;
+
+import org.springframework.boot.context.annotation.ImportCandidates;
+import org.springframework.core.io.UrlResource;
+import org.springframework.util.Assert;
+
+/**
+ * Contains auto-configuration replacements used to handle deprecated or moved
+ * auto-configurations which may still be referenced by
+ * {@link AutoConfigureBefore @AutoConfigureBefore},
+ * {@link AutoConfigureAfter @AutoConfigureAfter} or exclusions.
+ *
+ * @author Phillip Webb
+ */
+final class AutoConfigurationReplacements {
+
+	private static final String LOCATION = "META-INF/spring/%s.replacements";
+
+	private final Map<String, String> replacements;
+
+	private AutoConfigurationReplacements(Map<String, String> replacements) {
+		this.replacements = Map.copyOf(replacements);
+	}
+
+	Set<String> replaceAll(Set<String> classNames) {
+		Set<String> replaced = new LinkedHashSet<>(classNames.size());
+		for (String className : classNames) {
+			replaced.add(replace(className));
+		}
+		return replaced;
+	}
+
+	String replace(String className) {
+		return this.replacements.getOrDefault(className, className);
+	}
+
+	@Override
+	public boolean equals(Object obj) {
+		if (this == obj) {
+			return true;
+		}
+		if (obj == null || getClass() != obj.getClass()) {
+			return false;
+		}
+		return this.replacements.equals(((AutoConfigurationReplacements) obj).replacements);
+	}
+
+	@Override
+	public int hashCode() {
+		return this.replacements.hashCode();
+	}
+
+	/**
+	 * Loads the relocations from the classpath. Relactions are stored in files named
+	 * {@code META-INF/spring/full-qualified-annotation-name.replacements} on the
+	 * classpath. The file is loaded using {@link Properties#load(java.io.InputStream)}
+	 * with each entry containing an auto-configuration class name as the key and the
+	 * replacement class name as the value.
+	 * @param annotation annotation to load
+	 * @param classLoader class loader to use for loading
+	 * @return list of names of annotated classes
+	 */
+	static AutoConfigurationReplacements load(Class<?> annotation, ClassLoader classLoader) {
+		Assert.notNull(annotation, "'annotation' must not be null");
+		ClassLoader classLoaderToUse = decideClassloader(classLoader);
+		String location = String.format(LOCATION, annotation.getName());
+		Enumeration<URL> urls = findUrlsInClasspath(classLoaderToUse, location);
+		Map<String, String> replacements = new HashMap<>();
+		while (urls.hasMoreElements()) {
+			URL url = urls.nextElement();
+			replacements.putAll(readReplacements(url));
+		}
+		return new AutoConfigurationReplacements(replacements);
+	}
+
+	private static ClassLoader decideClassloader(ClassLoader classLoader) {
+		if (classLoader == null) {
+			return ImportCandidates.class.getClassLoader();
+		}
+		return classLoader;
+	}
+
+	private static Enumeration<URL> findUrlsInClasspath(ClassLoader classLoader, String location) {
+		try {
+			return classLoader.getResources(location);
+		}
+		catch (IOException ex) {
+			throw new IllegalArgumentException("Failed to load configurations from location [" + location + "]", ex);
+		}
+	}
+
+	@SuppressWarnings({ "unchecked", "rawtypes" })
+	private static Map<String, String> readReplacements(URL url) {
+		try (BufferedReader reader = new BufferedReader(
+				new InputStreamReader(new UrlResource(url).getInputStream(), StandardCharsets.UTF_8))) {
+			Properties properties = new Properties();
+			properties.load(reader);
+			return (Map) properties;
+		}
+		catch (IOException ex) {
+			throw new IllegalArgumentException("Unable to load replacements from location [" + url + "]", ex);
+		}
+	}
+
+}

spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/AutoConfigurationSorter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2023 the original author or authors.
+ * Copyright 2012-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.
@@ -17,6 +17,7 @@
 package org.springframework.boot.autoconfigure;
 
 import java.io.IOException;
+import java.lang.annotation.Annotation;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Collections;
@@ -27,6 +28,7 @@
 import java.util.Map;
 import java.util.Set;
 import java.util.TreeSet;
+import java.util.function.UnaryOperator;
 
 import org.springframework.core.type.AnnotationMetadata;
 import org.springframework.core.type.classreading.MetadataReader;
@@ -47,11 +49,14 @@ class AutoConfigurationSorter {
 
 	private final AutoConfigurationMetadata autoConfigurationMetadata;
 
+	private final UnaryOperator<String> replacementMapper;
+
 	AutoConfigurationSorter(MetadataReaderFactory metadataReaderFactory,
-			AutoConfigurationMetadata autoConfigurationMetadata) {
+			AutoConfigurationMetadata autoConfigurationMetadata, UnaryOperator<String> replacementMapper) {
 		Assert.notNull(metadataReaderFactory, "MetadataReaderFactory must not be null");
 		this.metadataReaderFactory = metadataReaderFactory;
 		this.autoConfigurationMetadata = autoConfigurationMetadata;
+		this.replacementMapper = replacementMapper;
 	}
 
 	List<String> getInPriorityOrder(Collection<String> classNames) {
@@ -108,7 +113,7 @@ private void checkForCycles(Set<String> processing, String current, String after
 				() -> "AutoConfigure cycle detected between " + current + " and " + after);
 	}
 
-	private static class AutoConfigurationClasses {
+	private class AutoConfigurationClasses {
 
 		private final Map<String, AutoConfigurationClass> classes = new LinkedHashMap<>();
 
@@ -157,7 +162,7 @@ Set<String> getClassesRequestedAfter(String className) {
 
 	}
 
-	private static class AutoConfigurationClass {
+	private class AutoConfigurationClass {
 
 		private final String className;
 
@@ -192,20 +197,36 @@ boolean isAvailable() {
 
 		Set<String> getBefore() {
 			if (this.before == null) {
-				this.before = (wasProcessed() ? this.autoConfigurationMetadata.getSet(this.className,
-						"AutoConfigureBefore", Collections.emptySet()) : getAnnotationValue(AutoConfigureBefore.class));
+				this.before = getClassNames("AutoConfigureBefore", AutoConfigureBefore.class);
 			}
 			return this.before;
 		}
 
 		Set<String> getAfter() {
 			if (this.after == null) {
-				this.after = (wasProcessed() ? this.autoConfigurationMetadata.getSet(this.className,
-						"AutoConfigureAfter", Collections.emptySet()) : getAnnotationValue(AutoConfigureAfter.class));
+				this.after = getClassNames("AutoConfigureAfter", AutoConfigureAfter.class);
 			}
 			return this.after;
 		}
 
+		private Set<String> getClassNames(String metadataKey, Class<? extends Annotation> annotation) {
+			Set<String> annotationValue = wasProcessed()
+					? this.autoConfigurationMetadata.getSet(this.className, metadataKey, Collections.emptySet())
+					: getAnnotationValue(annotation);
+			return applyReplacements(annotationValue);
+		}
+
+		private Set<String> applyReplacements(Set<String> values) {
+			if (AutoConfigurationSorter.this.replacementMapper == null) {
+				return values;
+			}
+			Set<String> replaced = new LinkedHashSet<>(values);
+			for (String value : values) {
+				replaced.add(AutoConfigurationSorter.this.replacementMapper.apply(value));
+			}
+			return replaced;
+		}
+
 		private int getOrder() {
 			if (wasProcessed()) {
 				return this.autoConfigurationMetadata.getInteger(this.className, "AutoConfigureOrder",