Introduce fallback flag and annotation (as companion to primary)

Closes gh-26241

spring-context/src/main/java/org/springframework/context/annotation/AnnotationConfigUtils.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.
@@ -246,6 +246,9 @@ public abstract class AnnotationConfigUtils {
 		if (metadata.isAnnotated(Primary.class.getName())) {
 			abd.setPrimary(true);
 		}
+		if (metadata.isAnnotated(Fallback.class.getName())) {
+			abd.setFallback(true);
+		}
 		AnnotationAttributes dependsOn = attributesFor(metadata, DependsOn.class);
 		if (dependsOn != null) {
 			abd.setDependsOn(dependsOn.getStringArray("value"));

spring-context/src/main/java/org/springframework/context/annotation/Fallback.java

@@ -0,0 +1,44 @@
+/*
+ * 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.
+ * 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.context.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Indicates that a bean qualifies as a fallback autowire candidate.
+ * This is a companion and alternative to the {@link Primary} annotation.
+ *
+ * <p>If all beans but one among multiple matching candidates are marked
+ * as a fallback, the remaining bean will be selected.
+ *
+ * @author Juergen Hoeller
+ * @since 6.2
+ * @see Primary
+ * @see Lazy
+ * @see Bean
+ * @see org.springframework.beans.factory.config.BeanDefinition#setFallback
+ */
+@Target({ElementType.TYPE, ElementType.METHOD})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface Fallback {
+
+}

spring-context/src/main/java/org/springframework/context/annotation/Primary.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.
@@ -77,10 +77,12 @@ import java.lang.annotation.Target;
  * @author Chris Beams
  * @author Juergen Hoeller
  * @since 3.0
+ * @see Fallback
  * @see Lazy
  * @see Bean
  * @see ComponentScan
  * @see org.springframework.stereotype.Component
+ * @see org.springframework.beans.factory.config.BeanDefinition#setPrimary
  */
 @Target({ElementType.TYPE, ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)

spring-context/src/test/java/org/springframework/context/annotation/configuration/BeanMethodQualificationTests.java

@@ -30,7 +30,9 @@ import org.springframework.beans.testfixture.beans.TestBean;
 import org.springframework.context.annotation.AnnotationConfigApplicationContext;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Fallback;
 import org.springframework.context.annotation.Lazy;
+import org.springframework.context.annotation.Primary;
 import org.springframework.context.annotation.Scope;
 import org.springframework.context.annotation.ScopedProxyMode;
 import org.springframework.core.annotation.AliasFor;
@@ -80,6 +82,26 @@ class BeanMethodQualificationTests {
 		ctx.close();
 	}
 
+	@Test
+	void primary() {
+		AnnotationConfigApplicationContext ctx =
+				new AnnotationConfigApplicationContext(PrimaryConfig.class, StandardPojo.class);
+		StandardPojo pojo = ctx.getBean(StandardPojo.class);
+		assertThat(pojo.testBean.getName()).isEqualTo("interesting");
+		assertThat(pojo.testBean2.getName()).isEqualTo("boring");
+		ctx.close();
+	}
+
+	@Test
+	void fallback() {
+		AnnotationConfigApplicationContext ctx =
+				new AnnotationConfigApplicationContext(FallbackConfig.class, StandardPojo.class);
+		StandardPojo pojo = ctx.getBean(StandardPojo.class);
+		assertThat(pojo.testBean.getName()).isEqualTo("interesting");
+		assertThat(pojo.testBean2.getName()).isEqualTo("boring");
+		ctx.close();
+	}
+
 	@Test
 	void customWithLazyResolution() {
 		AnnotationConfigApplicationContext ctx =
@@ -201,6 +223,58 @@ class BeanMethodQualificationTests {
 		}
 	}
 
+	@Configuration
+	static class PrimaryConfig {
+
+		@Bean @Qualifier("interesting") @Primary
+		public static TestBean testBean1() {
+			return new TestBean("interesting");
+		}
+
+		@Bean @Qualifier("interesting")
+		public static TestBean testBean1x() {
+			return new TestBean("interesting");
+		}
+
+		@Bean @Boring @Primary
+		public TestBean testBean2(TestBean testBean1) {
+			TestBean tb = new TestBean("boring");
+			tb.setSpouse(testBean1);
+			return tb;
+		}
+
+		@Bean @Boring
+		public TestBean testBean2x() {
+			return new TestBean("boring");
+		}
+	}
+
+	@Configuration
+	static class FallbackConfig {
+
+		@Bean @Qualifier("interesting")
+		public static TestBean testBean1() {
+			return new TestBean("interesting");
+		}
+
+		@Bean @Qualifier("interesting") @Fallback
+		public static TestBean testBean1x() {
+			return new TestBean("interesting");
+		}
+
+		@Bean @Boring
+		public TestBean testBean2(TestBean testBean1) {
+			TestBean tb = new TestBean("boring");
+			tb.setSpouse(testBean1);
+			return tb;
+		}
+
+		@Bean @Boring @Fallback
+		public TestBean testBean2x() {
+			return new TestBean("boring");
+		}
+	}
+
 	@Component @Lazy
 	static class StandardPojo {