Merge branch '5.3.x'

spring-web/src/main/java/org/springframework/web/context/support/AnnotationConfigWebApplicationContext.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2022 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.
@@ -36,16 +36,27 @@ import org.springframework.web.context.ContextLoader;
 /**
  * {@link org.springframework.web.context.WebApplicationContext WebApplicationContext}
  * implementation which accepts <em>component classes</em> as input &mdash; in particular
- * {@link org.springframework.context.annotation.Configuration @Configuration}-annotated
+ * {@link org.springframework.context.annotation.Configuration @Configuration}
  * classes, but also plain {@link org.springframework.stereotype.Component @Component}
- * classes and JSR-330 compliant classes using {@code jakarta.inject} annotations.
+ * classes as well as JSR-330 compliant classes using {@code jakarta.inject} annotations.
  *
  * <p>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).
+ * locations) as well as via classpath scanning (specifying base packages as config
+ * locations).
  *
  * <p>This is essentially the equivalent of
  * {@link org.springframework.context.annotation.AnnotationConfigApplicationContext
- * AnnotationConfigApplicationContext} for a web environment.
+ * AnnotationConfigApplicationContext} for a web environment. However, in contrast to
+ * {@code AnnotationConfigApplicationContext}, this class does not extend
+ * {@link org.springframework.context.support.GenericApplicationContext
+ * GenericApplicationContext} and therefore does not provide some of the convenient
+ * {@code registerBean(...)} methods available in a {@code GenericApplicationContext}.
+ * If you wish to register annotated <em>component classes</em> with a
+ * {@code GenericApplicationContext} in a web environment, you may use a
+ * {@code GenericWebApplicationContext} with an
+ * {@link org.springframework.context.annotation.AnnotatedBeanDefinitionReader
+ * AnnotatedBeanDefinitionReader}. See the Javadoc for {@link GenericWebApplicationContext}
+ * for details and an example.
  *
  * <p>To make use of this application context, the
  * {@linkplain ContextLoader#CONTEXT_CLASS_PARAM "contextClass"} context-param for
@@ -80,8 +91,10 @@ import org.springframework.web.context.ContextLoader;
  *
  * @author Chris Beams
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 3.0
  * @see org.springframework.context.annotation.AnnotationConfigApplicationContext
+ * @see org.springframework.web.context.support.GenericWebApplicationContext
  */
 public class AnnotationConfigWebApplicationContext extends AbstractRefreshableWebApplicationContext
 		implements AnnotationConfigRegistry {

spring-web/src/main/java/org/springframework/web/context/support/GenericWebApplicationContext.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2022 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.
@@ -39,26 +39,42 @@ import org.springframework.web.context.ServletContextAware;
 /**
  * Subclass of {@link GenericApplicationContext}, suitable for web environments.
  *
- * <p>Implements {@link org.springframework.web.context.ConfigurableWebApplicationContext},
- * but is not intended for declarative setup in {@code web.xml}. Instead, it is designed
- * for programmatic setup, for example for building nested contexts or for use within
+ * <p>Implements {@link ConfigurableWebApplicationContext}, but is not intended for
+ * declarative setup in {@code web.xml}. Instead, it is designed for programmatic setup,
+ * for example for building nested contexts or for use within
  * {@link org.springframework.web.WebApplicationInitializer WebApplicationInitializers}.
  *
- * <p><b>If you intend to implement a WebApplicationContext that reads bean definitions
- * from configuration files, consider deriving from AbstractRefreshableWebApplicationContext,
- * reading the bean definitions in an implementation of the {@code loadBeanDefinitions}
- * method.</b>
- *
  * <p>Interprets resource paths as servlet context resources, i.e. as paths beneath
- * the web application root. Absolute paths, e.g. for files outside the web app root,
- * can be accessed via "file:" URLs, as implemented by AbstractApplicationContext.
+ * the web application root. Absolute paths &mdash; for example, for files outside
+ * the web app root &mdash; can be accessed via {@code file:} URLs, as implemented
+ * by {@code AbstractApplicationContext}.
  *
  * <p>In addition to the special beans detected by
- * {@link org.springframework.context.support.AbstractApplicationContext},
- * this class detects a ThemeSource bean in the context, with the name "themeSource".
+ * {@link org.springframework.context.support.AbstractApplicationContext AbstractApplicationContext},
+ * this class detects a {@link ThemeSource} bean in the context, with the name "themeSource".
+ *
+ * <p>If you wish to register annotated <em>component classes</em> with a
+ * {@code GenericWebApplicationContext}, you can use an
+ * {@link org.springframework.context.annotation.AnnotatedBeanDefinitionReader
+ * AnnotatedBeanDefinitionReader}, as demonstrated in the following example.
+ * Component classes include in particular
+ * {@link org.springframework.context.annotation.Configuration @Configuration}
+ * classes but also plain {@link org.springframework.stereotype.Component @Component}
+ * classes as well as JSR-330 compliant classes using {@code jakarta.inject} annotations.
+ *
+ * <pre class="code">
+ * GenericWebApplicationContext context = new GenericWebApplicationContext();
+ * AnnotatedBeanDefinitionReader reader = new AnnotatedBeanDefinitionReader(context);
+ * reader.register(AppConfig.class, UserController.class, UserRepository.class);</pre>
+ *
+ * <p>If you intend to implement a {@code WebApplicationContext} that reads bean definitions
+ * from configuration files, consider deriving from {@link AbstractRefreshableWebApplicationContext},
+ * reading the bean definitions in an implementation of the {@code loadBeanDefinitions}
+ * method.
  *
  * @author Juergen Hoeller
  * @author Chris Beams
+ * @author Sam Brannen
  * @since 1.2
  */
 public class GenericWebApplicationContext extends GenericApplicationContext
@@ -72,7 +88,7 @@ public class GenericWebApplicationContext extends GenericApplicationContext
 
 
 	/**
-	 * Create a new GenericWebApplicationContext.
+	 * Create a new {@code GenericWebApplicationContext}.
 	 * @see #setServletContext
 	 * @see #registerBeanDefinition
 	 * @see #refresh
@@ -82,8 +98,8 @@ public class GenericWebApplicationContext extends GenericApplicationContext
 	}
 
 	/**
-	 * Create a new GenericWebApplicationContext for the given ServletContext.
-	 * @param servletContext the ServletContext to run in
+	 * Create a new {@code GenericWebApplicationContext} for the given {@link ServletContext}.
+	 * @param servletContext the {@code ServletContext} to run in
 	 * @see #registerBeanDefinition
 	 * @see #refresh
 	 */
@@ -92,8 +108,8 @@ public class GenericWebApplicationContext extends GenericApplicationContext
 	}
 
 	/**
-	 * Create a new GenericWebApplicationContext with the given DefaultListableBeanFactory.
-	 * @param beanFactory the DefaultListableBeanFactory instance to use for this context
+	 * Create a new {@code GenericWebApplicationContext} with the given {@link DefaultListableBeanFactory}.
+	 * @param beanFactory the {@code DefaultListableBeanFactory} instance to use for this context
 	 * @see #setServletContext
 	 * @see #registerBeanDefinition
 	 * @see #refresh
@@ -103,9 +119,10 @@ public class GenericWebApplicationContext extends GenericApplicationContext
 	}
 
 	/**
-	 * Create a new GenericWebApplicationContext with the given DefaultListableBeanFactory.
-	 * @param beanFactory the DefaultListableBeanFactory instance to use for this context
-	 * @param servletContext the ServletContext to run in
+	 * Create a new {@code GenericWebApplicationContext} with the given {@link DefaultListableBeanFactory}
+	 * and {@link ServletContext}.
+	 * @param beanFactory the {@code DefaultListableBeanFactory} instance to use for this context
+	 * @param servletContext the {@code ServletContext} to run in
 	 * @see #registerBeanDefinition
 	 * @see #refresh
 	 */
@@ -116,7 +133,7 @@ public class GenericWebApplicationContext extends GenericApplicationContext
 
 
 	/**
-	 * Set the ServletContext that this WebApplicationContext runs in.
+	 * Set the {@link ServletContext} that this {@code WebApplicationContext} runs in.
 	 */
 	@Override
 	public void setServletContext(@Nullable ServletContext servletContext) {
@@ -143,8 +160,7 @@ public class GenericWebApplicationContext extends GenericApplicationContext
 	}
 
 	/**
-	 * Register ServletContextAwareProcessor.
-	 * @see ServletContextAwareProcessor
+	 * Register request/session scopes, environment beans, a {@link ServletContextAwareProcessor}, etc.
 	 */
 	@Override
 	protected void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) {
@@ -157,7 +173,7 @@ public class GenericWebApplicationContext extends GenericApplicationContext
 	}
 
 	/**
-	 * This implementation supports file paths beneath the root of the ServletContext.
+	 * This implementation supports file paths beneath the root of the {@link ServletContext}.
 	 * @see ServletContextResource
 	 */
 	@Override
@@ -236,7 +252,7 @@ public class GenericWebApplicationContext extends GenericApplicationContext
 		if (StringUtils.hasText(configLocation)) {
 			throw new UnsupportedOperationException(
 					"GenericWebApplicationContext does not support setConfigLocation(). " +
-					"Do you still have an 'contextConfigLocations' init-param set?");
+					"Do you still have a 'contextConfigLocation' init-param set?");
 		}
 	}
 
@@ -245,7 +261,7 @@ public class GenericWebApplicationContext extends GenericApplicationContext
 		if (!ObjectUtils.isEmpty(configLocations)) {
 			throw new UnsupportedOperationException(
 					"GenericWebApplicationContext does not support setConfigLocations(). " +
-					"Do you still have an 'contextConfigLocations' init-param set?");
+					"Do you still have a 'contextConfigLocations' init-param set?");
 		}
 	}
 

src/docs/asciidoc/core/core-beans.adoc

@@ -7900,6 +7900,10 @@ init-param):
 	</web-app>
 ----
 
+NOTE: For programmatic use cases, a `GenericWebApplicationContext` can be used as an
+alternative to `AnnotationConfigWebApplicationContext`. See the
+{api-spring-framework}/web/context/support/GenericWebApplicationContext.html[`GenericWebApplicationContext`]
+javadoc for details.
 
 
 [[beans-java-bean-annotation]]

src/docs/asciidoc/web/webmvc.adoc

@@ -84,6 +84,11 @@ NOTE: In addition to using the ServletContext API directly, you can also extend
 `AbstractAnnotationConfigDispatcherServletInitializer` and override specific methods
 (see the example under <<mvc-servlet-context-hierarchy>>).
 
+NOTE: For programmatic use cases, a `GenericWebApplicationContext` can be used as an
+alternative to `AnnotationConfigWebApplicationContext`. See the
+{api-spring-framework}/web/context/support/GenericWebApplicationContext.html[`GenericWebApplicationContext`]
+javadoc for details.
+
 The following example of `web.xml` configuration registers and initializes the `DispatcherServlet`:
 
 [source,xml,indent=0,subs="verbatim,quotes"]