Improve documentation for FullyQualifiedConfigurationBeanNameGenerator

This commit documents FullyQualifiedConfigurationBeanNameGenerator in related Javadoc and in the reference manual. See gh-33448 Closes gh-36455
2026-06-08 17:33:33 +00:00 · 2026-03-11 17:41:07 +01:00
parent e634ced56b
commit 04313f062e
11 changed files with 106 additions and 45 deletions
@@ -109,7 +109,9 @@ public class AnnotatedBeanDefinitionReader {

 	/**
 	 * Set the {@code BeanNameGenerator} to use for detected bean classes.
-	 * <p>The default is a {@link AnnotationBeanNameGenerator}.
+	 * <p>The default is an {@link AnnotationBeanNameGenerator}.
+	 * @see FullyQualifiedAnnotationBeanNameGenerator
+	 * @see FullyQualifiedConfigurationBeanNameGenerator
 	 */
 	public void setBeanNameGenerator(@Nullable BeanNameGenerator beanNameGenerator) {
 		this.beanNameGenerator =
@@ -118,14 +118,20 @@ public class AnnotationConfigApplicationContext extends GenericApplicationContex

 	/**
 	 * Provide a custom {@link BeanNameGenerator} for use with {@link AnnotatedBeanDefinitionReader}
-	 * and/or {@link ClassPathBeanDefinitionScanner}, if any.
-	 * <p>Default is {@link AnnotationBeanNameGenerator}.
+	 * and/or {@link ClassPathBeanDefinitionScanner}.
+	 * <p>Default is {@code AnnotationBeanNameGenerator}.
+	 * <p>When processing {@link Configuration @Configuration} classes, a
+	 * {@link ConfigurationBeanNameGenerator} (such as
+	 * {@link FullyQualifiedConfigurationBeanNameGenerator}) also determines the
+	 * default names for {@link Bean @Bean} methods without an explicit {@code name}
+	 * attribute.
 	 * <p>Any call to this method must occur prior to calls to {@link #register(Class...)}
 	 * and/or {@link #scan(String...)}.
 	 * @see AnnotatedBeanDefinitionReader#setBeanNameGenerator
 	 * @see ClassPathBeanDefinitionScanner#setBeanNameGenerator
 	 * @see AnnotationBeanNameGenerator
 	 * @see FullyQualifiedAnnotationBeanNameGenerator
+	 * @see FullyQualifiedConfigurationBeanNameGenerator
 	 */
 	public void setBeanNameGenerator(BeanNameGenerator beanNameGenerator) {
 		this.reader.setBeanNameGenerator(beanNameGenerator);
@@ -45,10 +45,12 @@ import org.springframework.core.annotation.AliasFor;
 *
 * <p>While a {@link #name} attribute is available, the default strategy for
 * determining the name of a bean is to use the name of the {@code @Bean} method.
- * This is convenient and intuitive, but if explicit naming is desired, the
- * {@code name} attribute (or its alias {@code value}) may be used. Also note
- * that {@code name} accepts an array of Strings, allowing for multiple names
- * (i.e. a primary bean name plus one or more aliases) for a single bean.
+ * This default can be overridden by configuring a {@link ConfigurationBeanNameGenerator}
+ * &mdash; for example, {@link FullyQualifiedConfigurationBeanNameGenerator} for
+ * fully-qualified names. If explicit naming is desired for an individual bean, the
+ * {@code name} attribute (or its alias {@link #value}) may be used. Also note that
+ * {@code name} accepts an array of Strings, allowing for multiple names (i.e., a
+ * primary bean name plus one or more aliases) for a single bean.
 *
 * <pre class="code">
 * &#064;Bean({"b1", "b2"}) // bean available as 'b1' and 'b2', but not 'myBean'
@@ -237,6 +239,9 @@ import org.springframework.core.annotation.AliasFor;
 * @see org.springframework.stereotype.Component
 * @see org.springframework.beans.factory.annotation.Autowired
 * @see org.springframework.beans.factory.annotation.Value
+ * @see FullyQualifiedConfigurationBeanNameGenerator
+ * @see AnnotationConfigApplicationContext#setBeanNameGenerator
+ * @see ComponentScan#nameGenerator()
 */
@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@@ -255,10 +260,11 @@ public @interface Bean {

 	/**
 	 * The name of this bean, or if several names, a primary bean name plus aliases.
-	 * <p>If left unspecified, the name of the bean is the name of the annotated method.
-	 * If specified, the method name is ignored.
+	 * <p>See the "Bean Names" section in the {@linkplain Bean class-level documentation}
+	 * for details on how the bean name is determined if this attribute is left
+	 * unspecified.
 	 * <p>The bean name and aliases may also be configured via the {@link #value}
-	 * attribute if no other attributes are declared.
+	 * attribute.
 	 * @see #value
 	 */
 	@AliasFor("value")
@@ -43,11 +43,11 @@ import org.springframework.util.PatternMatchUtils;
 * or {@code ApplicationContext}).
 *
 * <p>Candidate classes are detected through configurable type filters. The
- * default filters include classes that are annotated with Spring's
- * {@link org.springframework.stereotype.Component @Component},
+ * default filters include classes that are annotated or meta-annotated with Spring's
+ * {@link org.springframework.stereotype.Component @Component} annotation, such as the
 * {@link org.springframework.stereotype.Repository @Repository},
- * {@link org.springframework.stereotype.Service @Service}, or
- * {@link org.springframework.stereotype.Controller @Controller} stereotype.
+ * {@link org.springframework.stereotype.Service @Service}, and
+ * {@link org.springframework.stereotype.Controller @Controller} stereotypes.
 *
 * <p>Also supports JSR-330's {@link jakarta.inject.Named} annotations, if available.
 *
@@ -204,8 +204,11 @@ public class ClassPathBeanDefinitionScanner extends ClassPathScanningCandidateCo
 	}

 	/**
-	 * Set the BeanNameGenerator to use for detected bean classes.
-	 * <p>Default is a {@link AnnotationBeanNameGenerator}.
+	 * Set the {@link BeanNameGenerator} to use for detected bean classes.
+	 * <p>Default is an {@code AnnotationBeanNameGenerator}.
+	 * @see AnnotationBeanNameGenerator
+	 * @see FullyQualifiedAnnotationBeanNameGenerator
+	 * @see FullyQualifiedConfigurationBeanNameGenerator
 	 */
 	public void setBeanNameGenerator(@Nullable BeanNameGenerator beanNameGenerator) {
 		this.beanNameGenerator =
@@ -109,14 +109,18 @@ public @interface ComponentScan {
 	/**
 	 * The {@link BeanNameGenerator} class to be used for naming detected components
 	 * within the Spring container.
-	 * <p>The default value of the {@link BeanNameGenerator} interface itself indicates
+	 * <p>The default value of the {@code BeanNameGenerator} interface itself indicates
 	 * that the scanner used to process this {@code @ComponentScan} annotation should
 	 * use its inherited bean name generator, for example, the default
 	 * {@link AnnotationBeanNameGenerator} or any custom instance supplied to the
-	 * application context at bootstrap time.
+	 * application context at bootstrap time. If a {@link ConfigurationBeanNameGenerator}
+	 * is used (such as {@link FullyQualifiedConfigurationBeanNameGenerator}), it
+	 * also affects the default names for {@link Bean @Bean} methods in
+	 * {@link Configuration @Configuration} classes.
 	 * @see AnnotationConfigApplicationContext#setBeanNameGenerator(BeanNameGenerator)
 	 * @see AnnotationBeanNameGenerator
 	 * @see FullyQualifiedAnnotationBeanNameGenerator
+	 * @see FullyQualifiedConfigurationBeanNameGenerator
 	 */
 	Class<? extends BeanNameGenerator> nameGenerator() default BeanNameGenerator.class;

@@ -437,6 +437,8 @@ public @interface Configuration {
 	 * <p>Alias for {@link Component#value}.
 	 * @return the explicit component name, if any (or empty String otherwise)
 	 * @see AnnotationBeanNameGenerator
+	 * @see FullyQualifiedAnnotationBeanNameGenerator
+	 * @see FullyQualifiedConfigurationBeanNameGenerator
 	 */
 	@AliasFor(annotation = Component.class)
 	String value() default "";
@@ -242,12 +242,15 @@ public class ConfigurationClassPostProcessor implements BeanDefinitionRegistryPo

 	/**
 	 * Set the {@link BeanNameGenerator} to be used when triggering component scanning
-	 * from {@link Configuration} classes and when registering {@link Import}'ed
-	 * configuration classes. The default is a standard {@link AnnotationBeanNameGenerator}
-	 * for scanned components (compatible with the default in {@link ClassPathBeanDefinitionScanner})
+	 * from {@link Configuration @Configuration} classes and when registering
+	 * {@link Import @Import}'ed configuration classes.
+	 * <p>The default is a standard {@link AnnotationBeanNameGenerator} for scanned
+	 * components (compatible with the default in {@link ClassPathBeanDefinitionScanner})
 	 * and a variant thereof for imported configuration classes (using unique fully-qualified
 	 * class names instead of standard component overriding).
-	 * <p>Note that this strategy does <em>not</em> apply to {@link Bean} methods.
+	 * <p>If the supplied bean name generator is a {@link ConfigurationBeanNameGenerator}
+	 * (such as {@link FullyQualifiedConfigurationBeanNameGenerator}), it also affects the
+	 * default names for {@link Bean @Bean} methods in configuration classes.
 	 * <p>This setter is typically only appropriate when configuring the post-processor as a
 	 * standalone bean definition in XML, for example, not using the dedicated {@code AnnotationConfig*}
 	 * application contexts or the {@code <context:annotation-config>} element. Any bean name
@@ -255,6 +258,9 @@ public class ConfigurationClassPostProcessor implements BeanDefinitionRegistryPo
 	 * @since 3.1.1
 	 * @see AnnotationConfigApplicationContext#setBeanNameGenerator(BeanNameGenerator)
 	 * @see AnnotationConfigUtils#CONFIGURATION_BEAN_NAME_GENERATOR
+	 * @see AnnotationBeanNameGenerator
+	 * @see FullyQualifiedAnnotationBeanNameGenerator
+	 * @see FullyQualifiedConfigurationBeanNameGenerator
 	 */
 	public void setBeanNameGenerator(BeanNameGenerator beanNameGenerator) {
 		Assert.notNull(beanNameGenerator, "BeanNameGenerator must not be null");