Improve documentation regarding "annotated classes"

See gh-23638

Author: sbrannen

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -34,8 +34,9 @@
 import org.springframework.util.Assert;
 
 /**
- * Convenient adapter for programmatic registration of annotated bean classes.
- * This is an alternative to {@link ClassPathBeanDefinitionScanner}, applying
+ * Convenient adapter for programmatic registration of bean classes.
+ *
+ * <p>This is an alternative to {@link ClassPathBeanDefinitionScanner}, applying
  * the same resolution of annotations but for explicitly registered classes only.
  *
  * @author Juergen Hoeller
@@ -58,7 +59,7 @@ public class AnnotatedBeanDefinitionReader {
 
 	/**
 	 * Create a new {@code AnnotatedBeanDefinitionReader} for the given registry.
-	 * If the registry is {@link EnvironmentCapable}, e.g. is an {@code ApplicationContext},
+	 * <p>If the registry is {@link EnvironmentCapable}, e.g. is an {@code ApplicationContext},
 	 * the {@link Environment} will be inherited, otherwise a new
 	 * {@link StandardEnvironment} will be created and used.
 	 * @param registry the {@code BeanFactory} to load bean definitions into,
@@ -71,8 +72,8 @@ public AnnotatedBeanDefinitionReader(BeanDefinitionRegistry registry) {
 	}
 
 	/**
-	 * Create a new {@code AnnotatedBeanDefinitionReader} for the given registry and using
-	 * the given {@link Environment}.
+	 * Create a new {@code AnnotatedBeanDefinitionReader} for the given registry,
+	 * using the given {@link Environment}.
 	 * @param registry the {@code BeanFactory} to load bean definitions into,
 	 * in the form of a {@code BeanDefinitionRegistry}
 	 * @param environment the {@code Environment} to use when evaluating bean definition
@@ -89,14 +90,14 @@ public AnnotatedBeanDefinitionReader(BeanDefinitionRegistry registry, Environmen
 
 
 	/**
-	 * Return the BeanDefinitionRegistry that this scanner operates on.
+	 * Get the BeanDefinitionRegistry that this reader operates on.
 	 */
 	public final BeanDefinitionRegistry getRegistry() {
 		return this.registry;
 	}
 
 	/**
-	 * Set the Environment to use when evaluating whether
+	 * Set the {@code Environment} to use when evaluating whether
 	 * {@link Conditional @Conditional}-annotated component classes should be registered.
 	 * <p>The default is a {@link StandardEnvironment}.
 	 * @see #registerBean(Class, String, Class...)
@@ -106,15 +107,15 @@ public void setEnvironment(Environment environment) {
 	}
 
 	/**
-	 * Set the BeanNameGenerator to use for detected bean classes.
+	 * Set the {@code BeanNameGenerator} to use for detected bean classes.
 	 * <p>The default is a {@link AnnotationBeanNameGenerator}.
 	 */
 	public void setBeanNameGenerator(@Nullable BeanNameGenerator beanNameGenerator) {
 		this.beanNameGenerator = (beanNameGenerator != null ? beanNameGenerator : new AnnotationBeanNameGenerator());
 	}
 
 	/**
-	 * Set the ScopeMetadataResolver to use for detected bean classes.
+	 * Set the {@code ScopeMetadataResolver} to use for registered component classes.
 	 * <p>The default is an {@link AnnotationScopeMetadataResolver}.
 	 */
 	public void setScopeMetadataResolver(@Nullable ScopeMetadataResolver scopeMetadataResolver) {
@@ -124,83 +125,83 @@ public void setScopeMetadataResolver(@Nullable ScopeMetadataResolver scopeMetada
 
 
 	/**
-	 * Register one or more annotated classes to be processed.
+	 * Register one or more component classes to be processed.
 	 * <p>Calls to {@code register} are idempotent; adding the same
-	 * annotated class more than once has no additional effect.
-	 * @param annotatedClasses one or more annotated classes,
+	 * component class more than once has no additional effect.
+	 * @param componentClasses one or more component classes,
 	 * e.g. {@link Configuration @Configuration} classes
 	 */
-	public void register(Class<?>... annotatedClasses) {
-		for (Class<?> annotatedClass : annotatedClasses) {
-			registerBean(annotatedClass);
+	public void register(Class<?>... componentClasses) {
+		for (Class<?> componentClass : componentClasses) {
+			registerBean(componentClass);
 		}
 	}
 
 	/**
 	 * Register a bean from the given bean class, deriving its metadata from
 	 * class-declared annotations.
-	 * @param annotatedClass the class of the bean
+	 * @param beanClass the class of the bean
 	 */
-	public void registerBean(Class<?> annotatedClass) {
-		doRegisterBean(annotatedClass, null, null, null);
+	public void registerBean(Class<?> beanClass) {
+		doRegisterBean(beanClass, null, null, null);
 	}
 
 	/**
 	 * Register a bean from the given bean class, deriving its metadata from
 	 * class-declared annotations, using the given supplier for obtaining a new
 	 * instance (possibly declared as a lambda expression or method reference).
-	 * @param annotatedClass the class of the bean
+	 * @param beanClass the class of the bean
 	 * @param instanceSupplier a callback for creating an instance of the bean
 	 * (may be {@code null})
 	 * @since 5.0
 	 */
-	public <T> void registerBean(Class<T> annotatedClass, @Nullable Supplier<T> instanceSupplier) {
-		doRegisterBean(annotatedClass, instanceSupplier, null, null);
+	public <T> void registerBean(Class<T> beanClass, @Nullable Supplier<T> instanceSupplier) {
+		doRegisterBean(beanClass, instanceSupplier, null, null);
 	}
 
 	/**
 	 * Register a bean from the given bean class, deriving its metadata from
 	 * class-declared annotations, using the given supplier for obtaining a new
 	 * instance (possibly declared as a lambda expression or method reference).
-	 * @param annotatedClass the class of the bean
+	 * @param beanClass the class of the bean
 	 * @param name an explicit name for the bean
 	 * @param instanceSupplier a callback for creating an instance of the bean
 	 * (may be {@code null})
 	 * @since 5.0
 	 */
-	public <T> void registerBean(Class<T> annotatedClass, String name, @Nullable Supplier<T> instanceSupplier) {
-		doRegisterBean(annotatedClass, instanceSupplier, name, null);
+	public <T> void registerBean(Class<T> beanClass, String name, @Nullable Supplier<T> instanceSupplier) {
+		doRegisterBean(beanClass, instanceSupplier, name, null);
 	}
 
 	/**
 	 * Register a bean from the given bean class, deriving its metadata from
 	 * class-declared annotations.
-	 * @param annotatedClass the class of the bean
+	 * @param beanClass the class of the bean
 	 * @param qualifiers specific qualifier annotations to consider,
 	 * in addition to qualifiers at the bean class level
 	 */
 	@SuppressWarnings("unchecked")
-	public void registerBean(Class<?> annotatedClass, Class<? extends Annotation>... qualifiers) {
-		doRegisterBean(annotatedClass, null, null, qualifiers);
+	public void registerBean(Class<?> beanClass, Class<? extends Annotation>... qualifiers) {
+		doRegisterBean(beanClass, null, null, qualifiers);
 	}
 
 	/**
 	 * Register a bean from the given bean class, deriving its metadata from
 	 * class-declared annotations.
-	 * @param annotatedClass the class of the bean
+	 * @param beanClass the class of the bean
 	 * @param name an explicit name for the bean
 	 * @param qualifiers specific qualifier annotations to consider,
 	 * in addition to qualifiers at the bean class level
 	 */
 	@SuppressWarnings("unchecked")
-	public void registerBean(Class<?> annotatedClass, String name, Class<? extends Annotation>... qualifiers) {
-		doRegisterBean(annotatedClass, null, name, qualifiers);
+	public void registerBean(Class<?> beanClass, String name, Class<? extends Annotation>... qualifiers) {
+		doRegisterBean(beanClass, null, name, qualifiers);
 	}
 
 	/**
 	 * Register a bean from the given bean class, deriving its metadata from
 	 * class-declared annotations.
-	 * @param annotatedClass the class of the bean
+	 * @param beanClass the class of the bean
 	 * @param instanceSupplier a callback for creating an instance of the bean
 	 * (may be {@code null})
 	 * @param name an explicit name for the bean
@@ -210,10 +211,10 @@ public void registerBean(Class<?> annotatedClass, String name, Class<? extends A
 	 * factory's {@link BeanDefinition}, e.g. setting a lazy-init or primary flag
 	 * @since 5.0
 	 */
-	<T> void doRegisterBean(Class<T> annotatedClass, @Nullable Supplier<T> instanceSupplier, @Nullable String name,
+	<T> void doRegisterBean(Class<T> beanClass, @Nullable Supplier<T> instanceSupplier, @Nullable String name,
 			@Nullable Class<? extends Annotation>[] qualifiers, BeanDefinitionCustomizer... definitionCustomizers) {
 
-		AnnotatedGenericBeanDefinition abd = new AnnotatedGenericBeanDefinition(annotatedClass);
+		AnnotatedGenericBeanDefinition abd = new AnnotatedGenericBeanDefinition(beanClass);
 		if (this.conditionEvaluator.shouldSkip(abd.getMetadata())) {
 			return;
 		}

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -27,19 +27,20 @@
 import org.springframework.util.Assert;
 
 /**
- * Standalone application context, accepting annotated classes as input - in particular
- * {@link Configuration @Configuration}-annotated classes, but also plain
+ * Standalone application context, accepting <em>component classes</em> as input &mdash;
+ * in particular {@link Configuration @Configuration}-annotated classes, but also plain
  * {@link org.springframework.stereotype.Component @Component} types and JSR-330 compliant
- * classes using {@code javax.inject} annotations. Allows for registering classes one by
- * one using {@link #register(Class...)} as well as for classpath scanning using
- * {@link #scan(String...)}.
+ * classes using {@code javax.inject} annotations.
  *
- * <p>In case of multiple {@code @Configuration} classes, @{@link Bean} methods defined in
- * later classes will override those defined in earlier classes. This can be leveraged to
- * deliberately override certain bean definitions via an extra {@code @Configuration}
- * class.
+ * <p>Allows for registering classes one by one using {@link #register(Class...)}
+ * as well as for classpath scanning using {@link #scan(String...)}.
  *
- * <p>See @{@link Configuration}'s javadoc for usage examples.
+ * <p>In case of multiple {@code @Configuration} classes, {@link Bean @Bean} methods
+ * defined in later classes will override those defined in earlier classes. This can
+ * be leveraged to deliberately override certain bean definitions via an extra
+ * {@code @Configuration} class.
+ *
+ * <p>See {@link Configuration @Configuration}'s javadoc for usage examples.
  *
  * @author Juergen Hoeller
  * @author Chris Beams
@@ -78,20 +79,21 @@ public AnnotationConfigApplicationContext(DefaultListableBeanFactory beanFactory
 
 	/**
 	 * Create a new AnnotationConfigApplicationContext, deriving bean definitions
-	 * from the given annotated classes and automatically refreshing the context.
-	 * @param annotatedClasses one or more annotated classes,
-	 * e.g. {@link Configuration @Configuration} classes
+	 * from the given component classes and automatically refreshing the context.
+	 * @param componentClasses one or more component classes &mdash; for example,
+	 * {@link Configuration @Configuration} classes
 	 */
-	public AnnotationConfigApplicationContext(Class<?>... annotatedClasses) {
+	public AnnotationConfigApplicationContext(Class<?>... componentClasses) {
 		this();
-		register(annotatedClasses);
+		register(componentClasses);
 		refresh();
 	}
 
 	/**
-	 * Create a new AnnotationConfigApplicationContext, scanning for bean definitions
-	 * in the given packages and automatically refreshing the context.
-	 * @param basePackages the packages to check for annotated classes
+	 * Create a new AnnotationConfigApplicationContext, scanning for components
+	 * in the given packages, registering bean definitions for those components,
+	 * and automatically refreshing the context.
+	 * @param basePackages the packages to scan for component classes
 	 */
 	public AnnotationConfigApplicationContext(String... basePackages) {
 		this();
@@ -101,7 +103,7 @@ public AnnotationConfigApplicationContext(String... basePackages) {
 
 
 	/**
-	 * Propagates the given custom {@code Environment} to the underlying
+	 * Propagate the given custom {@code Environment} to the underlying
 	 * {@link AnnotatedBeanDefinitionReader} and {@link ClassPathBeanDefinitionScanner}.
 	 */
 	@Override
@@ -128,7 +130,7 @@ public void setBeanNameGenerator(BeanNameGenerator beanNameGenerator) {
 	}
 
 	/**
-	 * Set the {@link ScopeMetadataResolver} to use for detected bean classes.
+	 * Set the {@link ScopeMetadataResolver} to use for registered component classes.
 	 * <p>The default is an {@link AnnotationScopeMetadataResolver}.
 	 * <p>Any call to this method must occur prior to calls to {@link #register(Class...)}
 	 * and/or {@link #scan(String...)}.
@@ -144,27 +146,29 @@ public void setScopeMetadataResolver(ScopeMetadataResolver scopeMetadataResolver
 	//---------------------------------------------------------------------
 
 	/**
-	 * Register one or more annotated classes to be processed.
+	 * Register one or more component classes to be processed.
 	 * <p>Note that {@link #refresh()} must be called in order for the context
 	 * to fully process the new classes.
-	 * @param annotatedClasses one or more annotated classes,
-	 * e.g. {@link Configuration @Configuration} classes
+	 * @param componentClasses one or more component classes &mdash; for example,
+	 * {@link Configuration @Configuration} classes
 	 * @see #scan(String...)
 	 * @see #refresh()
 	 */
-	public void register(Class<?>... annotatedClasses) {
-		Assert.notEmpty(annotatedClasses, "At least one annotated class must be specified");
-		this.reader.register(annotatedClasses);
+	@Override
+	public void register(Class<?>... componentClasses) {
+		Assert.notEmpty(componentClasses, "At least one component class must be specified");
+		this.reader.register(componentClasses);
 	}
 
 	/**
 	 * Perform a scan within the specified base packages.
 	 * <p>Note that {@link #refresh()} must be called in order for the context
 	 * to fully process the new classes.
-	 * @param basePackages the packages to check for annotated classes
+	 * @param basePackages the packages to scan for component classes
 	 * @see #register(Class...)
 	 * @see #refresh()
 	 */
+	@Override
 	public void scan(String... basePackages) {
 		Assert.notEmpty(basePackages, "At least one base package must be specified");
 		this.scanner.scan(basePackages);
@@ -180,31 +184,31 @@ public void scan(String... basePackages) {
 	 * class-declared annotations, and optionally providing explicit constructor
 	 * arguments for consideration in the autowiring process.
 	 * <p>The bean name will be generated according to annotated component rules.
-	 * @param annotatedClass the class of the bean
+	 * @param beanClass the class of the bean
 	 * @param constructorArguments argument values to be fed into Spring's
 	 * constructor resolution algorithm, resolving either all arguments or just
 	 * specific ones, with the rest to be resolved through regular autowiring
 	 * (may be {@code null} or empty)
 	 * @since 5.0
 	 */
-	public <T> void registerBean(Class<T> annotatedClass, Object... constructorArguments) {
-		registerBean(null, annotatedClass, constructorArguments);
+	public <T> void registerBean(Class<T> beanClass, Object... constructorArguments) {
+		registerBean(null, beanClass, constructorArguments);
 	}
 
 	/**
 	 * Register a bean from the given bean class, deriving its metadata from
 	 * class-declared annotations, and optionally providing explicit constructor
 	 * arguments for consideration in the autowiring process.
 	 * @param beanName the name of the bean (may be {@code null})
-	 * @param annotatedClass the class of the bean
+	 * @param beanClass the class of the bean
 	 * @param constructorArguments argument values to be fed into Spring's
 	 * constructor resolution algorithm, resolving either all arguments or just
 	 * specific ones, with the rest to be resolved through regular autowiring
 	 * (may be {@code null} or empty)
 	 * @since 5.0
 	 */
-	public <T> void registerBean(@Nullable String beanName, Class<T> annotatedClass, Object... constructorArguments) {
-		this.reader.doRegisterBean(annotatedClass, null, beanName, null,
+	public <T> void registerBean(@Nullable String beanName, Class<T> beanClass, Object... constructorArguments) {
+		this.reader.doRegisterBean(beanClass, null, beanName, null,
 				bd -> {
 					for (Object arg : constructorArguments) {
 						bd.getConstructorArgumentValues().addGenericArgumentValue(arg);

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -26,17 +26,17 @@
 public interface AnnotationConfigRegistry {
 
 	/**
-	 * Register one or more annotated classes to be processed.
+	 * Register one or more component classes to be processed.
 	 * <p>Calls to {@code register} are idempotent; adding the same
-	 * annotated class more than once has no additional effect.
-	 * @param annotatedClasses one or more annotated classes,
+	 * component class more than once has no additional effect.
+	 * @param componentClasses one or more component classes,
 	 * e.g. {@link Configuration @Configuration} classes
 	 */
-	void register(Class<?>... annotatedClasses);
+	void register(Class<?>... componentClasses);
 
 	/**
 	 * Perform a scan within the specified base packages.
-	 * @param basePackages the packages to check for annotated classes
+	 * @param basePackages the packages to scan for component classes
 	 */
 	void scan(String... basePackages);
 

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

@@ -352,7 +352,8 @@
  *
  * <p>The Spring <em>TestContext framework</em> available in the {@code spring-test} module
  * provides the {@code @ContextConfiguration} annotation which can accept an array of
- * {@code @Configuration} {@code Class} objects:
+ * <em>component class</em> references &mdash; typically {@code @Configuration} or
+ * {@code @Component} classes.
  *
  * <pre class="code">
  * &#064;RunWith(SpringRunner.class)