From 15ede46eb8e7381360269d04931a26299b7ca995 Mon Sep 17 00:00:00 2001 From: Phillip Webb Date: Wed, 17 Dec 2025 11:48:03 -0800 Subject: [PATCH] Improve javadoc for when to use class names rather than class references Closes gh-48395 --- .../boot/autoconfigure/AutoConfiguration.java | 12 ++++++++++ .../autoconfigure/AutoConfigureAfter.java | 6 +++++ .../autoconfigure/AutoConfigureBefore.java | 6 +++++ .../EnableAutoConfiguration.java | 6 +++++ .../autoconfigure/SpringBootApplication.java | 7 +++++- .../condition/ConditionalOnBean.java | 16 ++++++++++++++ .../condition/ConditionalOnClass.java | 12 +++++----- .../condition/ConditionalOnMissingBean.java | 22 +++++++++++++++++++ .../ConditionalOnSingleCandidate.java | 6 +++++ 9 files changed, 87 insertions(+), 6 deletions(-) diff --git a/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/AutoConfiguration.java b/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/AutoConfiguration.java index 86ea4681e3f..0a89093db30 100644 --- a/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/AutoConfiguration.java +++ b/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/AutoConfiguration.java @@ -78,6 +78,12 @@ public @interface AutoConfiguration { /** * The auto-configuration classes that should have not yet been applied. + *

+ * Since this annotation is parsed by loading class bytecode, it is safe to specify + * classes here that may ultimately not be on the classpath, only if this annotation + * is directly on the affected component and not if this annotation is used as + * a composed, meta-annotation. In order to use this annotation as a meta-annotation, + * only use the {@link #beforeName} attribute. * @return the classes */ @AliasFor(annotation = AutoConfigureBefore.class, attribute = "value") @@ -95,6 +101,12 @@ public @interface AutoConfiguration { /** * The auto-configuration classes that should have already been applied. + *

+ * Since this annotation is parsed by loading class bytecode, it is safe to specify + * classes here that may ultimately not be on the classpath, only if this annotation + * is directly on the affected component and not if this annotation is used as + * a composed, meta-annotation. In order to use this annotation as a meta-annotation, + * only use the {@link #afterName} attribute. * @return the classes */ @AliasFor(annotation = AutoConfigureAfter.class, attribute = "value") diff --git a/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/AutoConfigureAfter.java b/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/AutoConfigureAfter.java index 6c4aaa345f5..4188a91f1e3 100644 --- a/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/AutoConfigureAfter.java +++ b/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/AutoConfigureAfter.java @@ -45,6 +45,12 @@ public @interface AutoConfigureAfter { /** * The auto-configuration classes that should have already been applied. + *

+ * Since this annotation is parsed by loading class bytecode, it is safe to specify + * classes here that may ultimately not be on the classpath, only if this annotation + * is directly on the affected component and not if this annotation is used as + * a composed, meta-annotation. In order to use this annotation as a meta-annotation, + * only use the {@link #name} attribute. * @return the classes */ Class[] value() default {}; diff --git a/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/AutoConfigureBefore.java b/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/AutoConfigureBefore.java index fdabeb187f4..f637483c6c6 100644 --- a/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/AutoConfigureBefore.java +++ b/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/AutoConfigureBefore.java @@ -45,6 +45,12 @@ public @interface AutoConfigureBefore { /** * The auto-configuration classes that should have not yet been applied. + *

+ * Since this annotation is parsed by loading class bytecode, it is safe to specify + * classes here that may ultimately not be on the classpath, only if this annotation + * is directly on the affected component and not if this annotation is used as + * a composed, meta-annotation. In order to use this annotation as a meta-annotation, + * only use the {@link #name} attribute. * @return the classes */ Class[] value() default {}; diff --git a/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/EnableAutoConfiguration.java b/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/EnableAutoConfiguration.java index b6684c0ba79..2423b044570 100644 --- a/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/EnableAutoConfiguration.java +++ b/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/EnableAutoConfiguration.java @@ -90,6 +90,12 @@ public @interface EnableAutoConfiguration { /** * Exclude specific auto-configuration classes such that they will never be applied. + *

+ * Since this annotation is parsed by loading class bytecode, it is safe to specify + * classes here that may ultimately not be on the classpath, only if this annotation + * is directly on the affected component and not if this annotation is used as + * a composed, meta-annotation. In order to use this annotation as a meta-annotation, + * only use the {@link #excludeName()} attribute. * @return the classes to exclude */ Class[] exclude() default {}; diff --git a/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/SpringBootApplication.java b/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/SpringBootApplication.java index 78a80f5febe..62b8b4a8d50 100644 --- a/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/SpringBootApplication.java +++ b/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/SpringBootApplication.java @@ -34,7 +34,6 @@ import org.springframework.context.annotation.ComponentScan.Filter; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.FilterType; import org.springframework.core.annotation.AliasFor; -import org.springframework.data.repository.Repository; /** * Indicates a {@link Configuration configuration} class that declares one or more @@ -60,6 +59,12 @@ public @interface SpringBootApplication { /** * Exclude specific auto-configuration classes such that they will never be applied. + *

+ * Since this annotation is parsed by loading class bytecode, it is safe to specify + * classes here that may ultimately not be on the classpath, only if this annotation + * is directly on the affected component and not if this annotation is used as + * a composed, meta-annotation. In order to use this annotation as a meta-annotation, + * only use the {@link #excludeName} attribute. * @return the classes to exclude */ @AliasFor(annotation = EnableAutoConfiguration.class) diff --git a/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnBean.java b/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnBean.java index dd7642f14d8..32833baad07 100644 --- a/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnBean.java +++ b/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnBean.java @@ -72,6 +72,12 @@ public @interface ConditionalOnBean { * The class types of beans that should be checked. The condition matches when beans * of all classes specified are contained in the {@link BeanFactory}. Beans that are * not autowire candidates or that are not default candidates are ignored. + *

+ * Since this annotation is parsed by loading class bytecode, it is safe to specify + * classes here that may ultimately not be on the classpath, only if this annotation + * is directly on the affected component and not if this annotation is used as + * a composed, meta-annotation. In order to use this annotation as a meta-annotation, + * only use the {@link #type} attribute. * @return the class types of beans to check * @see Bean#autowireCandidate() * @see BeanDefinition#isAutowireCandidate @@ -97,6 +103,11 @@ public @interface ConditionalOnBean { * when all the annotations specified are defined on beans in the {@link BeanFactory}. * Beans that are not autowire candidates or that are not default candidates are * ignored. + *

+ * Since this annotation is parsed by loading class bytecode, it is safe to specify + * classes here that may ultimately not be on the classpath, only if this annotation + * is directly on the affected component and not if this annotation is used as + * a composed, meta-annotation. * @return the class-level annotation types to check * @see Bean#autowireCandidate() * @see BeanDefinition#isAutowireCandidate @@ -124,6 +135,11 @@ public @interface ConditionalOnBean { * parameters. For example, an annotation declaring {@code value=Name.class} and * {@code parameterizedContainer=NameRegistration.class} would detect both * {@code Name} and {@code NameRegistration}. + *

+ * Since this annotation is parsed by loading class bytecode, it is safe to specify + * classes here that may ultimately not be on the classpath, only if this annotation + * is directly on the affected component and not if this annotation is used as + * a composed, meta-annotation. * @return the container types * @since 2.1.0 */ diff --git a/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnClass.java b/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnClass.java index 492e6cf12bc..5f5233ce604 100644 --- a/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnClass.java +++ b/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnClass.java @@ -66,11 +66,13 @@ import org.springframework.context.annotation.Conditional; public @interface ConditionalOnClass { /** - * The classes that must be present. Since this annotation is parsed by loading class - * bytecode, it is safe to specify classes here that may ultimately not be on the - * classpath, only if this annotation is directly on the affected component and - * not if this annotation is used as a composed, meta-annotation. In order to - * use this annotation as a meta-annotation, only use the {@link #name} attribute. + * The classes that must be present. + *

+ * Since this annotation is parsed by loading class bytecode, it is safe to specify + * classes here that may ultimately not be on the classpath, only if this annotation + * is directly on the affected component and not if this annotation is used as + * a composed, meta-annotation. In order to use this annotation as a meta-annotation, + * only use the {@link #name} attribute. * @return the classes that must be present */ Class[] value() default {}; diff --git a/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnMissingBean.java b/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnMissingBean.java index 9785ade9399..ca238aef3e5 100644 --- a/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnMissingBean.java +++ b/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnMissingBean.java @@ -73,6 +73,12 @@ public @interface ConditionalOnMissingBean { * The class types of beans that should be checked. The condition matches when no bean * of each class specified is contained in the {@link BeanFactory}. Beans that are not * autowire candidates or that are not default candidates are ignored. + *

+ * Since this annotation is parsed by loading class bytecode, it is safe to specify + * classes here that may ultimately not be on the classpath, only if this annotation + * is directly on the affected component and not if this annotation is used as + * a composed, meta-annotation. In order to use this annotation as a meta-annotation, + * only use the {@link #type} attribute. * @return the class types of beans to check * @see Bean#autowireCandidate() * @see BeanDefinition#isAutowireCandidate @@ -95,6 +101,12 @@ public @interface ConditionalOnMissingBean { /** * The class types of beans that should be ignored when identifying matching beans. + *

+ * Since this annotation is parsed by loading class bytecode, it is safe to specify + * classes here that may ultimately not be on the classpath, only if this annotation + * is directly on the affected component and not if this annotation is used as + * a composed, meta-annotation. In order to use this annotation as a meta-annotation, + * only use the {@link #ignoredType} attribute. * @return the class types of beans to ignore * @since 1.2.5 */ @@ -113,6 +125,11 @@ public @interface ConditionalOnMissingBean { * when each annotation specified is missing from all beans in the * {@link BeanFactory}. Beans that are not autowire candidates or that are not default * candidates are ignored. + *

+ * Since this annotation is parsed by loading class bytecode, it is safe to specify + * classes here that may ultimately not be on the classpath, only if this annotation + * is directly on the affected component and not if this annotation is used as + * a composed, meta-annotation. * @return the class-level annotation types to check * @see Bean#autowireCandidate() * @see BeanDefinition#isAutowireCandidate @@ -140,6 +157,11 @@ public @interface ConditionalOnMissingBean { * parameters. For example, an annotation declaring {@code value=Name.class} and * {@code parameterizedContainer=NameRegistration.class} would detect both * {@code Name} and {@code NameRegistration}. + *

+ * Since this annotation is parsed by loading class bytecode, it is safe to specify + * classes here that may ultimately not be on the classpath, only if this annotation + * is directly on the affected component and not if this annotation is used as + * a composed, meta-annotation. * @return the container types * @since 2.1.0 */ diff --git a/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnSingleCandidate.java b/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnSingleCandidate.java index 6742aeae980..15636dc7543 100644 --- a/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnSingleCandidate.java +++ b/spring-boot-project/spring-boot-autoconfigure/src/main/java/org/springframework/boot/autoconfigure/condition/ConditionalOnSingleCandidate.java @@ -57,6 +57,12 @@ public @interface ConditionalOnSingleCandidate { * exists in case of multiple instances. Beans that are not autowire candidates, that * are not default candidates, or that are fallback candidates are ignored. *

+ * Since this annotation is parsed by loading class bytecode, it is safe to specify + * classes here that may ultimately not be on the classpath, only if this annotation + * is directly on the affected component and not if this annotation is used as + * a composed, meta-annotation. In order to use this annotation as a meta-annotation, + * only use the {@link #type} attribute. + *

* This attribute may not be used in conjunction with * {@link #type()}, but it may be used instead of {@link #type()}. * @return the class type of the bean to check