Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve documentation regarding "annotated classes"

Browse Source 
See gh-23638
This commit is contained in:
Sam Brannen
2019-09-25 13:29:17 +02:00
parent e9dc5160b9
commit 7d126d3288
11 changed files with 202 additions and 183 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -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.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.
*
* <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 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.
* <p>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.
* <p>The default is a {@link AnnotationBeanNameGenerator}.
*/
public void setBeanNameGenerator(@Nullable BeanNameGenerator beanNameGenerator) {
@@ -114,7 +115,7 @@ public class AnnotatedBeanDefinitionReader {
}
/**
* 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 class AnnotatedBeanDefinitionReader {
/**
* 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 class AnnotatedBeanDefinitionReader {
* 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;
}

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

@@ -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.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 <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 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 &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 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.
* <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 class AnnotationConfigApplicationContext extends GenericApplicationContex
//---------------------------------------------------------------------
/**
* 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,15 +184,15 @@ public class AnnotationConfigApplicationContext extends GenericApplicationContex
* 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);
}
/**
@@ -196,15 +200,15 @@ public class AnnotationConfigApplicationContext extends GenericApplicationContex
* 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);

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

@@ -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.
* <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);

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

@@ -352,7 +352,8 @@ import org.springframework.stereotype.Component;
*
* <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)

9
spring-context/src/main/java/org/springframework/context/annotation/Import.java
View File

@@ -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 <em>component classes</em> to import &mdash; typically
* {@link Configuration @Configuration} classes.
*
* <p>Provides functionality equivalent to the {@code <import/>} element in Spring XML.
* Allows for importing {@code @Configuration} classes, {@link ImportSelector} and
@@ -54,8 +55,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();