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 78c60e9bf5..1c46076587 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 @@ -23,10 +23,12 @@ import java.util.List; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; import org.springframework.context.annotation.Configuration; +import org.springframework.test.context.SmartContextLoader; import org.springframework.util.Assert; /** - * TODO [SPR-9864] Document AnnotationConfigContextLoaderUtils. + * Utility methods for {@link SmartContextLoader SmartContextLoaders} that deal + * with annotated classes (e.g., {@link Configuration @Configuration} classes). * * @author Sam Brannen * @since 3.2 diff --git a/spring-test/src/main/java/org/springframework/test/context/web/AbstractGenericWebContextLoader.java b/spring-test/src/main/java/org/springframework/test/context/web/AbstractGenericWebContextLoader.java index 42bdc7ee46..8b02eb4c32 100644 --- a/spring-test/src/main/java/org/springframework/test/context/web/AbstractGenericWebContextLoader.java +++ b/spring-test/src/main/java/org/springframework/test/context/web/AbstractGenericWebContextLoader.java @@ -20,6 +20,7 @@ import javax.servlet.ServletContext; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; + import org.springframework.beans.factory.support.DefaultListableBeanFactory; import org.springframework.context.ApplicationContext; import org.springframework.context.ConfigurableApplicationContext; @@ -34,10 +35,26 @@ import org.springframework.web.context.WebApplicationContext; import org.springframework.web.context.support.GenericWebApplicationContext; /** - * TODO [SPR-9864] Document AbstractGenericWebContextLoader. + * Abstract, generic extension of {@link AbstractContextLoader} that loads a + * {@link GenericWebApplicationContext}. + * + *
If instances of concrete subclasses are invoked via the + * {@link org.springframework.test.context.SmartContextLoader SmartContextLoader} + * SPI, the context will be loaded from the {@link MergedContextConfiguration} + * provided to {@link #loadContext(MergedContextConfiguration)}. In such cases, a + * {@code SmartContextLoader} will decide whether to load the context from + * locations or annotated classes. Note that {@code + * AbstractGenericWebContextLoader} does not support the {@code + * loadContext(String... locations)} method from the legacy + * {@link org.springframework.test.context.ContextLoader ContextLoader} SPI. + * + *
Concrete subclasses must provide an appropriate implementation of + * {@link #loadBeanDefinitions()}. * * @author Sam Brannen * @since 3.2 + * @see #loadContext(MergedContextConfiguration) + * @see #loadContext(String...) */ public abstract class AbstractGenericWebContextLoader extends AbstractContextLoader { @@ -47,9 +64,33 @@ public abstract class AbstractGenericWebContextLoader extends AbstractContextLoa // --- SmartContextLoader ----------------------------------------------- /** - * TODO [SPR-9864] Document overridden loadContext(MergedContextConfiguration). + * Load a Spring {@link WebApplicationContext} from the supplied + * {@link MergedContextConfiguration}. * - * @see org.springframework.test.context.SmartContextLoader#loadContext(org.springframework.test.context.MergedContextConfiguration) + *
Implementation details: + * + *
Implementation details: + * + *
The default implementation is empty but can be overridden in subclasses
+ * to customize DefaultListableBeanFactory's standard settings.
+ *
+ * @param beanFactory the bean factory created by this context loader
+ * @param webMergedConfig the merged context configuration to use to load the
+ * web application context
+ * @see #loadContext(MergedContextConfiguration)
+ * @see DefaultListableBeanFactory#setAllowBeanDefinitionOverriding
+ * @see DefaultListableBeanFactory#setAllowEagerClassLoading
+ * @see DefaultListableBeanFactory#setAllowCircularReferences
+ * @see DefaultListableBeanFactory#setAllowRawInjectionDespiteWrapping
*/
protected void customizeBeanFactory(DefaultListableBeanFactory beanFactory,
WebMergedContextConfiguration webMergedConfig) {
}
/**
- * TODO [SPR-9864] Document loadBeanDefinitions().
+ * Load bean definitions into the supplied {@link GenericWebApplicationContext context}
+ * from the locations or classes in the supplied WebMergedContextConfiguration.
+ *
+ *
Concrete subclasses must provide an appropriate implementation. + * + * @param context the context into which the bean definitions should be loaded + * @param webMergedConfig the merged context configuration to use to load the + * web application context + * @see #loadContext(MergedContextConfiguration) */ protected abstract void loadBeanDefinitions(GenericWebApplicationContext context, WebMergedContextConfiguration webMergedConfig); /** - * TODO [SPR-9864] Document customizeContext(). + * Customize the {@link GenericWebApplicationContext} created by this context + * loader after bean definitions have been loaded into the context but + * before the context is refreshed. + * + *
The default implementation is empty but can be overridden in subclasses + * to customize the web application context. + * + * @param context the newly created web application context + * @param webMergedConfig the merged context configuration to use to load the + * web application context + * @see #loadContext(MergedContextConfiguration) */ protected void customizeContext(GenericWebApplicationContext context, WebMergedContextConfiguration webMergedConfig) { } @@ -114,9 +208,13 @@ public abstract class AbstractGenericWebContextLoader extends AbstractContextLoa // --- ContextLoader ------------------------------------------------------- /** - * TODO [SPR-9864] Document overridden loadContext(String...). + * {@code AbstractGenericWebContextLoader} should be used as a + * {@link org.springframework.test.context.SmartContextLoader SmartContextLoader}, + * not as a legacy {@link org.springframework.test.context.ContextLoader ContextLoader}. + * Consequently, this method is not supported. * * @see org.springframework.test.context.ContextLoader#loadContext(java.lang.String[]) + * @throws UnsupportedOperationException */ public final ApplicationContext loadContext(String... locations) throws Exception { throw new UnsupportedOperationException( diff --git a/spring-test/src/main/java/org/springframework/test/context/web/AnnotationConfigWebContextLoader.java b/spring-test/src/main/java/org/springframework/test/context/web/AnnotationConfigWebContextLoader.java index 71621b1ea8..05cc92cd93 100644 --- a/spring-test/src/main/java/org/springframework/test/context/web/AnnotationConfigWebContextLoader.java +++ b/spring-test/src/main/java/org/springframework/test/context/web/AnnotationConfigWebContextLoader.java @@ -18,18 +18,38 @@ package org.springframework.test.context.web; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; + import org.springframework.context.annotation.AnnotatedBeanDefinitionReader; import org.springframework.test.context.ContextConfigurationAttributes; -import org.springframework.test.context.support.AbstractContextLoader; import org.springframework.test.context.support.AnnotationConfigContextLoaderUtils; import org.springframework.util.ObjectUtils; import org.springframework.web.context.support.GenericWebApplicationContext; /** - * TODO [SPR-9864] Document AnnotationConfigWebContextLoader. + * Concrete implementation of {@link AbstractGenericWebContextLoader} that loads + * bean definitions from annotated classes. + * + *
See the Javadoc for + * {@link org.springframework.test.context.ContextConfiguration @ContextConfiguration} + * for a definition of annotated class. + * + *
Note: AnnotationConfigWebContextLoader supports annotated classes
+ * rather than the String-based resource locations defined by the legacy
+ * {@link org.springframework.test.context.ContextLoader ContextLoader} API. Thus,
+ * although AnnotationConfigWebContextLoader extends
+ * AbstractGenericWebContextLoader, AnnotationConfigWebContextLoader
+ * does not support any String-based methods defined by
+ * {@link org.springframework.test.context.support.AbstractContextLoader
+ * AbstractContextLoader} or AbstractGenericWebContextLoader.
+ * Consequently, AnnotationConfigWebContextLoader should chiefly be
+ * considered a {@link org.springframework.test.context.SmartContextLoader SmartContextLoader}
+ * rather than a {@link org.springframework.test.context.ContextLoader ContextLoader}.
*
* @author Sam Brannen
* @since 3.2
+ * @see #processContextConfiguration(ContextConfigurationAttributes)
+ * @see #detectDefaultConfigurationClasses(Class)
+ * @see #loadBeanDefinitions(GenericWebApplicationContext, WebMergedContextConfiguration)
*/
public class AnnotationConfigWebContextLoader extends AbstractGenericWebContextLoader {
@@ -43,10 +63,10 @@ public class AnnotationConfigWebContextLoader extends AbstractGenericWebContextL
*
*
If the annotated classes are null or empty and
* {@link #isGenerateDefaultLocations()} returns true, this
- * SmartContextLoader will attempt to {@link
+ * SmartContextLoader will attempt to {@linkplain
* #detectDefaultConfigurationClasses detect default configuration classes}.
* If defaults are detected they will be
- * {@link ContextConfigurationAttributes#setClasses(Class[]) set} in the
+ * {@linkplain ContextConfigurationAttributes#setClasses(Class[]) set} in the
* supplied configuration attributes. Otherwise, properties in the supplied
* configuration attributes will not be modified.
*
@@ -85,7 +105,7 @@ public class AnnotationConfigWebContextLoader extends AbstractGenericWebContextL
* not as a legacy {@link org.springframework.test.context.ContextLoader ContextLoader}.
* Consequently, this method is not supported.
*
- * @see AbstractContextLoader#modifyLocations
+ * @see org.springframework.test.context.support.AbstractContextLoader#modifyLocations
* @throws UnsupportedOperationException
*/
@Override
@@ -100,7 +120,7 @@ public class AnnotationConfigWebContextLoader extends AbstractGenericWebContextL
* not as a legacy {@link org.springframework.test.context.ContextLoader ContextLoader}.
* Consequently, this method is not supported.
*
- * @see AbstractContextLoader#generateDefaultLocations
+ * @see org.springframework.test.context.support.AbstractContextLoader#generateDefaultLocations
* @throws UnsupportedOperationException
*/
@Override
@@ -115,7 +135,7 @@ public class AnnotationConfigWebContextLoader extends AbstractGenericWebContextL
* not as a legacy {@link org.springframework.test.context.ContextLoader ContextLoader}.
* Consequently, this method is not supported.
*
- * @see AbstractContextLoader#getResourceSuffix
+ * @see org.springframework.test.context.support.AbstractContextLoader#getResourceSuffix
* @throws UnsupportedOperationException
*/
@Override
@@ -127,7 +147,7 @@ public class AnnotationConfigWebContextLoader extends AbstractGenericWebContextL
// --- AbstractGenericWebContextLoader -------------------------------------
/**
- * Register classes in the supplied {@link GenericWebApplicationContext context}
+ * Register classes in the supplied {@linkplain GenericWebApplicationContext context}
* from the classes in the supplied {@link WebMergedContextConfiguration}.
*
*
Each class must represent an annotated class. An diff --git a/spring-test/src/main/java/org/springframework/test/context/web/GenericXmlWebContextLoader.java b/spring-test/src/main/java/org/springframework/test/context/web/GenericXmlWebContextLoader.java index 23146df624..b3c9c2dabd 100644 --- a/spring-test/src/main/java/org/springframework/test/context/web/GenericXmlWebContextLoader.java +++ b/spring-test/src/main/java/org/springframework/test/context/web/GenericXmlWebContextLoader.java @@ -20,7 +20,8 @@ import org.springframework.beans.factory.xml.XmlBeanDefinitionReader; import org.springframework.web.context.support.GenericWebApplicationContext; /** - * TODO [SPR-9864] Document GenericXmlWebContextLoader. + * Concrete implementation of {@link AbstractGenericWebContextLoader} that loads + * bean definitions from XML resources. * * @author Sam Brannen * @since 3.2 @@ -28,9 +29,9 @@ import org.springframework.web.context.support.GenericWebApplicationContext; public class GenericXmlWebContextLoader extends AbstractGenericWebContextLoader { /** - * TODO [SPR-9864] Document overridden loadBeanDefinitions(). + * Loads bean definitions using an {@link XmlBeanDefinitionReader}. * - * @see org.springframework.test.context.web.AbstractGenericWebContextLoader#loadBeanDefinitions(org.springframework.web.context.support.GenericWebApplicationContext, org.springframework.test.context.web.WebMergedContextConfiguration) + * @see AbstractGenericWebContextLoader#loadBeanDefinitions() */ @Override protected void loadBeanDefinitions(GenericWebApplicationContext context, diff --git a/spring-test/src/main/java/org/springframework/test/context/web/ServletTestExecutionListener.java b/spring-test/src/main/java/org/springframework/test/context/web/ServletTestExecutionListener.java index b5f7549e8f..5a21ea0d32 100644 --- a/spring-test/src/main/java/org/springframework/test/context/web/ServletTestExecutionListener.java +++ b/spring-test/src/main/java/org/springframework/test/context/web/ServletTestExecutionListener.java @@ -20,6 +20,7 @@ import javax.servlet.ServletContext; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; + import org.springframework.beans.factory.config.ConfigurableListableBeanFactory; import org.springframework.context.ApplicationContext; import org.springframework.context.ConfigurableApplicationContext; @@ -34,7 +35,24 @@ import org.springframework.web.context.request.RequestContextHolder; import org.springframework.web.context.request.ServletWebRequest; /** - * TODO [SPR-9864] Document ServletTestExecutionListener. + * {@code TestExecutionListener} which provides mock Servlet API support to + * {@link WebApplicationContext WebApplicationContexts} loaded by the Spring + * TestContext Framework. + * + *
Specifically, {@code ServletTestExecutionListener} sets up thread-local + * state via Spring Web's {@link RequestContextHolder} during {@linkplain + * #prepareTestInstance(TestContext) test instance preparation} and {@linkplain + * #beforeTestMethod(TestContext) before each test method} and creates a {@link + * MockHttpServletRequest}, {@link MockHttpServletResponse}, and + * {@link ServletWebRequest} based on the {@link MockServletContext} present in + * the {@code WebApplicationContext}. This listener also ensures that the + * {@code MockHttpServletResponse} and {@code ServletWebRequest} can be injected + * into the test instance, and once the test is complete this listener {@linkplain + * #afterTestMethod(TestContext) cleans up} thread-local state. + * + *
Note that {@code ServletTestExecutionListener} is enabled by default but + * takes no action if the {@link ApplicationContext} loaded for the current test + * is not a {@link WebApplicationContext}. * * @author Sam Brannen * @since 3.2 @@ -43,27 +61,33 @@ public class ServletTestExecutionListener extends AbstractTestExecutionListener private static final Log logger = LogFactory.getLog(ServletTestExecutionListener.class); - + /** - * TODO [SPR-9864] Document overridden prepareTestInstance(). + * Sets up thread-local state during the test instance preparation + * callback phase via Spring Web's {@link RequestContextHolder}. * * @see TestExecutionListener#prepareTestInstance(TestContext) + * @see #setUpRequestContextIfNecessary(TestContext) */ public void prepareTestInstance(TestContext testContext) throws Exception { setUpRequestContextIfNecessary(testContext); } /** - * TODO [SPR-9864] Document overridden beforeTestMethod(). + * Sets up thread-local state before each test method via Spring Web's + * {@link RequestContextHolder}. * * @see TestExecutionListener#beforeTestMethod(TestContext) + * @see #setUpRequestContextIfNecessary(TestContext) */ public void beforeTestMethod(TestContext testContext) throws Exception { setUpRequestContextIfNecessary(testContext); } /** - * TODO [SPR-9864] Document overridden afterTestMethod(). + * Cleans up thread-local state after each test method by {@linkplain + * RequestContextHolder#resetRequestAttributes() resetting} Spring Web's + * {@code RequestContextHolder}. * * @see TestExecutionListener#afterTestMethod(TestContext) */ @@ -74,11 +98,6 @@ public class ServletTestExecutionListener extends AbstractTestExecutionListener RequestContextHolder.resetRequestAttributes(); } - /** - * TODO [SPR-9864] Document setUpRequestContext(). - * - * @param testContext - */ private void setUpRequestContextIfNecessary(TestContext testContext) { ApplicationContext context = testContext.getApplicationContext(); diff --git a/spring-test/src/main/java/org/springframework/test/context/web/WebAppConfiguration.java b/spring-test/src/main/java/org/springframework/test/context/web/WebAppConfiguration.java index 1dfa0478e0..785d314e5e 100644 --- a/spring-test/src/main/java/org/springframework/test/context/web/WebAppConfiguration.java +++ b/spring-test/src/main/java/org/springframework/test/context/web/WebAppConfiguration.java @@ -24,10 +24,25 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * TODO [SPR-9864] Document WebAppConfiguration. + * {@code @WebAppConfiguration} is a class-level annotation that is used to + * declare that the {@code ApplicationContext} loaded for an integration test + * should be a {@link org.springframework.web.context.WebApplicationContext + * WebApplicationContext}. * + *
The mere presence of {@code @WebAppConfiguration} on a test class ensures + * that a {@code WebApplicationContext} will be loaded for the test using a default + * for the path to the root of the web application. To override the default, + * specify an explicit resource path via the {@link #value} attribute. + * + *
Note that {@code @WebAppConfiguration} must be used in conjunction with + * {@link org.springframework.test.context.ContextConfiguration @ContextConfiguration}, + * either within a single test class or within a test class hierarchy. + * * @author Sam Brannen * @since 3.2 + * @see org.springframework.web.context.WebApplicationContext + * @see org.springframework.test.context.ContextConfiguration + * @see ServletTestExecutionListener */ @Documented @Inherited @@ -36,9 +51,15 @@ import java.lang.annotation.Target; public @interface WebAppConfiguration { /** - * The root directory of the web application (i.e., WAR); should not end with a slash. - * - *
Defaults to {@code "src/main/webapp"}. + * The resource path to the root directory of the web application. + * + *
A path that does not include a Spring resource prefix (e.g., {@code classpath:}, + * {@code file:}, etc.) will be interpreted as a file system resource, and a + * path should not end with a slash. + * + *
Defaults to {@code "src/main/webapp"} as a file system resource. Note + * that this is the standard directory for the root of a web application in + * a project that follows the standard Maven project layout for a WAR. */ String value() default "src/main/webapp"; diff --git a/spring-test/src/main/java/org/springframework/test/context/web/WebMergedContextConfiguration.java b/spring-test/src/main/java/org/springframework/test/context/web/WebMergedContextConfiguration.java index fc2c351e31..ce3ed59e29 100644 --- a/spring-test/src/main/java/org/springframework/test/context/web/WebMergedContextConfiguration.java +++ b/spring-test/src/main/java/org/springframework/test/context/web/WebMergedContextConfiguration.java @@ -27,10 +27,28 @@ import org.springframework.util.ObjectUtils; import org.springframework.util.StringUtils; /** - * TODO [SPR-9864] Document WebMergedContextConfiguration. + * {@code WebMergedContextConfiguration} encapsulates the merged + * context configuration declared on a test class and all of its superclasses + * via {@link org.springframework.test.context.ContextConfiguration @ContextConfiguration}, + * {@link WebAppConfiguration @WebAppConfiguration}, and + * {@link org.springframework.test.context.ActiveProfiles @ActiveProfiles}. + * + *
{@code WebMergedContextConfiguration} extends the contract of + * {@link MergedContextConfiguration} by adding support for the {@link + * #getResourceBasePath() resource base path} configured via {@code @WebAppConfiguration}. + * This allows the {@link org.springframework.test.context.TestContext TestContext} + * to properly cache the corresponding {@link + * org.springframework.web.context.WebApplicationContext WebApplicationContext} + * that was loaded using properties of this {@code WebMergedContextConfiguration}. * * @author Sam Brannen * @since 3.2 + * @see WebAppConfiguration + * @see MergedContextConfiguration + * @see org.springframework.test.context.ContextConfiguration + * @see org.springframework.test.context.ActiveProfiles + * @see org.springframework.test.context.ContextConfigurationAttributes + * @see org.springframework.test.context.SmartContextLoader#loadContext(MergedContextConfiguration) */ public class WebMergedContextConfiguration extends MergedContextConfiguration { @@ -40,7 +58,25 @@ public class WebMergedContextConfiguration extends MergedContextConfiguration { /** - * TODO [SPR-9864] Document WebMergedContextConfiguration constructor. + * Create a new {@code WebMergedContextConfiguration} instance for the + * supplied test class, resource locations, annotated classes, context + * initializers, active profiles, resource base path, and {@code ContextLoader}. + * + *
If a null value is supplied for locations,
+ * classes, or activeProfiles an empty array will
+ * be stored instead. If a null value is supplied for the
+ * contextInitializerClasses an empty set will be stored instead.
+ * If an empty value is supplied for the resourceBasePath
+ * an empty string will be used. Furthermore, active profiles will be sorted,
+ * and duplicate profiles will be removed.
+ *
+ * @param testClass the test class for which the configuration was merged
+ * @param locations the merged resource locations
+ * @param classes the merged annotated classes
+ * @param contextInitializerClasses the merged context initializer classes
+ * @param activeProfiles the merged active bean definition profiles
+ * @param resourceBasePath the resource path to the root directory of the web application
+ * @param contextLoader the resolved ContextLoader
*/
public WebMergedContextConfiguration(
Class> testClass,
@@ -55,7 +91,9 @@ public class WebMergedContextConfiguration extends MergedContextConfiguration {
}
/**
- * TODO [SPR-9864] Document getResourceBasePath().
+ * Get the resource path to the root directory of the web application for the
+ * {@linkplain #getTestClass() test class}, configured via {@code @WebAppConfiguration}.
+ * @see WebAppConfiguration
*/
public String getResourceBasePath() {
return this.resourceBasePath;