From 36e7cb2d3142466d0f169331352f9c2abf185574 Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Thu, 17 May 2012 20:17:48 +0200 Subject: [PATCH] Improve documentation of annotated class support in the TCF Updated all Javadoc in the Spring TestContext Framework (TCF) to explain and refer to 'annotated classes' instead of 'configuration classes'. Specifically, @ContextConfiguration now explicitly defines what is meant by 'annotated classes', and various other classes now refer to this definition. Otherwise, the term 'configuration class' has simply been replaced with 'annotated class'. Also deleted cross references to deprecated JUnit 3.8 classes and formatted Javadoc in general for greater readability. Issue: SPR-9401 --- .../test/annotation/package-info.java | 4 +- .../test/context/ActiveProfiles.java | 17 ++--- .../test/context/ContextCache.java | 26 ++++--- .../test/context/ContextConfiguration.java | 67 ++++++++++++------- .../ContextConfigurationAttributes.java | 20 ++++-- .../test/context/ContextLoader.java | 12 +++- .../test/context/ContextLoaderUtils.java | 17 +++-- .../context/MergedContextConfiguration.java | 35 +++++----- .../test/context/SmartContextLoader.java | 6 +- .../AbstractJUnit4SpringContextTests.java | 5 +- ...TransactionalJUnit4SpringContextTests.java | 3 +- .../test/context/package-info.java | 21 +++--- .../support/AbstractContextLoader.java | 21 +++++- .../support/AbstractGenericContextLoader.java | 31 ++++++--- .../AnnotationConfigContextLoader.java | 50 +++++++++----- .../support/DelegatingSmartContextLoader.java | 14 ++-- .../DirtiesContextTestExecutionListener.java | 3 +- .../AbstractTestNGSpringContextTests.java | 5 +- ...TransactionalTestNGSpringContextTests.java | 3 +- 19 files changed, 227 insertions(+), 133 deletions(-) diff --git a/spring-test/src/main/java/org/springframework/test/annotation/package-info.java b/spring-test/src/main/java/org/springframework/test/annotation/package-info.java index 6590ae49a149..1695b36cc002 100644 --- a/spring-test/src/main/java/org/springframework/test/annotation/package-info.java +++ b/spring-test/src/main/java/org/springframework/test/annotation/package-info.java @@ -1,8 +1,6 @@ - /** - * * Support classes for annotation-driven tests. - * */ + package org.springframework.test.annotation; diff --git a/spring-test/src/main/java/org/springframework/test/context/ActiveProfiles.java b/spring-test/src/main/java/org/springframework/test/context/ActiveProfiles.java index 71dc59ff97e8..b0bff1db9a4c 100644 --- a/spring-test/src/main/java/org/springframework/test/context/ActiveProfiles.java +++ b/spring-test/src/main/java/org/springframework/test/context/ActiveProfiles.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2011 the original author or authors. + * Copyright 2002-2012 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. @@ -65,15 +65,15 @@ * Whether or not bean definition profiles from superclasses should be * inherited. * - *

The default value is true, which means that an annotated - * class will inherit bean definition profiles defined by an - * annotated superclass. Specifically, the bean definition profiles for an - * annotated class will be appended to the list of bean definition profiles - * defined by an annotated superclass. Thus, subclasses have the option of + *

The default value is true, which means that a test + * class will inherit bean definition profiles defined by a + * test superclass. Specifically, the bean definition profiles for a test + * class will be appended to the list of bean definition profiles + * defined by a test superclass. Thus, subclasses have the option of * extending the list of bean definition profiles. * *

If inheritProfiles is set to false, the bean - * definition profiles for the annotated class will shadow and + * definition profiles for the test class will shadow and * effectively replace any bean definition profiles defined by a superclass. * *

In the following example, the {@code ApplicationContext} for @@ -98,7 +98,8 @@ * *

Note: {@code @ActiveProfiles} can be used when loading an * {@code ApplicationContext} from path-based resource locations or - * configuration classes. + * annotated classes. + * * @see ContextConfiguration#locations * @see ContextConfiguration#classes * @see ContextConfiguration#inheritLocations diff --git a/spring-test/src/main/java/org/springframework/test/context/ContextCache.java b/spring-test/src/main/java/org/springframework/test/context/ContextCache.java index a2458fa3305b..e449ab866ecb 100644 --- a/spring-test/src/main/java/org/springframework/test/context/ContextCache.java +++ b/spring-test/src/main/java/org/springframework/test/context/ContextCache.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2011 the original author or authors. + * Copyright 2002-2012 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. @@ -25,16 +25,15 @@ import org.springframework.util.Assert; /** - * Cache for Spring {@link ApplicationContext ApplicationContexts} - * in a test environment. + * Cache for Spring {@link ApplicationContext ApplicationContexts} in a test environment. * *

Maintains a cache of {@link ApplicationContext contexts} keyed by * {@link MergedContextConfiguration} instances. This has significant performance * benefits if initializing the context would take time. While initializing a * Spring context itself is very quick, some beans in a context, such as a - * {@link org.springframework.orm.hibernate3.LocalSessionFactoryBean LocalSessionFactoryBean} - * for working with Hibernate, may take some time to initialize. Hence it often - * makes sense to perform that initialization once. + * {@code LocalSessionFactoryBean} for working with Hibernate, may take some time + * to initialize. Hence it often makes sense to perform that initialization only + * once per test suite. * * @author Sam Brannen * @author Juergen Hoeller @@ -70,6 +69,7 @@ void clearStatistics() { /** * Return whether there is a cached context for the given key. + * * @param key the context key (never null) */ boolean contains(MergedContextConfiguration key) { @@ -79,8 +79,10 @@ boolean contains(MergedContextConfiguration key) { /** * Obtain a cached ApplicationContext for the given key. + * *

The {@link #getHitCount() hit} and {@link #getMissCount() miss} * counts will be updated accordingly. + * * @param key the context key (never null) * @return the corresponding ApplicationContext instance, * or null if not found in the cache. @@ -133,6 +135,7 @@ int getMissCount() { /** * Explicitly add an ApplicationContext instance to the cache under the given key. + * * @param key the context key (never null) * @param context the ApplicationContext instance (never null) */ @@ -144,9 +147,10 @@ void put(MergedContextConfiguration key, ApplicationContext context) { /** * Remove the context with the given key. + * * @param key the context key (never null) - * @return the corresponding ApplicationContext instance, - * or null if not found in the cache. + * @return the corresponding ApplicationContext instance, or null + * if not found in the cache. * @see #setDirty */ ApplicationContext remove(MergedContextConfiguration key) { @@ -156,11 +160,13 @@ ApplicationContext remove(MergedContextConfiguration key) { /** * Mark the context with the given key as dirty, effectively * {@link #remove removing} the context from the cache and explicitly - * {@link ConfigurableApplicationContext#close() closing} it if - * it is an instance of {@link ConfigurableApplicationContext}. + * {@link ConfigurableApplicationContext#close() closing} it if it is an + * instance of {@link ConfigurableApplicationContext}. + * *

Generally speaking, you would only call this method if you change the * state of a singleton bean, potentially affecting future interaction with * the context. + * * @param key the context key (never null) * @see #remove */ 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 1638f28cc3b3..60bfa1072820 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 @@ -1,5 +1,5 @@ /* - * Copyright 2002-2011 the original author or authors. + * Copyright 2002-2012 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,20 +23,43 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; + /** * {@code ContextConfiguration} defines class-level metadata that is * used to determine how to load and configure an * {@link org.springframework.context.ApplicationContext ApplicationContext} * for test classes. - * + * + *

Supported Resource Types

+ * *

Prior to Spring 3.1, only path-based resource locations were supported. * As of Spring 3.1, {@link #loader context loaders} may choose to support * either path-based or class-based resources (but not both). Consequently * {@code @ContextConfiguration} can be used to declare either path-based * resource locations (via the {@link #locations} or {@link #value} - * attribute) or configuration classes (via the {@link #classes} + * attribute) or annotated classes (via the {@link #classes} * attribute). - * + * + *

Annotated Classes

+ * + *

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

+ * + * Consult the JavaDoc for {@link Configuration @Configuration} and {@link Bean @Bean} + * for further information regarding the configuration and semantics of + * annotated classes. + * * @author Sam Brannen * @since 2.5 * @see ContextLoader @@ -92,19 +115,19 @@ String[] locations() default {}; /** - * The {@link org.springframework.context.annotation.Configuration - * configuration classes} to use for loading an + * The annotated 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 none are specified. - * See the documentation for {@link #loader} for further details regarding - * default loaders. + * on how default configuration classes will be detected if no + * annotated classes are specified. See the documentation for + * {@link #loader} for further details regarding default loaders. * *

This attribute may not be used in conjunction with * {@link #locations} or {@link #value}. + * * @since 3.1 * @see org.springframework.context.annotation.Configuration * @see org.springframework.test.context.support.AnnotationConfigContextLoader @@ -112,23 +135,21 @@ Class[] classes() default {}; /** - * Whether or not {@link #locations resource locations} or - * {@link #classes configuration classes} from superclasses should be - * inherited. - * + * Whether or not {@link #locations resource locations} or annotated + * classes from test superclasses should be inherited. + * *

The default value is true. This means that an annotated - * class will inherit the resource locations or configuration - * classes defined by annotated superclasses. Specifically, the resource - * locations or configuration classes for an annotated class will be - * appended to the list of resource locations or configuration classes - * defined by annotated superclasses. Thus, subclasses have the option of - * extending the list of resource locations or configuration - * classes. + * class will inherit the resource locations or annotated 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. + * Thus, subclasses have the option of extending the list of resource + * locations or annotated classes. * *

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

In the following example that uses path-based resource locations, the * {@link org.springframework.context.ApplicationContext ApplicationContext} @@ -149,7 +170,7 @@ * } * * - *

Similarly, in the following example that uses configuration + *

Similarly, in the following example that uses annotated * classes, the * {@link org.springframework.context.ApplicationContext ApplicationContext} * for {@code ExtendedTest} will be loaded from the diff --git a/spring-test/src/main/java/org/springframework/test/context/ContextConfigurationAttributes.java b/spring-test/src/main/java/org/springframework/test/context/ContextConfigurationAttributes.java index e937898a231a..b7983030cef5 100644 --- a/spring-test/src/main/java/org/springframework/test/context/ContextConfigurationAttributes.java +++ b/spring-test/src/main/java/org/springframework/test/context/ContextConfigurationAttributes.java @@ -96,7 +96,7 @@ public ContextConfigurationAttributes(Class declaringClass, ContextConfigurat * * @param declaringClass the test class that declared {@code @ContextConfiguration} * @param locations the resource locations declared via {@code @ContextConfiguration} - * @param classes the configuration classes declared via {@code @ContextConfiguration} + * @param classes the annotated classes declared via {@code @ContextConfiguration} * @param inheritLocations the inheritLocations flag declared via {@code @ContextConfiguration} * @param contextLoaderClass the {@code ContextLoader} class declared via {@code @ContextConfiguration} * @throws IllegalArgumentException if the {@code declaringClass} or {@code contextLoaderClass} is @@ -128,6 +128,7 @@ public ContextConfigurationAttributes(Class declaringClass, String[] location /** * Get the {@link Class class} that declared the * {@link ContextConfiguration @ContextConfiguration} annotation. + * * @return the declaring class; never null */ public Class getDeclaringClass() { @@ -137,9 +138,11 @@ public Class getDeclaringClass() { /** * Get the resource locations that were declared via * {@link ContextConfiguration @ContextConfiguration}. + * *

Note: this is a mutable property. The returned value may therefore * represent a processed value that does not match the original value * declared via {@link ContextConfiguration @ContextConfiguration}. + * * @return the resource locations; potentially null or empty * @see ContextConfiguration#value * @see ContextConfiguration#locations @@ -152,6 +155,7 @@ public String[] getLocations() { /** * Set the processed resource locations, effectively overriding the * original value declared via {@link ContextConfiguration @ContextConfiguration}. + * * @see #getLocations() */ public void setLocations(String[] locations) { @@ -159,12 +163,14 @@ public void setLocations(String[] locations) { } /** - * Get the configuration classes that were declared via + * Get the annotated classes that were declared via * {@link ContextConfiguration @ContextConfiguration}. + * *

Note: this is a mutable property. The returned value may therefore * represent a processed value that does not match the original value * declared via {@link ContextConfiguration @ContextConfiguration}. - * @return the configuration classes; potentially null or empty + * + * @return the annotated classes; potentially null or empty * @see ContextConfiguration#classes * @see #setClasses(Class[]) */ @@ -173,8 +179,9 @@ public Class[] getClasses() { } /** - * Set the processed configuration classes, effectively overriding the + * Set the processed annotated classes, effectively overriding the * original value declared via {@link ContextConfiguration @ContextConfiguration}. + * * @see #getClasses() */ public void setClasses(Class[] classes) { @@ -184,6 +191,7 @@ public void setClasses(Class[] classes) { /** * Determine if this {@code ContextConfigurationAttributes} instance has * path-based resource locations. + * * @return true if the {@link #getLocations() locations} array is not empty * @see #hasResources() * @see #hasClasses() @@ -195,6 +203,7 @@ public boolean hasLocations() { /** * Determine if this {@code ContextConfigurationAttributes} instance has * class-based resources. + * * @return true if the {@link #getClasses() classes} array is not empty * @see #hasResources() * @see #hasLocations() @@ -206,6 +215,7 @@ public boolean hasClasses() { /** * Determine if this {@code ContextConfigurationAttributes} instance has * either path-based resource locations or class-based resources. + * * @return true if either the {@link #getLocations() locations} * or the {@link #getClasses() classes} array is not empty * @see #hasLocations() @@ -218,6 +228,7 @@ public boolean hasResources() { /** * Get the inheritLocations flag that was declared via * {@link ContextConfiguration @ContextConfiguration}. + * * @return the inheritLocations flag * @see ContextConfiguration#inheritLocations */ @@ -228,6 +239,7 @@ public boolean isInheritLocations() { /** * Get the ContextLoader class that was declared via * {@link ContextConfiguration @ContextConfiguration}. + * * @return the ContextLoader class * @see ContextConfiguration#loader */ diff --git a/spring-test/src/main/java/org/springframework/test/context/ContextLoader.java b/spring-test/src/main/java/org/springframework/test/context/ContextLoader.java index a5d7f173f36e..12fdf6142a34 100644 --- a/spring-test/src/main/java/org/springframework/test/context/ContextLoader.java +++ b/spring-test/src/main/java/org/springframework/test/context/ContextLoader.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2011 the original author or authors. + * Copyright 2002-2012 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,8 +23,8 @@ * for an integration test managed by the Spring TestContext Framework. * *

Note: as of Spring 3.1, implement {@link SmartContextLoader} instead - * of this interface in order to provide support for configuration classes and - * active bean definition profiles. + * of this interface in order to provide support for annotated classes and active + * bean definition profiles. * *

Clients of a ContextLoader should call * {@link #processLocations(Class,String...) processLocations()} prior to @@ -52,8 +52,10 @@ public interface ContextLoader { /** * Processes application context resource locations for a specified class. + * *

Concrete implementations may choose to modify the supplied locations, * generate new locations, or simply return the supplied locations unchanged. + * * @param clazz the class with which the locations are associated: used to * determine how to process the supplied locations * @param locations the unmodified locations to use for loading the @@ -66,8 +68,10 @@ public interface ContextLoader { * Loads a new {@link ApplicationContext context} based on the supplied * locations, configures the context, and finally returns * the context in fully refreshed state. + * *

Configuration locations are generally considered to be classpath * resources by default. + * *

Concrete implementations should register annotation configuration * processors with bean factories of {@link ApplicationContext application * contexts} loaded by this ContextLoader. Beans will therefore automatically @@ -75,11 +79,13 @@ public interface ContextLoader { * {@link org.springframework.beans.factory.annotation.Autowired @Autowired}, * {@link javax.annotation.Resource @Resource}, and * {@link javax.inject.Inject @Inject}. + * *

Any ApplicationContext loaded by a ContextLoader must * register a JVM shutdown hook for itself. Unless the context gets closed * early, all context instances will be automatically closed on JVM * shutdown. This allows for freeing external resources held by beans within * the context, e.g. temporary files. + * * @param locations the resource locations to use to load the application context * @return a new application context * @throws Exception if context loading failed diff --git a/spring-test/src/main/java/org/springframework/test/context/ContextLoaderUtils.java b/spring-test/src/main/java/org/springframework/test/context/ContextLoaderUtils.java index 5d3609d4b6ed..8f62aecbe5c4 100644 --- a/spring-test/src/main/java/org/springframework/test/context/ContextLoaderUtils.java +++ b/spring-test/src/main/java/org/springframework/test/context/ContextLoaderUtils.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2011 the original author or authors. + * Copyright 2002-2012 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,7 +35,7 @@ /** * Utility methods for working with {@link ContextLoader ContextLoaders} and * {@link SmartContextLoader SmartContextLoaders} and resolving resource locations, - * configuration classes, and active bean definition profiles. + * annotated classes, and active bean definition profiles. * * @author Sam Brannen * @since 3.1 @@ -61,11 +61,13 @@ private ContextLoaderUtils() { * Resolve the {@link ContextLoader} {@link Class class} to use for the * supplied {@link Class testClass} and then instantiate and return that * {@code ContextLoader}. + * *

If the supplied defaultContextLoaderClassName is * null or empty, the standard * default context loader class name {@value #DEFAULT_CONTEXT_LOADER_CLASS_NAME} * will be used. For details on the class resolution process, see * {@link #resolveContextLoaderClass()}. + * * @param testClass the test class for which the {@code ContextLoader} * should be resolved (must not be null) * @param defaultContextLoaderClassName the name of the default @@ -90,6 +92,7 @@ static ContextLoader resolveContextLoader(Class testClass, String defaultCont /** * Resolve the {@link ContextLoader} {@link Class} to use for the supplied * {@link Class testClass}. + * *

    *
  1. If the {@link ContextConfiguration#loader() loader} attribute of * {@link ContextConfiguration @ContextConfiguration} is configured @@ -101,6 +104,7 @@ static ContextLoader resolveContextLoader(Class testClass, String defaultCont * the class hierarchy, an attempt will be made to load and return the class * with the supplied defaultContextLoaderClassName.
    2. *
+ * * @param testClass the class for which to resolve the {@code ContextLoader} * class; must not be null * @param defaultContextLoaderClassName the name of the default @@ -163,13 +167,15 @@ static Class resolveContextLoaderClass(Class testCla /** * Resolve the list of {@link ContextConfigurationAttributes configuration * attributes} for the supplied {@link Class class} and its superclasses. + * *

Note that the {@link ContextConfiguration#inheritLocations * inheritLocations} flag of {@link ContextConfiguration * @ContextConfiguration} will be taken into consideration. * Specifically, if the inheritLocations flag is set to - * true, configuration attributes defined in the annotated + * true, configuration attributes defined in the test * class will be appended to the configuration attributes defined in * superclasses. + * * @param clazz the class for which to resolve the configuration attributes (must * not be null) * @return the list of configuration attributes for the specified class, @@ -214,11 +220,13 @@ static List resolveContextConfigurationAttribute /** * Resolve active bean definition profiles for the supplied {@link Class}. + * *

Note that the {@link ActiveProfiles#inheritProfiles inheritProfiles} * flag of {@link ActiveProfiles @ActiveProfiles} will be taken into * consideration. Specifically, if the inheritProfiles flag is - * set to true, profiles defined in the annotated class will be + * set to true, profiles defined in the test class will be * merged with those defined in superclasses. + * * @param clazz the class for which to resolve the active profiles (must * not be null) * @return the set of active profiles for the specified class, including @@ -280,6 +288,7 @@ else if (!ObjectUtils.isEmpty(valueProfiles)) { * Build the {@link MergedContextConfiguration merged context configuration} * for the supplied {@link Class testClass} and * defaultContextLoaderClassName. + * * @param testClass the test class for which the {@code MergedContextConfiguration} * should be built (must not be null) * @param defaultContextLoaderClassName the name of the default diff --git a/spring-test/src/main/java/org/springframework/test/context/MergedContextConfiguration.java b/spring-test/src/main/java/org/springframework/test/context/MergedContextConfiguration.java index 59b282a49768..274d5da8c431 100644 --- a/spring-test/src/main/java/org/springframework/test/context/MergedContextConfiguration.java +++ b/spring-test/src/main/java/org/springframework/test/context/MergedContextConfiguration.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2011 the original author or authors. + * Copyright 2002-2012 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. @@ -30,8 +30,8 @@ * context configuration declared on a test class and all of its superclasses * via {@link ContextConfiguration @ContextConfiguration} and * {@link ActiveProfiles @ActiveProfiles}. - * - *

Merged resource locations, configuration classes, and active profiles + * + *

Merged resource locations, annotated classes, and active profiles * represent all declared values in the test class hierarchy taking into * consideration the semantics of the * {@link ContextConfiguration#inheritLocations inheritLocations} and @@ -98,15 +98,17 @@ private static String nullSafeToString(ContextLoader contextLoader) { /** * Create a new {@code MergedContextConfiguration} instance for the - * supplied {@link Class test class}, resource locations, configuration - * classes, active profiles, and {@link ContextLoader}. + * supplied test class, resource locations, annotated classes, active + * profiles, and {@code ContextLoader}. + * *

If a null value is supplied for locations, * classes, or activeProfiles an empty array will * be stored instead. Furthermore, active profiles will be sorted, and duplicate - * profiles will be removed. + * 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 configuration classes + * @param classes the merged annotated classes * @param activeProfiles the merged active bean definition profiles * @param contextLoader the resolved ContextLoader */ @@ -120,40 +122,35 @@ public MergedContextConfiguration(Class testClass, String[] locations, Class< } /** - * Get the {@link Class test class} associated with this - * {@code MergedContextConfiguration}. + * Get the {@link Class test class} associated with this {@code MergedContextConfiguration}. */ public Class getTestClass() { return testClass; } /** - * Get the merged resource locations for the - * {@link #getTestClass() test class}. + * Get the merged resource locations for the {@link #getTestClass() test class}. */ public String[] getLocations() { return locations; } /** - * Get the merged configuration classes for the - * {@link #getTestClass() test class}. + * Get the merged annotated classes for the {@link #getTestClass() test class}. */ public Class[] getClasses() { return classes; } /** - * Get the merged active bean definition profiles for the - * {@link #getTestClass() test class}. + * Get the merged active bean definition profiles for the {@link #getTestClass() test class}. */ public String[] getActiveProfiles() { return activeProfiles; } /** - * Get the resolved {@link ContextLoader} for the - * {@link #getTestClass() test class}. + * Get the resolved {@link ContextLoader} for the {@link #getTestClass() test class}. */ public ContextLoader getContextLoader() { return contextLoader; @@ -178,7 +175,7 @@ public int hashCode() { /** * Determine if the supplied object is equal to this {@code MergedContextConfiguration} * instance by comparing both object's {@link #getLocations() locations}, - * {@link #getClasses() configuration classes}, {@link #getActiveProfiles() + * {@link #getClasses() annotated classes}, {@link #getActiveProfiles() * active profiles}, and the fully qualified names of their * {@link #getContextLoader() ContextLoaders}. */ @@ -212,7 +209,7 @@ public boolean equals(Object obj) { /** * Provide a String representation of the {@link #getTestClass() test class}, - * {@link #getLocations() locations}, {@link #getClasses() configuration classes}, + * {@link #getLocations() locations}, {@link #getClasses() annotated classes}, * {@link #getActiveProfiles() active profiles}, and the name of the * {@link #getContextLoader() ContextLoader}. */ diff --git a/spring-test/src/main/java/org/springframework/test/context/SmartContextLoader.java b/spring-test/src/main/java/org/springframework/test/context/SmartContextLoader.java index 63d52418a9dd..ba5f22bd66b1 100644 --- a/spring-test/src/main/java/org/springframework/test/context/SmartContextLoader.java +++ b/spring-test/src/main/java/org/springframework/test/context/SmartContextLoader.java @@ -24,11 +24,15 @@ * *

The {@code SmartContextLoader} SPI supersedes the {@link ContextLoader} SPI * introduced in Spring 2.5: a {@code SmartContextLoader} can choose to process - * either resource locations or configuration classes. Furthermore, a + * either resource locations or annotated classes. Furthermore, a * {@code SmartContextLoader} can set active bean definition profiles in the * context that it loads (see {@link MergedContextConfiguration#getActiveProfiles()} * and {@link #loadContext(MergedContextConfiguration)}). * + *

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

Clients of a {@code SmartContextLoader} should call * {@link #processContextConfiguration(ContextConfigurationAttributes) * processContextConfiguration()} prior to calling diff --git a/spring-test/src/main/java/org/springframework/test/context/junit4/AbstractJUnit4SpringContextTests.java b/spring-test/src/main/java/org/springframework/test/context/junit4/AbstractJUnit4SpringContextTests.java index 50967dedf795..69916d321df0 100644 --- a/spring-test/src/main/java/org/springframework/test/context/junit4/AbstractJUnit4SpringContextTests.java +++ b/spring-test/src/main/java/org/springframework/test/context/junit4/AbstractJUnit4SpringContextTests.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2009 the original author or authors. + * Copyright 2002-2012 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. @@ -60,11 +60,10 @@ * @see TestContext * @see TestContextManager * @see AbstractTransactionalJUnit4SpringContextTests - * @see org.springframework.test.context.junit38.AbstractJUnit38SpringContextTests * @see org.springframework.test.context.testng.AbstractTestNGSpringContextTests */ @RunWith(SpringJUnit4ClassRunner.class) -@TestExecutionListeners( { DependencyInjectionTestExecutionListener.class, DirtiesContextTestExecutionListener.class }) +@TestExecutionListeners({ DependencyInjectionTestExecutionListener.class, DirtiesContextTestExecutionListener.class }) public abstract class AbstractJUnit4SpringContextTests implements ApplicationContextAware { /** diff --git a/spring-test/src/main/java/org/springframework/test/context/junit4/AbstractTransactionalJUnit4SpringContextTests.java b/spring-test/src/main/java/org/springframework/test/context/junit4/AbstractTransactionalJUnit4SpringContextTests.java index ca545b1ad90c..541ffd241ab9 100644 --- a/spring-test/src/main/java/org/springframework/test/context/junit4/AbstractTransactionalJUnit4SpringContextTests.java +++ b/spring-test/src/main/java/org/springframework/test/context/junit4/AbstractTransactionalJUnit4SpringContextTests.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2011 the original author or authors. + * Copyright 2002-2012 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. @@ -74,7 +74,6 @@ * @see org.springframework.test.context.transaction.BeforeTransaction * @see org.springframework.test.context.transaction.AfterTransaction * @see org.springframework.test.jdbc.SimpleJdbcTestUtils - * @see org.springframework.test.context.junit38.AbstractTransactionalJUnit38SpringContextTests * @see org.springframework.test.context.testng.AbstractTransactionalTestNGSpringContextTests */ @SuppressWarnings("deprecation") diff --git a/spring-test/src/main/java/org/springframework/test/context/package-info.java b/spring-test/src/main/java/org/springframework/test/context/package-info.java index c9cd821a2aee..f549babc39d7 100644 --- a/spring-test/src/main/java/org/springframework/test/context/package-info.java +++ b/spring-test/src/main/java/org/springframework/test/context/package-info.java @@ -1,16 +1,15 @@ /** - *

This package contains the Spring TestContext Framework - * which provides annotation-driven unit and integration testing support - * that is agnostic of the actual testing framework in use. The same - * techniques and annotation-based configuration used in, for example, a - * JUnit 3.8 environment can also be applied to tests written with JUnit - * 4.5+, TestNG, etc.

+ *

This package contains the Spring TestContext Framework which + * provides annotation-driven unit and integration testing support that is + * agnostic of the actual testing framework in use. The same techniques and + * annotation-based configuration used in, for example, a JUnit 4.5+ environment + * can also be applied to tests written with TestNG, etc. * - *

In addition to providing generic and extensible testing - * infrastructure, the Spring TestContext Framework provides out-of-the-box - * support for Spring-specific integration testing functionality such as - * context management and caching, dependency injection of test fixtures, - * and transactional test management with default rollback semantics.

+ *

In addition to providing generic and extensible testing infrastructure, + * the Spring TestContext Framework provides out-of-the-box support for + * Spring-specific integration testing functionality such as context management + * and caching, dependency injection of test fixtures, and transactional test + * management with default rollback semantics. */ package org.springframework.test.context; diff --git a/spring-test/src/main/java/org/springframework/test/context/support/AbstractContextLoader.java b/spring-test/src/main/java/org/springframework/test/context/support/AbstractContextLoader.java index 83e50888e774..0fe803569501 100644 --- a/spring-test/src/main/java/org/springframework/test/context/support/AbstractContextLoader.java +++ b/spring-test/src/main/java/org/springframework/test/context/support/AbstractContextLoader.java @@ -68,8 +68,10 @@ public abstract class AbstractContextLoader implements SmartContextLoader { * processed locations are then * {@link ContextConfigurationAttributes#setLocations(String[]) set} in * the supplied configuration attributes. + * *

Can be overridden in subclasses — for example, to process - * configuration classes instead of resource locations. + * annotated classes instead of resource locations. + * * @since 3.1 * @see #processLocations(Class, String...) */ @@ -90,6 +92,7 @@ public void processContextConfiguration(ContextConfigurationAttributes configAtt * {@link #getResourceSuffix() resource suffix}; otherwise, the supplied * locations will be {@link #modifyLocations modified} if * necessary and returned. + * * @param clazz the class with which the locations are associated: to be * used when generating default locations * @param locations the unmodified locations to use for loading the @@ -110,18 +113,22 @@ public final String[] processLocations(Class clazz, String... locations) { /** * Generate the default classpath resource locations array based on the * supplied class. + * *

For example, if the supplied class is com.example.MyTest, * the generated locations will contain a single string with a value of * "classpath:/com/example/MyTest<suffix>", * where <suffix> is the value of the * {@link #getResourceSuffix() resource suffix} string. + * *

As of Spring 3.1, the implementation of this method adheres to the * contract defined in the {@link SmartContextLoader} SPI. Specifically, * this method will preemptively verify that the generated default * location actually exists. If it does not exist, this method will log a * warning and return an empty array. + * *

Subclasses can override this method to implement a different * default location generation strategy. + * * @param clazz the class for which the default locations are to be generated * @return an array of default application context resource locations * @since 2.5 @@ -153,6 +160,7 @@ protected String[] generateDefaultLocations(Class clazz) { /** * Generate a modified version of the supplied locations array and return it. + * *

A plain path — for example, "context.xml" — will * be treated as a classpath resource that is relative to the package in which * the specified class is defined. A path starting with a slash is treated @@ -162,8 +170,10 @@ protected String[] generateDefaultLocations(Class clazz) { * {@link ResourceUtils#CLASSPATH_URL_PREFIX classpath:}, * {@link ResourceUtils#FILE_URL_PREFIX file:}, http:, * etc.) will be added to the results unchanged. + * *

Subclasses can override this method to implement a different * location modification strategy. + * * @param clazz the class with which the locations are associated * @param locations the resource locations to be modified * @return an array of modified application context resource locations @@ -191,6 +201,7 @@ else if (!ResourcePatternUtils.isUrl(path)) { * Determine whether or not default resource locations should be * generated if the locations provided to * {@link #processLocations(Class, String...)} are null or empty. + * *

As of Spring 3.1, the semantics of this method have been overloaded * to include detection of either default resource locations or default * configuration classes. Consequently, this method can also be used to @@ -199,7 +210,9 @@ else if (!ResourcePatternUtils.isUrl(path)) { * {@link ContextConfigurationAttributes configuration attributes} supplied * to {@link #processContextConfiguration(ContextConfigurationAttributes)} * are null or empty. + * *

Can be overridden by subclasses to change the default behavior. + * * @return always true by default * @since 2.5 */ @@ -208,9 +221,11 @@ protected boolean isGenerateDefaultLocations() { } /** - * Get the suffix to append to {@link ApplicationContext} resource - * locations when generating default locations. + * Get the suffix to append to {@link ApplicationContext} resource locations + * when generating default locations. + * *

Must be implemented by subclasses. + * * @return the resource suffix; should not be null or empty * @since 2.5 * @see #generateDefaultLocations(Class) diff --git a/spring-test/src/main/java/org/springframework/test/context/support/AbstractGenericContextLoader.java b/spring-test/src/main/java/org/springframework/test/context/support/AbstractGenericContextLoader.java index 6da30280093f..e1669ac176bc 100644 --- a/spring-test/src/main/java/org/springframework/test/context/support/AbstractGenericContextLoader.java +++ b/spring-test/src/main/java/org/springframework/test/context/support/AbstractGenericContextLoader.java @@ -40,8 +40,7 @@ * SPI, the context will be loaded from the {@link MergedContextConfiguration} * provided to {@link #loadContext(MergedContextConfiguration)}. In such cases, a * SmartContextLoader will decide whether to load the context from - * locations or - * {@link org.springframework.context.annotation.Configuration configuration classes}. + * locations or annotated classes. * * *

Concrete subclasses must provide an appropriate implementation of @@ -62,7 +61,9 @@ public abstract class AbstractGenericContextLoader extends AbstractContextLoader /** * Load a Spring ApplicationContext from the supplied {@link MergedContextConfiguration}. + * *

Implementation details: + * *

+ * * @return a new application context * @see org.springframework.test.context.SmartContextLoader#loadContext(MergedContextConfiguration) * @see GenericApplicationContext @@ -107,7 +109,9 @@ public final ConfigurableApplicationContext loadContext(MergedContextConfigurati /** * Load a Spring ApplicationContext from the supplied locations. + * *

Implementation details: + * *

+ * *

Note: this method does not provide a means to set active bean definition * profiles for the loaded context. See {@link #loadContext(MergedContextConfiguration)} * for an alternative. + * * @return a new application context * @see org.springframework.test.context.ContextLoader#loadContext * @see GenericApplicationContext @@ -153,8 +159,10 @@ public final ConfigurableApplicationContext loadContext(String... locations) thr /** * Prepare the {@link GenericApplicationContext} created by this ContextLoader. * Called before bean definitions are read. + * *

The default implementation is empty. Can be overridden in subclasses to * customize GenericApplicationContext's standard settings. + * * @param context the context that should be prepared * @see #loadContext(MergedContextConfiguration) * @see #loadContext(String...) @@ -169,8 +177,10 @@ protected void prepareContext(GenericApplicationContext context) { /** * Customize the internal bean factory of the ApplicationContext created by * this ContextLoader. + * *

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 ContextLoader * @see #loadContext(MergedContextConfiguration) * @see #loadContext(String...) @@ -185,17 +195,19 @@ protected void customizeBeanFactory(DefaultListableBeanFactory beanFactory) { /** * Load bean definitions into the supplied {@link GenericApplicationContext context} - * from the configuration locations or classes in the supplied - * MergedContextConfiguration. + * from the locations or classes in the supplied MergedContextConfiguration. + * *

The default implementation delegates to the {@link BeanDefinitionReader} * returned by {@link #createBeanDefinitionReader(GenericApplicationContext)} to * {@link BeanDefinitionReader#loadBeanDefinitions(String) load} the * bean definitions. + * *

Subclasses must provide an appropriate implementation of - * {@link #createBeanDefinitionReader(GenericApplicationContext)}. Alternatively subclasses may - * provide a no-op implementation of {@code createBeanDefinitionReader()} + * {@link #createBeanDefinitionReader(GenericApplicationContext)}. Alternatively subclasses + * may provide a no-op implementation of {@code createBeanDefinitionReader()} * and override this method to provide a custom strategy for loading or * registering bean definitions. + * * @param context the context into which the bean definitions should be loaded * @param mergedConfig the merged context configuration * @see #loadContext(MergedContextConfiguration) @@ -208,6 +220,7 @@ protected void loadBeanDefinitions(GenericApplicationContext context, MergedCont /** * Factory method for creating a new {@link BeanDefinitionReader} for loading * bean definitions into the supplied {@link GenericApplicationContext context}. + * * @param context the context for which the BeanDefinitionReader * should be created * @return a BeanDefinitionReader for the supplied context @@ -222,8 +235,10 @@ protected void loadBeanDefinitions(GenericApplicationContext context, MergedCont * Customize the {@link GenericApplicationContext} created by this * ContextLoader 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 application context. + * * @param context the newly created application context * @see #loadContext(MergedContextConfiguration) * @see #loadContext(String...) 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 8d92ff51a42c..39542ad34b14 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 @@ -33,11 +33,13 @@ /** * Concrete implementation of {@link AbstractGenericContextLoader} that loads - * bean definitions from - * {@link org.springframework.context.annotation.Configuration configuration classes}. - * - *

Note: AnnotationConfigContextLoader supports - * {@link org.springframework.context.annotation.Configuration configuration classes} + * bean definitions from annotated classes. + * + *

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

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

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

If the annotated classes are null or empty and * {@link #isGenerateDefaultLocations()} returns true, this * SmartContextLoader will attempt to {@link * #detectDefaultConfigurationClasses detect default configuration classes}. @@ -71,6 +74,7 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader * {@link ContextConfigurationAttributes#setClasses(Class[]) set} in the * supplied configuration attributes. Otherwise, properties in the supplied * configuration attributes will not be modified. + * * @param configAttributes the context configuration attributes to process * @see org.springframework.test.context.SmartContextLoader#processContextConfiguration(ContextConfigurationAttributes) * @see #isGenerateDefaultLocations() @@ -94,7 +98,9 @@ private boolean isStaticNonPrivateAndNonFinal(Class clazz) { /** * Determine if the supplied {@link Class} meets the criteria for being * considered a default configuration class candidate. + * *

Specifically, such candidates: + * *

+ * * @param clazz the class to check * @return true if the supplied class meets the candidate criteria */ @@ -111,16 +118,18 @@ private boolean isDefaultConfigurationClassCandidate(Class clazz) { /** * Detect the default configuration classes for the supplied test class. + * *

The returned class array will contain all static inner classes of * the supplied class that meet the requirements for {@code @Configuration} * class implementations as specified in the documentation for * {@link Configuration @Configuration}. + * *

The implementation of this method adheres to the contract defined in the * {@link org.springframework.test.context.SmartContextLoader SmartContextLoader} * SPI. Specifically, this method uses introspection to detect default * configuration classes that comply with the constraints required of * {@code @Configuration} class implementations. If a potential candidate - * configuration class does meet these requirements, this method will log a + * configuration class does not meet these requirements, this method will log a * warning, and the potential candidate class will be ignored. * @param declaringClass the test class that declared {@code @ContextConfiguration} * @return an array of default configuration classes, potentially empty but @@ -163,6 +172,7 @@ protected Class[] detectDefaultConfigurationClasses(Class declaringClass) * {@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 AbstractContextLoader#modifyLocations * @throws UnsupportedOperationException */ @@ -177,6 +187,7 @@ protected String[] modifyLocations(Class clazz, String... locations) { * {@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 AbstractContextLoader#generateDefaultLocations * @throws UnsupportedOperationException */ @@ -191,6 +202,7 @@ protected String[] generateDefaultLocations(Class clazz) { * {@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 AbstractContextLoader#getResourceSuffix * @throws UnsupportedOperationException */ @@ -203,26 +215,29 @@ protected String getResourceSuffix() { // --- AbstractGenericContextLoader ---------------------------------------- /** - * Register {@link org.springframework.context.annotation.Configuration configuration classes} - * in the supplied {@link GenericApplicationContext context} from the classes - * in the supplied {@link MergedContextConfiguration}. - *

Each class must represent an annotated configuration class or component. An + * Register classes in the supplied {@link GenericApplicationContext context} + * from the classes in the supplied {@link MergedContextConfiguration}. + * + *

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

Note that this method does not call {@link #createBeanDefinitionReader} + * + *

Note that this method does not call {@link #createBeanDefinitionReader()} * since AnnotatedBeanDefinitionReader is not an instance of * {@link BeanDefinitionReader}. - * @param context the context in which the configuration classes should be registered + * + * @param context the context in which the annotated 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[] configClasses = mergedConfig.getClasses(); + Class[] annotatedClasses = mergedConfig.getClasses(); if (logger.isDebugEnabled()) { - logger.debug("Registering configuration classes: " + ObjectUtils.nullSafeToString(configClasses)); + logger.debug("Registering annotated classes: " + ObjectUtils.nullSafeToString(annotatedClasses)); } - new AnnotatedBeanDefinitionReader(context).register(configClasses); + new AnnotatedBeanDefinitionReader(context).register(annotatedClasses); } /** @@ -230,6 +245,7 @@ protected void loadBeanDefinitions(GenericApplicationContext context, MergedCont * {@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 #loadBeanDefinitions * @see AbstractGenericContextLoader#createBeanDefinitionReader * @throws UnsupportedOperationException diff --git a/spring-test/src/main/java/org/springframework/test/context/support/DelegatingSmartContextLoader.java b/spring-test/src/main/java/org/springframework/test/context/support/DelegatingSmartContextLoader.java index fcdf2a30db07..2fe19aa0a7d2 100644 --- a/spring-test/src/main/java/org/springframework/test/context/support/DelegatingSmartContextLoader.java +++ b/spring-test/src/main/java/org/springframework/test/context/support/DelegatingSmartContextLoader.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2011 the original author or authors. + * Copyright 2002-2012 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. @@ -48,7 +48,7 @@ * {@link SmartContextLoader} is not explicitly declared via * {@code @ContextConfiguration}, {@code DelegatingSmartContextLoader} will be used as * the default loader, thus providing automatic support for either XML configuration - * files or configuration classes, but not both simultaneously. + * files or annotated classes, but not both simultaneously. * * @author Sam Brannen * @since 3.1 @@ -96,7 +96,7 @@ private static boolean supports(SmartContextLoader loader, MergedContextConfigur * Specifically, the delegation algorithm is as follows: * *