Introduce defaultCandidate flag (for plain type vs. qualified match)

Closes gh-26528

spring-context/src/main/java/org/springframework/context/annotation/Bean.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.
@@ -239,13 +239,27 @@ public @interface Bean {
 	String[] name() default {};
 
 	/**
-	 * Is this bean a candidate for getting autowired into some other bean?
+	 * Is this bean a candidate for getting autowired into some other bean at all?
 	 * <p>Default is {@code true}; set this to {@code false} for internal delegates
 	 * that are not meant to get in the way of beans of the same type in other places.
 	 * @since 5.1
+	 * @see #defaultCandidate()
 	 */
 	boolean autowireCandidate() default true;
 
+	/**
+	 * Is this bean a candidate for getting autowired into some other bean based on
+	 * the plain type, without any further indications such as a qualifier match?
+	 * <p>Default is {@code true}; set this to {@code false} for restricted delegates
+	 * that are supposed to be injectable in certain areas but are not meant to get
+	 * in the way of beans of the same type in other places.
+	 * <p>This is a variation of {@link #autowireCandidate()} which does not disable
+	 * injection in general, just enforces an additional indication such as a qualifier.
+	 * @since 6.2
+	 * @see #autowireCandidate()
+	 */
+	boolean defaultCandidate() default true;
+
 	/**
 	 * The optional name of a method to call on the bean instance during initialization.
 	 * Not commonly used, given that the method may be called programmatically directly

spring-context/src/main/java/org/springframework/context/annotation/ConfigurationClassBeanDefinitionReader.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.
@@ -241,6 +241,11 @@ class ConfigurationClassBeanDefinitionReader {
 			beanDef.setAutowireCandidate(false);
 		}
 
+		boolean defaultCandidate = bean.getBoolean("defaultCandidate");
+		if (!defaultCandidate) {
+			beanDef.setDefaultCandidate(false);
+		}
+
 		String initMethodName = bean.getString("initMethod");
 		if (StringUtils.hasText(initMethodName)) {
 			beanDef.setInitMethodName(initMethodName);

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2022 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.
@@ -89,6 +89,7 @@ class BeanMethodQualificationTests {
 		assertThat(BeanFactoryAnnotationUtils.isQualifierMatch(value -> value.equals("boring"),
 		"testBean2", ctx.getDefaultListableBeanFactory())).isTrue();
 		CustomPojo pojo = ctx.getBean(CustomPojo.class);
+		assertThat(pojo.plainBean).isNull();
 		assertThat(pojo.testBean.getName()).isEqualTo("interesting");
 		TestBean testBean2 = BeanFactoryAnnotationUtils.qualifiedBeanOfType(
 				ctx.getDefaultListableBeanFactory(), TestBean.class, "boring");
@@ -132,7 +133,9 @@ class BeanMethodQualificationTests {
 				new AnnotationConfigApplicationContext(CustomConfigWithAttributeOverride.class, CustomPojo.class);
 		assertThat(ctx.getBeanFactory().containsSingleton("testBeanX")).isFalse();
 		CustomPojo pojo = ctx.getBean(CustomPojo.class);
+		assertThat(pojo.plainBean).isNull();
 		assertThat(pojo.testBean.getName()).isEqualTo("interesting");
+		assertThat(pojo.nestedTestBean).isNull();
 		ctx.close();
 	}
 
@@ -219,7 +222,7 @@ class BeanMethodQualificationTests {
 			return new TestBean("interesting");
 		}
 
-		@Bean @Qualifier("boring") @Lazy
+		@Bean(defaultCandidate=false) @Qualifier("boring") @Lazy
 		public TestBean testBean2(@Lazy TestBean testBean1) {
 			TestBean tb = new TestBean("boring");
 			tb.setSpouse(testBean1);
@@ -235,7 +238,7 @@ class BeanMethodQualificationTests {
 			return new TestBean("interesting");
 		}
 
-		@Bean @Qualifier("boring")
+		@Bean(defaultCandidate=false) @Qualifier("boring")
 		public TestBean testBean2(@Lazy TestBean testBean1) {
 			TestBean tb = new TestBean("boring");
 			tb.setSpouse(testBean1);
@@ -246,17 +249,19 @@ class BeanMethodQualificationTests {
 	@InterestingPojo
 	static class CustomPojo {
 
+		@Autowired(required=false) TestBean plainBean;
+
 		@InterestingNeed TestBean testBean;
 
 		@InterestingNeedWithRequiredOverride(required=false) NestedTestBean nestedTestBean;
 	}
 
-	@Bean @Lazy @Qualifier("interesting")
+	@Bean(defaultCandidate=false) @Lazy @Qualifier("interesting")
 	@Retention(RetentionPolicy.RUNTIME)
 	@interface InterestingBean {
 	}
 
-	@Bean @Lazy @Qualifier("interesting")
+	@Bean(defaultCandidate=false) @Lazy @Qualifier("interesting")
 	@Retention(RetentionPolicy.RUNTIME)
 	@interface InterestingBeanWithName {