diff --git a/spring-context/src/main/java/org/springframework/context/annotation/AnnotatedBeanDefinitionReader.java b/spring-context/src/main/java/org/springframework/context/annotation/AnnotatedBeanDefinitionReader.java index 19448f1794..eea4fa9631 100644 --- a/spring-context/src/main/java/org/springframework/context/annotation/AnnotatedBeanDefinitionReader.java +++ b/spring-context/src/main/java/org/springframework/context/annotation/AnnotatedBeanDefinitionReader.java @@ -34,8 +34,9 @@ import org.springframework.lang.Nullable; 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. + * + *

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}, + *

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 class AnnotatedBeanDefinitionReader { } /** - * 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 class AnnotatedBeanDefinitionReader { /** - * 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. *

The default is a {@link StandardEnvironment}. * @see #registerBean(Class, String, Class...) @@ -106,7 +107,7 @@ public class AnnotatedBeanDefinitionReader { } /** - * Set the BeanNameGenerator to use for detected bean classes. + * Set the {@code BeanNameGenerator} to use for detected bean classes. *

The default is a {@link AnnotationBeanNameGenerator}. */ public void setBeanNameGenerator(@Nullable BeanNameGenerator beanNameGenerator) { @@ -115,7 +116,7 @@ public class AnnotatedBeanDefinitionReader { } /** - * Set the ScopeMetadataResolver to use for detected bean classes. + * Set the {@code ScopeMetadataResolver} to use for registered component classes. *

The default is an {@link AnnotationScopeMetadataResolver}. */ public void setScopeMetadataResolver(@Nullable ScopeMetadataResolver scopeMetadataResolver) { @@ -125,99 +126,99 @@ public class AnnotatedBeanDefinitionReader { /** - * Register one or more annotated classes to be processed. + * Register one or more component classes to be processed. *

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, null); + public void registerBean(Class beanClass) { + doRegisterBean(beanClass, null, null, null, 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 name an explicit name for the bean * (or {@code null} for generating a default bean name) * @since 5.2 */ - public void registerBean(Class annotatedClass, @Nullable String name) { - doRegisterBean(annotatedClass, name, null, null, null); + public void registerBean(Class beanClass, @Nullable String name) { + doRegisterBean(beanClass, name, null, null, 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... qualifiers) { - doRegisterBean(annotatedClass, null, qualifiers, null, null); + public void registerBean(Class beanClass, Class... qualifiers) { + doRegisterBean(beanClass, null, qualifiers, null, 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 name an explicit name for the bean * (or {@code null} for generating a default bean name) * @param qualifiers specific qualifier annotations to consider, * in addition to qualifiers at the bean class level */ @SuppressWarnings("unchecked") - public void registerBean(Class annotatedClass, @Nullable String name, + public void registerBean(Class beanClass, @Nullable String name, Class... qualifiers) { - doRegisterBean(annotatedClass, name, qualifiers, null, null); + doRegisterBean(beanClass, name, qualifiers, 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 supplier a callback for creating an instance of the bean * (may be {@code null}) * @since 5.0 */ - public void registerBean(Class annotatedClass, @Nullable Supplier supplier) { - doRegisterBean(annotatedClass, null, null, supplier, null); + public void registerBean(Class beanClass, @Nullable Supplier supplier) { + doRegisterBean(beanClass, null, null, supplier, 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 * (or {@code null} for generating a default bean name) * @param supplier a callback for creating an instance of the bean * (may be {@code null}) * @since 5.0 */ - public void registerBean(Class annotatedClass, @Nullable String name, @Nullable Supplier supplier) { - doRegisterBean(annotatedClass, name, null, supplier, null); + public void registerBean(Class beanClass, @Nullable String name, @Nullable Supplier supplier) { + doRegisterBean(beanClass, name, null, supplier, 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 name an explicit name for the bean * (or {@code null} for generating a default bean name) * @param supplier a callback for creating an instance of the bean @@ -226,16 +227,16 @@ public class AnnotatedBeanDefinitionReader { * {@link BeanDefinition}, e.g. setting a lazy-init or primary flag * @since 5.2 */ - public void registerBean(Class annotatedClass, @Nullable String name, @Nullable Supplier supplier, + public void registerBean(Class beanClass, @Nullable String name, @Nullable Supplier supplier, BeanDefinitionCustomizer... customizers) { - doRegisterBean(annotatedClass, name, null, supplier, customizers); + doRegisterBean(beanClass, name, null, supplier, customizers); } /** * 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 supplier a callback for creating an instance of the bean * (may be {@code null}) @@ -245,11 +246,11 @@ public class AnnotatedBeanDefinitionReader { * {@link BeanDefinition}, e.g. setting a lazy-init or primary flag * @since 5.0 */ - private void doRegisterBean(Class annotatedClass, @Nullable String name, + private void doRegisterBean(Class beanClass, @Nullable String name, @Nullable Class[] qualifiers, @Nullable Supplier supplier, @Nullable BeanDefinitionCustomizer[] customizers) { - AnnotatedGenericBeanDefinition abd = new AnnotatedGenericBeanDefinition(annotatedClass); + AnnotatedGenericBeanDefinition abd = new AnnotatedGenericBeanDefinition(beanClass); if (this.conditionEvaluator.shouldSkip(abd.getMetadata())) { return; } diff --git a/spring-context/src/main/java/org/springframework/context/annotation/AnnotationConfigApplicationContext.java b/spring-context/src/main/java/org/springframework/context/annotation/AnnotationConfigApplicationContext.java index 1dafa1f1ad..fa98718d27 100644 --- a/spring-context/src/main/java/org/springframework/context/annotation/AnnotationConfigApplicationContext.java +++ b/spring-context/src/main/java/org/springframework/context/annotation/AnnotationConfigApplicationContext.java @@ -27,19 +27,20 @@ import org.springframework.lang.Nullable; 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 component classes as input — + * 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. * - *

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. + *

Allows for registering classes one by one using {@link #register(Class...)} + * as well as for classpath scanning using {@link #scan(String...)}. * - *

See @{@link Configuration}'s javadoc for usage examples. + *

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. + * + *

See {@link Configuration @Configuration}'s javadoc for usage examples. * * @author Juergen Hoeller * @author Chris Beams @@ -78,20 +79,21 @@ public class AnnotationConfigApplicationContext extends GenericApplicationContex /** * 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 — 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 class AnnotationConfigApplicationContext extends GenericApplicationContex /** - * 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 class AnnotationConfigApplicationContext extends GenericApplicationContex } /** - * Set the {@link ScopeMetadataResolver} to use for detected bean classes. + * Set the {@link ScopeMetadataResolver} to use for registered component classes. *

The default is an {@link AnnotationScopeMetadataResolver}. *

Any call to this method must occur prior to calls to {@link #register(Class...)} * and/or {@link #scan(String...)}. @@ -144,25 +146,25 @@ public class AnnotationConfigApplicationContext extends GenericApplicationContex //--------------------------------------------------------------------- /** - * Register one or more annotated classes to be processed. + * Register one or more component classes to be processed. *

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 — for example, + * {@link Configuration @Configuration} classes * @see #scan(String...) * @see #refresh() */ @Override - public void register(Class... annotatedClasses) { - Assert.notEmpty(annotatedClasses, "At least one annotated class must be specified"); - this.reader.register(annotatedClasses); + 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. *

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() */ diff --git a/spring-context/src/main/java/org/springframework/context/annotation/AnnotationConfigRegistry.java b/spring-context/src/main/java/org/springframework/context/annotation/AnnotationConfigRegistry.java index 5709d56f1a..4535537934 100644 --- a/spring-context/src/main/java/org/springframework/context/annotation/AnnotationConfigRegistry.java +++ b/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 @@ package org.springframework.context.annotation; public interface AnnotationConfigRegistry { /** - * Register one or more annotated classes to be processed. + * Register one or more component classes to be processed. *

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); diff --git a/spring-context/src/main/java/org/springframework/context/annotation/Configuration.java b/spring-context/src/main/java/org/springframework/context/annotation/Configuration.java index 33f38bdf14..1394fdc32c 100644 --- a/spring-context/src/main/java/org/springframework/context/annotation/Configuration.java +++ b/spring-context/src/main/java/org/springframework/context/annotation/Configuration.java @@ -352,7 +352,8 @@ import org.springframework.stereotype.Component; * *

The Spring TestContext framework available in the {@code spring-test} module * provides the {@code @ContextConfiguration} annotation which can accept an array of - * {@code @Configuration} {@code Class} objects: + * component class references — typically {@code @Configuration} or + * {@code @Component} classes. * *

  * @RunWith(SpringRunner.class)
diff --git a/spring-context/src/main/java/org/springframework/context/annotation/Import.java b/spring-context/src/main/java/org/springframework/context/annotation/Import.java
index 88e189c7f4..9c905d0d0b 100644
--- a/spring-context/src/main/java/org/springframework/context/annotation/Import.java
+++ b/spring-context/src/main/java/org/springframework/context/annotation/Import.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 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.
@@ -23,7 +23,8 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Indicates one or more {@link Configuration @Configuration} classes to import.
+ * Indicates one or more component classes to import — typically
+ * {@link Configuration @Configuration} classes.
  *
  * 

Provides functionality equivalent to the {@code } element in Spring XML. * Allows for importing {@code @Configuration} classes, {@link ImportSelector} and @@ -55,8 +56,8 @@ import java.lang.annotation.Target; public @interface Import { /** - * {@link Configuration}, {@link ImportSelector}, {@link ImportBeanDefinitionRegistrar} - * or regular component classes to import. + * {@link Configuration @Configuration}, {@link ImportSelector}, + * {@link ImportBeanDefinitionRegistrar}, or regular component classes to import. */ Class[] value(); diff --git a/spring-test/src/main/java/org/springframework/test/context/ContextConfiguration.java b/spring-test/src/main/java/org/springframework/test/context/ContextConfiguration.java index df34c9052d..e90c8d9be2 100644 --- a/spring-test/src/main/java/org/springframework/test/context/ContextConfiguration.java +++ b/spring-test/src/main/java/org/springframework/test/context/ContextConfiguration.java @@ -41,15 +41,15 @@ import org.springframework.core.annotation.AliasFor; * and class-based resources simultaneously. Consequently * {@code @ContextConfiguration} can be used to declare either path-based resource * locations (via the {@link #locations} or {@link #value} attribute) or - * annotated classes (via the {@link #classes} attribute). Note, however, that most + * component classes (via the {@link #classes} attribute). Note, however, that most * implementations of {@link SmartContextLoader} only support a single resource type. As * of Spring 4.1, path-based resource locations may be either XML configuration files or * Groovy scripts (if Groovy is on the classpath). Of course, third-party frameworks may * choose to support additional types of path-based resources. * - *

Annotated Classes

+ *

Component Classes

* - *

The term annotated class can refer to any of the following. + *

The term component class can refer to any of the following. * *

* + * A bean will be registered in the {@code ApplicationContext} for each component + * class, and such beans can therefore be injected into other beans or into the + * instance of the test class. + * *

Consult the Javadoc for {@link org.springframework.context.annotation.Configuration @Configuration} * and {@link org.springframework.context.annotation.Bean @Bean} for further - * information regarding the configuration and semantics of annotated classes. + * information regarding the configuration and semantics of component classes. * - *

As of Spring Framework 4.0, this annotation may be used as a meta-annotation - * to create custom composed annotations. + *

This annotation may be used as a meta-annotation to create custom + * composed annotations. * * @author Sam Brannen * @since 2.5 @@ -124,13 +131,13 @@ public @interface ContextConfiguration { String[] locations() default {}; /** - * The annotated classes to use for loading an + * The component classes to use for loading an * {@link org.springframework.context.ApplicationContext ApplicationContext}. *

Check out the javadoc for * {@link org.springframework.test.context.support.AnnotationConfigContextLoader#detectDefaultConfigurationClasses * AnnotationConfigContextLoader.detectDefaultConfigurationClasses()} for details * on how default configuration classes will be detected if no - * annotated classes are specified. See the documentation for + * component classes are specified. See the documentation for * {@link #loader} for further details regarding default loaders. * @since 3.1 * @see org.springframework.context.annotation.Configuration @@ -158,19 +165,20 @@ public @interface ContextConfiguration { Class>[] initializers() default {}; /** - * Whether or not {@link #locations resource locations} or annotated - * classes from test superclasses should be inherited. - *

The default value is {@code true}. This means that an annotated - * class will inherit the resource locations or annotated classes + * Whether or not {@linkplain #locations resource locations} or + * {@linkplain #classes component classes} from test superclasses + * should be inherited. + *

The default value is {@code true}. This means that an annotated test + * class will inherit the resource locations or component classes * defined by test superclasses. Specifically, the resource locations or - * annotated classes for a given test class will be appended to the list of - * resource locations or annotated classes defined by test superclasses. + * component classes for a given test class will be appended to the list of + * resource locations or component classes defined by test superclasses. * Thus, subclasses have the option of extending the list of resource - * locations or annotated classes. + * locations or component classes. *

If {@code inheritLocations} is set to {@code false}, the - * resource locations or annotated classes for the annotated class + * resource locations or component classes for the annotated test class * will shadow and effectively replace any resource locations - * or annotated classes defined by superclasses. + * or component classes defined by superclasses. *

In the following example that uses path-based resource locations, the * {@link org.springframework.context.ApplicationContext ApplicationContext} * for {@code ExtendedTest} will be loaded from @@ -189,8 +197,7 @@ public @interface ContextConfiguration { * // ... * } *

- *

Similarly, in the following example that uses annotated - * classes, the + *

Similarly, in the following example that uses component classes, the * {@link org.springframework.context.ApplicationContext ApplicationContext} * for {@code ExtendedTest} will be loaded from the * {@code BaseConfig} and {@code ExtendedConfig} @@ -215,15 +222,15 @@ public @interface ContextConfiguration { /** * Whether or not {@linkplain #initializers context initializers} from test * superclasses should be inherited. - *

The default value is {@code true}. This means that an annotated + *

The default value is {@code true}. This means that an annotated test * class will inherit the application context initializers defined * by test superclasses. Specifically, the initializers for a given test * class will be added to the set of initializers defined by test * superclasses. Thus, subclasses have the option of extending the * set of initializers. - *

If {@code inheritInitializers} is set to {@code false}, the - * initializers for the annotated class will shadow and effectively - * replace any initializers defined by superclasses. + *

If {@code inheritInitializers} is set to {@code false}, the initializers + * for the annotated test class will shadow and effectively replace + * any initializers defined by superclasses. *

In the following example, the * {@link org.springframework.context.ApplicationContext ApplicationContext} * for {@code ExtendedTest} will be initialized using @@ -252,9 +259,9 @@ public @interface ContextConfiguration { * for loading an {@link org.springframework.context.ApplicationContext * ApplicationContext}. *

If not specified, the loader will be inherited from the first superclass - * that is annotated with {@code @ContextConfiguration} and specifies an - * explicit loader. If no class in the hierarchy specifies an explicit - * loader, a default loader will be used instead. + * that is annotated or meta-annotated with {@code @ContextConfiguration} and + * specifies an explicit loader. If no class in the hierarchy specifies an + * explicit loader, a default loader will be used instead. *

The default concrete implementation chosen at runtime will be either * {@link org.springframework.test.context.support.DelegatingSmartContextLoader * DelegatingSmartContextLoader} or diff --git a/spring-test/src/main/java/org/springframework/test/context/support/AnnotationConfigContextLoader.java b/spring-test/src/main/java/org/springframework/test/context/support/AnnotationConfigContextLoader.java index cca1627231..7b3f043253 100644 --- a/spring-test/src/main/java/org/springframework/test/context/support/AnnotationConfigContextLoader.java +++ b/spring-test/src/main/java/org/springframework/test/context/support/AnnotationConfigContextLoader.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. @@ -28,13 +28,13 @@ import org.springframework.util.ObjectUtils; /** * Concrete implementation of {@link AbstractGenericContextLoader} that loads - * bean definitions from annotated classes. + * bean definitions from component classes. * *

See the Javadoc for * {@link org.springframework.test.context.ContextConfiguration @ContextConfiguration} - * for a definition of annotated class. + * for a definition of component class. * - *

Note: {@code AnnotationConfigContextLoader} supports annotated classes + *

Note: {@code AnnotationConfigContextLoader} supports component classes * rather than the String-based resource locations defined by the legacy * {@link org.springframework.test.context.ContextLoader ContextLoader} API. Thus, * although {@code AnnotationConfigContextLoader} extends @@ -61,8 +61,8 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader // SmartContextLoader /** - * Process annotated classes in the supplied {@link ContextConfigurationAttributes}. - *

If the annotated classes are {@code null} or empty and + * Process component classes in the supplied {@link ContextConfigurationAttributes}. + *

If the component classes are {@code null} or empty and * {@link #isGenerateDefaultLocations()} returns {@code true}, this * {@code SmartContextLoader} will attempt to {@link * #detectDefaultConfigurationClasses detect default configuration classes}. @@ -167,23 +167,23 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader /** * Register classes in the supplied {@link GenericApplicationContext context} * from the classes in the supplied {@link MergedContextConfiguration}. - *

Each class must represent an annotated class. An + *

Each class must represent a component class. An * {@link AnnotatedBeanDefinitionReader} is used to register the appropriate * bean definitions. *

Note that this method does not call {@link #createBeanDefinitionReader} * since {@code AnnotatedBeanDefinitionReader} is not an instance of * {@link BeanDefinitionReader}. - * @param context the context in which the annotated classes should be registered + * @param context the context in which the component classes should be registered * @param mergedConfig the merged configuration from which the classes should be retrieved * @see AbstractGenericContextLoader#loadBeanDefinitions */ @Override protected void loadBeanDefinitions(GenericApplicationContext context, MergedContextConfiguration mergedConfig) { - Class[] annotatedClasses = mergedConfig.getClasses(); + Class[] componentClasses = mergedConfig.getClasses(); if (logger.isDebugEnabled()) { - logger.debug("Registering annotated classes: " + ObjectUtils.nullSafeToString(annotatedClasses)); + logger.debug("Registering component classes: " + ObjectUtils.nullSafeToString(componentClasses)); } - new AnnotatedBeanDefinitionReader(context).register(annotatedClasses); + new AnnotatedBeanDefinitionReader(context).register(componentClasses); } /** diff --git a/spring-test/src/main/java/org/springframework/test/context/support/AnnotationConfigContextLoaderUtils.java b/spring-test/src/main/java/org/springframework/test/context/support/AnnotationConfigContextLoaderUtils.java index 7f97b11587..c63512a12a 100644 --- a/spring-test/src/main/java/org/springframework/test/context/support/AnnotationConfigContextLoaderUtils.java +++ b/spring-test/src/main/java/org/springframework/test/context/support/AnnotationConfigContextLoaderUtils.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. @@ -32,7 +32,7 @@ import org.springframework.util.ClassUtils; /** * Utility methods for {@link SmartContextLoader SmartContextLoaders} that deal - * with annotated classes (e.g., {@link Configuration @Configuration} classes). + * with component classes (e.g., {@link Configuration @Configuration} classes). * * @author Sam Brannen * @since 3.2 diff --git a/spring-web/src/main/java/org/springframework/web/context/support/AnnotationConfigWebApplicationContext.java b/spring-web/src/main/java/org/springframework/web/context/support/AnnotationConfigWebApplicationContext.java index b3d1ed90cc..5de3b4352b 100644 --- a/spring-web/src/main/java/org/springframework/web/context/support/AnnotationConfigWebApplicationContext.java +++ b/spring-web/src/main/java/org/springframework/web/context/support/AnnotationConfigWebApplicationContext.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. @@ -35,12 +35,13 @@ import org.springframework.web.context.ContextLoader; /** * {@link org.springframework.web.context.WebApplicationContext WebApplicationContext} - * implementation which accepts annotated classes as input - in particular + * implementation which accepts component classes as input — in particular * {@link org.springframework.context.annotation.Configuration @Configuration}-annotated * classes, but also plain {@link org.springframework.stereotype.Component @Component} - * classes and JSR-330 compliant classes using {@code javax.inject} annotations. Allows - * for registering classes one by one (specifying class names as config location) as well - * as for classpath scanning (specifying base packages as config location). + * classes and JSR-330 compliant classes using {@code javax.inject} annotations. + * + *

Allows for registering classes one by one (specifying class names as config + * location) as well as for classpath scanning (specifying base packages as config location). * *

This is essentially the equivalent of * {@link org.springframework.context.annotation.AnnotationConfigApplicationContext @@ -53,7 +54,7 @@ import org.springframework.web.context.ContextLoader; * *

As of Spring 3.1, this class may also be directly instantiated and injected into * Spring's {@code DispatcherServlet} or {@code ContextLoaderListener} when using the - * new {@link org.springframework.web.WebApplicationInitializer WebApplicationInitializer} + * {@link org.springframework.web.WebApplicationInitializer WebApplicationInitializer} * code-based alternative to {@code web.xml}. See its Javadoc for details and usage examples. * *

Unlike {@link XmlWebApplicationContext}, no default configuration class locations @@ -74,7 +75,8 @@ import org.springframework.web.context.ContextLoader; * *

Note: In case of multiple {@code @Configuration} classes, later {@code @Bean} * definitions will override ones defined in earlier loaded files. This can be leveraged - * to deliberately override certain bean definitions via an extra Configuration class. + * to deliberately override certain bean definitions via an extra {@code @Configuration} + * class. * * @author Chris Beams * @author Juergen Hoeller @@ -90,7 +92,7 @@ public class AnnotationConfigWebApplicationContext extends AbstractRefreshableWe @Nullable private ScopeMetadataResolver scopeMetadataResolver; - private final Set> annotatedClasses = new LinkedHashSet<>(); + private final Set> componentClasses = new LinkedHashSet<>(); private final Set basePackages = new LinkedHashSet<>(); @@ -137,10 +139,10 @@ public class AnnotationConfigWebApplicationContext extends AbstractRefreshableWe /** - * Register one or more annotated classes to be processed. + * Register one or more component classes to be processed. *

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, + * @param componentClasses one or more component classes, * e.g. {@link org.springframework.context.annotation.Configuration @Configuration} classes * @see #scan(String...) * @see #loadBeanDefinitions(DefaultListableBeanFactory) @@ -148,16 +150,16 @@ public class AnnotationConfigWebApplicationContext extends AbstractRefreshableWe * @see #refresh() */ @Override - public void register(Class... annotatedClasses) { - Assert.notEmpty(annotatedClasses, "At least one annotated class must be specified"); - Collections.addAll(this.annotatedClasses, annotatedClasses); + public void register(Class... componentClasses) { + Assert.notEmpty(componentClasses, "At least one component class must be specified"); + Collections.addAll(this.componentClasses, componentClasses); } /** * Perform a scan within the specified base packages. *

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 check for component classes * @see #loadBeanDefinitions(DefaultListableBeanFactory) * @see #register(Class...) * @see #setConfigLocation(String) @@ -178,7 +180,7 @@ public class AnnotationConfigWebApplicationContext extends AbstractRefreshableWe * {@link #setConfigLocations(String[])}, attempt first to load each location as a * class, registering a {@code BeanDefinition} if class loading is successful, * and if class loading fails (i.e. a {@code ClassNotFoundException} is raised), - * assume the value is a package and attempt to scan it for annotated classes. + * assume the value is a package and attempt to scan it for component classes. *

Enables the default set of annotation configuration post processors, such that * {@code @Autowired}, {@code @Required}, and associated annotations can be used. *

Configuration class bean definitions are registered with generated bean @@ -210,12 +212,12 @@ public class AnnotationConfigWebApplicationContext extends AbstractRefreshableWe scanner.setScopeMetadataResolver(scopeMetadataResolver); } - if (!this.annotatedClasses.isEmpty()) { + if (!this.componentClasses.isEmpty()) { if (logger.isDebugEnabled()) { - logger.debug("Registering annotated classes: [" + - StringUtils.collectionToCommaDelimitedString(this.annotatedClasses) + "]"); + logger.debug("Registering component classes: [" + + StringUtils.collectionToCommaDelimitedString(this.componentClasses) + "]"); } - reader.register(ClassUtils.toClassArray(this.annotatedClasses)); + reader.register(ClassUtils.toClassArray(this.componentClasses)); } if (!this.basePackages.isEmpty()) { @@ -243,7 +245,7 @@ public class AnnotationConfigWebApplicationContext extends AbstractRefreshableWe } int count = scanner.scan(configLocation); if (count == 0 && logger.isDebugEnabled()) { - logger.debug("No annotated classes found for specified class/package [" + configLocation + "]"); + logger.debug("No component classes found for specified class/package [" + configLocation + "]"); } } } diff --git a/src/docs/asciidoc/core/core-beans.adoc b/src/docs/asciidoc/core/core-beans.adoc index 06300027ab..b4c743f859 100644 --- a/src/docs/asciidoc/core/core-beans.adoc +++ b/src/docs/asciidoc/core/core-beans.adoc @@ -8743,7 +8743,7 @@ This approach simplifies container instantiation, as only one class needs to be with, rather than requiring you to remember a potentially large number of `@Configuration` classes during construction. -TIP: As of Spring Framework 4.2, `@Import` also supports references regular component +TIP: As of Spring Framework 4.2, `@Import` also supports references to regular component classes, analogous to the `AnnotationConfigApplicationContext.register` method. This is particularly useful if you want to avoid component scanning, by using a few configuration classes as entry points to explicitly define all your components. diff --git a/src/docs/asciidoc/testing.adoc b/src/docs/asciidoc/testing.adoc index 759fec9212..1383024095 100644 --- a/src/docs/asciidoc/testing.adoc +++ b/src/docs/asciidoc/testing.adoc @@ -258,7 +258,7 @@ load the mapping files, and incurring that cost before running every test in eve fixture leads to slower overall test runs that reduce developer productivity. Test classes typically declare either an array of resource locations for XML or Groovy -configuration metadata -- often in the classpath -- or an array of annotated classes that +configuration metadata -- often in the classpath -- or an array of component classes that is used to configure the application. These locations or classes are the same as or similar to those specified in `web.xml` or other configuration files for production deployments. @@ -436,12 +436,13 @@ specify a custom `TestContextBootstrapper`. See the section on `@ContextConfiguration` defines class-level metadata that is used to determine how to load and configure an `ApplicationContext` for integration tests. Specifically, `@ContextConfiguration` declares the application context resource `locations` or the -annotated `classes` used to load the context. +component `classes` used to load the context. Resource locations are typically XML configuration files or Groovy scripts located in the -classpath, while annotated classes are typically `@Configuration` classes. However, -resource locations can also refer to files and scripts in the file system, and annotated -classes can be component classes, and so on. +classpath, while component classes are typically `@Configuration` classes. However, +resource locations can also refer to files and scripts in the file system, and component +classes can be `@Component` classes, `@Service` classes, and so on. See +<> for further details. The following example shows a `@ContextConfiguration` annotation that refers to an XML file: @@ -490,7 +491,7 @@ The following example shows a `@ContextConfiguration` annotation that refers to <1> Referring to a class. -As an alternative or in addition to declaring resource locations or annotated classes, +As an alternative or in addition to declaring resource locations or component classes, you can use `@ContextConfiguration` to declare `ApplicationContextInitializer` classes. The following example shows such a case: @@ -517,7 +518,7 @@ The following example shows such a case: You can optionally use `@ContextConfiguration` to declare the `ContextLoader` strategy as well. Note, however, that you typically do not need to explicitly configure the loader, since the default loader supports `initializers` and either resource `locations` or -annotated `classes`. +component `classes`. The following example uses both a location and a loader: @@ -1633,7 +1634,7 @@ The following annotations are supported only when used in conjunction with the `@ExtendWith(SpringExtension.class)` from JUnit Jupiter with `@ContextConfiguration` from the Spring TestContext Framework. It can be used at the class level as a drop-in replacement for `@ContextConfiguration`. With regard to configuration options, the only -difference between `@ContextConfiguration` and `@SpringJUnitConfig` is that annotated +difference between `@ContextConfiguration` and `@SpringJUnitConfig` is that component classes may be declared with the `value` attribute in `@SpringJUnitConfig`. The following example shows how to use the `@SpringJUnitConfig` annotation to specify a @@ -1696,7 +1697,7 @@ and `@ContextConfiguration` for further details. `@WebAppConfiguration` from the Spring TestContext Framework. You can use it at the class level as a drop-in replacement for `@ContextConfiguration` and `@WebAppConfiguration`. With regard to configuration options, the only difference between `@ContextConfiguration` -and `@SpringJUnitWebConfig` is that you can declare annotated classes by using the +and `@SpringJUnitWebConfig` is that you can declare component classes by using the `value` attribute in `@SpringJUnitWebConfig`. In addition, you can override the `value` attribute from `@WebAppConfiguration` only by using the `resourcePath` attribute in `@SpringJUnitWebConfig`. @@ -2215,13 +2216,13 @@ the `TestContextManager` with which the listener is registered. See <>), you can annotate your test class with `@ContextConfiguration` and configure the `classes` attribute with an array -that contains references to annotated classes. The following example shows how to do so: +that contains references to component classes. The following example shows how to do so: [source,java,indent=0,subs="verbatim,quotes",role="primary"] .Java @@ -2845,7 +2846,7 @@ that contains references to annotated classes. The following example shows how t // class body... } ---- -<1> Specifying annotated classes. +<1> Specifying component classes. [source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"] .Kotlin @@ -2857,23 +2858,27 @@ that contains references to annotated classes. The following example shows how t // class body... } ---- -<1> Specifying annotated classes. +<1> Specifying component classes. -.Annotated Classes +[[testcontext-ctx-management-javaconfig-component-classes]] +.Component Classes [TIP] ==== -The term "`annotated class`" can refer to any of the following: +The term "`component class`" can refer to any of the following: * A class annotated with `@Configuration`. * A component (that is, a class annotated with `@Component`, `@Service`, `@Repository`, or other stereotype annotations). * A JSR-330 compliant class that is annotated with `javax.inject` annotations. -* Any other class that contains `@Bean` methods. +* Any class that contains `@Bean`-methods. +* Any other class that is intended to be registered as a Spring component (i.e., a Spring + bean in the `ApplicationContext`), potentially taking advantage of automatic autowiring + of a single constructor without the use of Spring annotations. See the javadoc of {api-spring-framework}/context/annotation/Configuration.html[`@Configuration`] and {api-spring-framework}/context/annotation/Bean.html[`@Bean`] for further information -regarding the configuration and semantics of annotated classes, paying special attention +regarding the configuration and semantics of component classes, paying special attention to the discussion of `@Bean` Lite Mode. ==== @@ -2952,10 +2957,10 @@ class: [[testcontext-ctx-management-mixed-config]] -===== Mixing XML, Groovy Scripts, and Annotated Classes +===== Mixing XML, Groovy Scripts, and Component Classes It may sometimes be desirable to mix XML configuration files, Groovy scripts, and -annotated classes (typically `@Configuration` classes) to configure an +component classes (typically `@Configuration` classes) to configure an `ApplicationContext` for your tests. For example, if you use XML configuration in production, you may decide that you want to use `@Configuration` classes to configure specific Spring-managed components for your tests, or vice versa. @@ -3031,7 +3036,7 @@ order in which the initializers are invoked depends on whether they implement Sp You can also omit the declaration of XML configuration files, Groovy scripts, or -annotated classes in `@ContextConfiguration` entirely and instead declare only +component classes in `@ContextConfiguration` entirely and instead declare only `ApplicationContextInitializer` classes, which are then responsible for registering beans in the context -- for example, by programmatically loading bean definitions from XML files or configuration classes. The following example shows how to do so: @@ -3067,18 +3072,18 @@ files or configuration classes. The following example shows how to do so: ===== Context Configuration Inheritance `@ContextConfiguration` supports boolean `inheritLocations` and `inheritInitializers` -attributes that denote whether resource locations or annotated classes and context +attributes that denote whether resource locations or component classes and context initializers declared by superclasses should be inherited. The default value for both flags is `true`. This means that a test class inherits the resource locations or -annotated classes as well as the context initializers declared by any superclasses. -Specifically, the resource locations or annotated classes for a test class are appended +component classes as well as the context initializers declared by any superclasses. +Specifically, the resource locations or component classes for a test class are appended to the list of resource locations or annotated classes declared by superclasses. Similarly, the initializers for a given test class are added to the set of initializers defined by test superclasses. Thus, subclasses have the option of extending the resource -locations, annotated classes, or context initializers. +locations, component classes, or context initializers. If the `inheritLocations` or `inheritInitializers` attribute in `@ContextConfiguration` -is set to `false`, the resource locations or annotated classes and the context +is set to `false`, the resource locations or component classes and the context initializers, respectively, for the test class shadow and effectively replace the configuration defined by superclasses. @@ -3131,7 +3136,7 @@ another and use both its own configuration file and the superclass's configurati <2> Configuration file defined in the subclass. -Similarly, in the next example, which uses annotated classes, the `ApplicationContext` +Similarly, in the next example, which uses component classes, the `ApplicationContext` for `ExtendedTest` is loaded from the `BaseConfig` and `ExtendedConfig` classes, in that order. Beans defined in `ExtendedConfig` can, therefore, override (that is, replace) those defined in `BaseConfig`. The following example shows how one class can extend @@ -4027,7 +4032,7 @@ framework's support for convention over configuration: If you annotate a test class with `@WebAppConfiguration` without specifying a resource base path, the resource path effectively defaults to `file:src/main/webapp`. Similarly, -if you declare `@ContextConfiguration` without specifying resource `locations`, annotated +if you declare `@ContextConfiguration` without specifying resource `locations`, component `classes`, or context `initializers`, Spring tries to detect the presence of your configuration by using conventions (that is, `WacTests-context.xml` in the same package as the `WacTests` class or static nested `@Configuration` classes). @@ -4280,7 +4285,7 @@ either on an individual test class or within a test class hierarchy. If a contex hierarchy is declared on multiple classes within a test class hierarchy, you can also merge or override the context configuration for a specific, named level in the context hierarchy. When merging configuration for a given level in the hierarchy, the -configuration resource type (that is, XML configuration files or annotated classes) must +configuration resource type (that is, XML configuration files or component classes) must be consistent. Otherwise, it is perfectly acceptable to have different levels in a context hierarchy configured using different resource types.