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 6590ae49a14..1695b36cc00 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 71dc59ff97e..b0bff1db9a4 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 @@ public @interface ActiveProfiles { * 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 @@ public @interface ActiveProfiles { * *

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 a2458fa3305..e449ab866ec 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.core.style.ToStringCreator; 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 @@ class ContextCache { /** * 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 @@ class ContextCache { /** * 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 @@ class ContextCache { /** * 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 @@ class ContextCache { /** * 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 @@ class ContextCache { /** * 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 1638f28cc3b..60bfa107282 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.Retention; 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 @@ public @interface ContextConfiguration { 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 @@ public @interface ContextConfiguration { 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 @@ public @interface ContextConfiguration { * } * * - *

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 e937898a231..b7983030cef 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 class ContextConfigurationAttributes { * * @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 class ContextConfigurationAttributes { /** * 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 ContextConfigurationAttributes { /** * 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 class ContextConfigurationAttributes { /** * 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 class ContextConfigurationAttributes { } /** - * 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 ContextConfigurationAttributes { } /** - * 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 class ContextConfigurationAttributes { /** * 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 class ContextConfigurationAttributes { /** * 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 class ContextConfigurationAttributes { /** * 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 class ContextConfigurationAttributes { /** * Get the inheritLocations flag that was declared via * {@link ContextConfiguration @ContextConfiguration}. + * * @return the inheritLocations flag * @see ContextConfiguration#inheritLocations */ @@ -228,6 +239,7 @@ public class ContextConfigurationAttributes { /** * 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 a5d7f173f36..12fdf6142a3 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 @@ import org.springframework.context.ApplicationContext; * 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 5d3609d4b6e..8f62aecbe5c 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 @@ import org.springframework.util.StringUtils; /** * 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 @@ abstract class 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 @@ abstract class ContextLoaderUtils { /** * 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 @@ abstract class ContextLoaderUtils { * 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 @@ abstract class ContextLoaderUtils { /** * 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 @@ abstract class ContextLoaderUtils { /** * 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 @@ abstract class ContextLoaderUtils { * 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 59b282a4976..274d5da8c43 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 @@ import org.springframework.util.StringUtils; * 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 @@ public class MergedContextConfiguration implements Serializable { /** * 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 class MergedContextConfiguration implements Serializable { } /** - * 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 class MergedContextConfiguration implements Serializable { /** * 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 class MergedContextConfiguration implements Serializable { /** * 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 63d52418a9d..ba5f22bd66b 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 @@ import org.springframework.context.ApplicationContext; * *

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 50967dedf79..69916d321df 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 @@ import org.springframework.test.context.support.DirtiesContextTestExecutionListe * @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 ca545b1ad90..541ffd241ab 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 @@ import org.springframework.transaction.annotation.Transactional; * @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 c9cd821a2ae..f549babc39d 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 83e50888e77..0fe80356950 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 abstract class AbstractContextLoader implements SmartContextLoader { * {@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 abstract class AbstractContextLoader implements SmartContextLoader { /** * 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 @@ public abstract class AbstractContextLoader implements SmartContextLoader { /** * 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 @@ public abstract class AbstractContextLoader implements SmartContextLoader { * {@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 @@ public abstract class AbstractContextLoader implements SmartContextLoader { * 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 @@ public abstract class AbstractContextLoader implements SmartContextLoader { * {@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 @@ public abstract class AbstractContextLoader implements SmartContextLoader { } /** - * 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 6da30280093..e1669ac176b 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 @@ import org.springframework.util.StringUtils; * 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 abstract class AbstractGenericContextLoader extends AbstractContextLoader /** * 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 abstract class AbstractGenericContextLoader extends AbstractContextLoader /** * 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 @@ public abstract class AbstractGenericContextLoader extends AbstractContextLoader /** * 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 @@ public abstract class AbstractGenericContextLoader extends AbstractContextLoader /** * 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 @@ public abstract class AbstractGenericContextLoader extends AbstractContextLoader /** * 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 @@ public abstract class AbstractGenericContextLoader extends AbstractContextLoader * 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 8d92ff51a42..39542ad34b1 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 @@ import org.springframework.util.ObjectUtils; /** * 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 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader /** * 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 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader /** * 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 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader * {@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 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader * {@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 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader * {@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 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader // --- 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 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader * {@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 fcdf2a30db0..2fe19aa0a7d 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 @@ import org.springframework.util.ObjectUtils; * {@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 @@ public class DelegatingSmartContextLoader implements SmartContextLoader { * Specifically, the delegation algorithm is as follows: * *