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

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;
 

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
 	 * <em>inherited</em>.
 	 *
-	 * <p>The default value is <code>true</code>, which means that an annotated
-	 * class will <em>inherit</em> 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
+	 * <p>The default value is <code>true</code>, which means that a test
+	 * class will <em>inherit</em> 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
 	 * <em>extending</em> the list of bean definition profiles.
 	 *
 	 * <p>If <code>inheritProfiles</code> is set to <code>false</code>, the bean
-	 * definition profiles for the annotated class will <em>shadow</em> and
+	 * definition profiles for the test class will <em>shadow</em> and
 	 * effectively replace any bean definition profiles defined by a superclass.
 	 *
 	 * <p>In the following example, the {@code ApplicationContext} for
@@ -98,7 +98,8 @@
 	 *
 	 * <p>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

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.
  *
  * <p>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 <code>null</code>)
 	 */
 	boolean contains(MergedContextConfiguration key) {
@@ -79,8 +79,10 @@ boolean contains(MergedContextConfiguration key) {
 
 	/**
 	 * Obtain a cached ApplicationContext for the given key.
+	 *
 	 * <p>The {@link #getHitCount() hit} and {@link #getMissCount() miss}
 	 * counts will be updated accordingly.
+	 *
 	 * @param key the context key (never <code>null</code>)
 	 * @return the corresponding ApplicationContext instance,
 	 * or <code>null</code> 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 <code>null</code>)
 	 * @param context the ApplicationContext instance (never <code>null</code>)
 	 */
@@ -144,9 +147,10 @@ void put(MergedContextConfiguration key, ApplicationContext context) {
 
 	/**
 	 * Remove the context with the given key.
+	 *
 	 * @param key the context key (never <code>null</code>)
-	 * @return the corresponding ApplicationContext instance,
-	 * or <code>null</code> if not found in the cache.
+	 * @return the corresponding ApplicationContext instance, or <code>null</code>
+	 * 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}.
+	 *
 	 * <p>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 <code>null</code>)
 	 * @see #remove
 	 */

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.
- * 
+ *
+ * <h3>Supported Resource Types</h3>
+ *
  * <p>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) <i>or</i> configuration classes (via the {@link #classes}
+ * attribute) <i>or</i> annotated classes (via the {@link #classes}
  * attribute).
- * 
+ *
+ * <h3>Annotated Classes</h3>
+ *
+ * <p>The term <em>annotated class</em> can refer to any of the following.
+ *
+ * <ul>
+ * <li>A class annotated with {@link Configuration @Configuration}</li>
+ * <li>A component (i.e., a class annotated with
+ * {@link org.springframework.stereotype.Component @Component},
+ * {@link org.springframework.stereotype.Service @Service},
+ * {@link org.springframework.stereotype.Repository @Repository}, etc.)</li>
+ * <li>A JSR-330 compliant class that is annotated with {@code javax.inject} annotations</li>
+ * <li>Any other class that contains {@link Bean @Bean}-methods</li>
+ * </ul>
+ *
+ * Consult the JavaDoc for {@link Configuration @Configuration} and {@link Bean @Bean}
+ * for further information regarding the configuration and semantics of
+ * <em>annotated classes</em>.
+ *
  * @author Sam Brannen
  * @since 2.5
  * @see ContextLoader
@@ -92,43 +115,41 @@
 	String[] locations() default {};
 
 	/**
-	 * The {@link org.springframework.context.annotation.Configuration
-	 * configuration classes} to use for loading an
+	 * The <em>annotated classes</em> to use for loading an
 	 * {@link org.springframework.context.ApplicationContext ApplicationContext}.
 	 * 
 	 * <p>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
+	 * <em>annotated classes</em> are specified. See the documentation for
+	 * {@link #loader} for further details regarding default loaders.
 	 * 
 	 * <p>This attribute may <strong>not</strong> 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
 	 */
 	Class<?>[] classes() default {};
 
 	/**
-	 * Whether or not {@link #locations resource locations} or
-	 * {@link #classes configuration classes} from superclasses should be
-	 * <em>inherited</em>.
-	 * 
+	 * Whether or not {@link #locations resource locations} or <em>annotated
+	 * classes</em> from test superclasses should be <em>inherited</em>.
+	 *
 	 * <p>The default value is <code>true</code>. This means that an annotated
-	 * class will <em>inherit</em> 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
-	 * <em>extending</em> the list of resource locations or configuration
-	 * classes.
+	 * class will <em>inherit</em> 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 <em>extending</em> the list of resource
+	 * locations or annotated classes.
 	 * 
 	 * <p>If <code>inheritLocations</code> is set to <code>false</code>, the
-	 * resource locations or configuration classes for the annotated class
+	 * resource locations or annotated classes for the annotated class
 	 * will <em>shadow</em> and effectively replace any resource locations 
-	 * or configuration classes defined by superclasses.
+	 * or annotated classes defined by superclasses.
 	 * 
 	 * <p>In the following example that uses path-based resource locations, the
 	 * {@link org.springframework.context.ApplicationContext ApplicationContext}
@@ -149,7 +170,7 @@
 	 * }
 	 * </pre>
 	 * 
-	 * <p>Similarly, in the following example that uses configuration
+	 * <p>Similarly, in the following example that uses annotated
 	 * classes, the
 	 * {@link org.springframework.context.ApplicationContext ApplicationContext}
 	 * for {@code ExtendedTest} will be loaded from the

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 <code>inheritLocations</code> 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 <code>null</code>
 	 */
 	public Class<?> getDeclaringClass() {
@@ -137,9 +138,11 @@ public Class<?> getDeclaringClass() {
 	/**
 	 * Get the resource locations that were declared via
 	 * {@link ContextConfiguration @ContextConfiguration}.
+	 *
 	 * <p>Note: this is a mutable property. The returned value may therefore
 	 * represent a <em>processed</em> value that does not match the original value
 	 * declared via {@link ContextConfiguration @ContextConfiguration}.
+	 *
 	 * @return the resource locations; potentially <code>null</code> or <em>empty</em>
 	 * @see ContextConfiguration#value
 	 * @see ContextConfiguration#locations
@@ -152,19 +155,22 @@ public String[] getLocations() {
 	/**
 	 * Set the <em>processed</em> resource locations, effectively overriding the
 	 * original value declared via {@link ContextConfiguration @ContextConfiguration}.
+	 *
 	 * @see #getLocations()
 	 */
 	public void setLocations(String[] locations) {
 		this.locations = locations;
 	}
 
 	/**
-	 * Get the configuration classes that were declared via
+	 * Get the annotated classes that were declared via
 	 * {@link ContextConfiguration @ContextConfiguration}.
+	 *
 	 * <p>Note: this is a mutable property. The returned value may therefore
 	 * represent a <em>processed</em> value that does not match the original value
 	 * declared via {@link ContextConfiguration @ContextConfiguration}.
-	 * @return the configuration classes; potentially <code>null</code> or <em>empty</em>
+	 *
+	 * @return the annotated classes; potentially <code>null</code> or <em>empty</em>
 	 * @see ContextConfiguration#classes
 	 * @see #setClasses(Class[])
 	 */
@@ -173,8 +179,9 @@ public Class<?>[] getClasses() {
 	}
 
 	/**
-	 * Set the <em>processed</em> configuration classes, effectively overriding the
+	 * Set the <em>processed</em> 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 <code>true</code> 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 <code>true</code> 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 <code>true</code> 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 <code>inheritLocations</code> flag that was declared via
 	 * {@link ContextConfiguration @ContextConfiguration}.
+	 *
 	 * @return the <code>inheritLocations</code> flag
 	 * @see ContextConfiguration#inheritLocations
 	 */
@@ -228,6 +239,7 @@ public boolean isInheritLocations() {
 	/**
 	 * Get the <code>ContextLoader</code> class that was declared via
 	 * {@link ContextConfiguration @ContextConfiguration}.
+	 *
 	 * @return the <code>ContextLoader</code> class
 	 * @see ContextConfiguration#loader
 	 */