[SPR-6184] completed JavaDoc for @ContextConfiguration.

org.springframework.test/src/main/java/org/springframework/test/context/ContextConfiguration.java

@@ -24,9 +24,18 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * ContextConfiguration defines class-level metadata which can be used to
- * instruct client code with regard to how to load and configure an
- * {@link org.springframework.context.ApplicationContext ApplicationContext}.
+ * {@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.
+ * 
+ * <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).
  * 
  * @author Sam Brannen
  * @since 2.5
@@ -41,6 +50,10 @@ public @interface ContextConfiguration {
 
 	/**
 	 * Alias for {@link #locations() locations}.
+	 * 
+	 * <p>This attribute may <strong>not</strong> be used in conjunction
+	 * with {@link #locations} or {@link #classes}, but it may be used
+	 * instead of {@link #locations}.
 	 * @since 3.0
 	 */
 	String[] value() default {};
@@ -48,38 +61,68 @@ public @interface ContextConfiguration {
 	/**
 	 * The resource locations to use for loading an
 	 * {@link org.springframework.context.ApplicationContext ApplicationContext}.
+	 * 
 	 * <p>Check out the javadoc for {@link org.springframework.test.context.support.AbstractContextLoader#modifyLocations AbstractContextLoader.modifyLocations()}
 	 * for details on how a location String will be interpreted at runtime,
 	 * in particular in case of a relative path. Also, check out the documentation on
 	 * {@link org.springframework.test.context.support.AbstractContextLoader#generateDefaultLocations AbstractContextLoader.generateDefaultLocations()}
 	 * for details on the default locations that are going to be used if none are specified.
+	 * 
 	 * <p>Note that the above-mentioned default rules only apply for a standard
 	 * {@link org.springframework.test.context.support.AbstractContextLoader AbstractContextLoader} subclass
 	 * such as {@link org.springframework.test.context.support.GenericXmlContextLoader GenericXmlContextLoader}
 	 * which is the effective default implementation used at runtime.
+	 * 
+	 * <p>This attribute may <strong>not</strong> be used in conjunction
+	 * with {@link #value} or {@link #classes}, but it may be used
+	 * instead of {@link #value}.
 	 */
 	String[] locations() default {};
 
 	/**
-	 * TODO Document classes().
+	 * The {@link org.springframework.context.annotation.Configuration configuration classes}
+	 * to use for loading an
+	 * {@link org.springframework.context.ApplicationContext ApplicationContext}.
+	 * 
+	 * <p>To enable support for configuration class processing, an appropriate
+	 * {@link ContextLoader} must be {@link #loader configured}.
+	 * {@link org.springframework.test.context.support.AnnotationConfigContextLoader AnnotationConfigContextLoader}
+	 * is one such loader provided by the Spring Framework.
+	 * 
+	 * <p>Check out the javadoc for
+	 * {@link org.springframework.test.context.support.AnnotationConfigContextLoader#generateDefaultLocations AnnotationConfigContextLoader.generateDefaultLocations()}
+	 * for details on the default configuration classes that will be used if none are specified.
 	 * 
+	 * <p>Note that 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 {};
 
 	/**
-	 * TODO Update documentation regarding classes vs. locations.
+	 * 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} 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> the resource locations defined by an
-	 * annotated superclass. Specifically, the resource locations for an
-	 * annotated class will be appended to the list of resource locations
+	 * class will <em>inherit</em> the resource locations or configuration
+	 * classes defined by an annotated superclass. 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 an annotated superclass. Thus, subclasses have the option of
-	 * <em>extending</em> the list of resource locations. In the following
-	 * example, the {@link org.springframework.context.ApplicationContext ApplicationContext}
-	 * for <code>ExtendedTest</code> will be loaded from
+	 * <em>extending</em> the list of resource locations or configuration
+	 * classes.
+	 * 
+	 * <p>If <code>inheritLocations</code> is set to <code>false</code>, the
+	 * resource locations or configuration classes for the annotated class
+	 * will <em>shadow</em> and effectively replace any resource locations 
+	 * or configuration classes defined by a superclass.
+	 * 
+	 * <p>In the following example that uses path-based resource locations, the
+	 * {@link org.springframework.context.ApplicationContext ApplicationContext}
+	 * for {@code ExtendedTest} will be loaded from
 	 * &quot;base-context.xml&quot; <strong>and</strong>
 	 * &quot;extended-context.xml&quot;, in that order. Beans defined in
 	 * &quot;extended-context.xml&quot; may therefore override those defined in
@@ -87,27 +130,46 @@ public @interface ContextConfiguration {
 	 * <pre class="code">
 	 * &#064;ContextConfiguration(&quot;base-context.xml&quot;)
 	 * public class BaseTest {
-	 * 	// ...
+	 *     // ...
 	 * }
 	 * 
 	 * &#064;ContextConfiguration(&quot;extended-context.xml&quot;)
 	 * public class ExtendedTest extends BaseTest {
-	 * 	// ...
+	 *     // ...
+	 * }
+	 * </pre>
+	 * 
+	 * <p>Similarly, in the following example that uses configuration
+	 * classes, the
+	 * {@link org.springframework.context.ApplicationContext ApplicationContext}
+	 * for {@code ExtendedTest} will be loaded from the
+	 * {@code BaseConfig} <strong>and</strong> {@code ExtendedConfig} 
+	 * configuration classes, in that order. Beans defined in
+	 * {@code ExtendedConfig} may therefore override those defined in
+	 * {@code BaseConfig}.
+	 * <pre class="code">
+	 * &#064;ContextConfiguration(classes=BaseConfig.class, loader=AnnotationConfigContextLoader.class)
+	 * public class BaseTest {
+	 *     // ...
+	 * }
+	 * 
+	 * &#064;ContextConfiguration(classes=ExtendedConfig.class, loader=AnnotationConfigContextLoader.class)
+	 * public class ExtendedTest extends BaseTest {
+	 *     // ...
 	 * }
 	 * </pre>
-	 * If <code>inheritLocations</code> is set to <code>false</code>, the
-	 * resource locations for the annotated class will <em>shadow</em> and
-	 * effectively replace any resource locations defined by a superclass.
 	 */
 	boolean inheritLocations() default true;
 
 	/**
 	 * The type of {@link ContextLoader} to use for loading an
 	 * {@link org.springframework.context.ApplicationContext ApplicationContext}.
+	 * 
 	 * <p>If not specified, the loader will be inherited from the first superclass
 	 * which is annotated with <code>&#064;ContextConfiguration</code> and specifies
 	 * an explicit loader. If no class in the hierarchy specifies an explicit
 	 * loader, a default loader will be used instead.
+	 * 
 	 * <p>The default concrete implementation chosen at runtime will be
 	 * {@link org.springframework.test.context.support.GenericXmlContextLoader GenericXmlContextLoader}.
 	 * Also check out {@link org.springframework.test.context.support.AbstractContextLoader AbstractContextLoader}'s

org.springframework.test/src/main/java/org/springframework/test/context/ContextLoader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2008 the original author or authors.
+ * Copyright 2002-2011 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.
@@ -33,8 +33,8 @@ import org.springframework.context.ApplicationContext;
  *
  * <p>Spring provides the following out-of-the-box implementations:
  * <ul>
- * <li>{@link org.springframework.test.context.support.AnnotationConfigContextLoader AnnotationConfigContextLoader}</li>
  * <li>{@link org.springframework.test.context.support.GenericXmlContextLoader GenericXmlContextLoader}</li>
+ * <li>{@link org.springframework.test.context.support.AnnotationConfigContextLoader AnnotationConfigContextLoader}</li>
  * <li>{@link org.springframework.test.context.support.GenericPropertiesContextLoader GenericPropertiesContextLoader}</li>
  * </ul>
  *

org.springframework.test/src/main/java/org/springframework/test/context/ContextLoaderUtils.java

@@ -38,7 +38,7 @@ import org.springframework.util.StringUtils;
  * @since 3.1
  * @see ContextLoader
  */
-public abstract class ContextLoaderUtils {
+abstract class ContextLoaderUtils {
 
 	// TODO Consider refactoring ContextLoaderUtils into a stateful
 	// ContextLoaderResolver.
@@ -55,6 +55,7 @@ public abstract class ContextLoaderUtils {
 	 * Resolves the {@link ContextLoader}
 	 * {@link Class} to use for the supplied {@link Class testClass} and
 	 * then instantiates and returns that <code>ContextLoader</code>.
+	 * 
 	 * <p>If the supplied <code>defaultContextLoaderClassName</code> is
 	 * <code>null</code> or <em>empty</em>, the <em>standard</em>
 	 * default context loader class name ({@value #STANDARD_DEFAULT_CONTEXT_LOADER_CLASS_NAME})
@@ -68,7 +69,7 @@ public abstract class ContextLoaderUtils {
 	 * <code>testClass</code> 
 	 * @see #resolveContextLoaderClass(Class, String)
 	 */
-	public static ContextLoader resolveContextLoader(Class<?> testClass, String defaultContextLoaderClassName) {
+	static ContextLoader resolveContextLoader(Class<?> testClass, String defaultContextLoaderClassName) {
 		Assert.notNull(testClass, "Test class must not be null");
 
 		if (!StringUtils.hasText(defaultContextLoaderClassName)) {
@@ -156,6 +157,7 @@ public abstract class ContextLoaderUtils {
 	 * {@link Class class}, using the supplied {@link ContextLoader} to
 	 * {@link ContextLoader#processLocations(Class, String...) process} the
 	 * locations.
+	 * 
 	 * <p>Note that the {@link ContextConfiguration#inheritLocations()
 	 * inheritLocations} flag of {@link ContextConfiguration
 	 * &#064;ContextConfiguration} will be taken into consideration.
@@ -171,7 +173,7 @@ public abstract class ContextLoaderUtils {
 	 * @throws IllegalArgumentException if {@link ContextConfiguration
 	 * &#064;ContextConfiguration} is not <em>present</em> on the supplied class
 	 */
-	public static String[] resolveContextLocations(ContextLoader contextLoader, Class<?> clazz) {
+	static String[] resolveContextLocations(ContextLoader contextLoader, Class<?> clazz) {
 		Assert.notNull(contextLoader, "ContextLoader must not be null");
 		Assert.notNull(clazz, "Class must not be null");
 
@@ -210,6 +212,7 @@ public abstract class ContextLoaderUtils {
 
 	/**
 	 * Strategy interface for resolving application context resource locations.
+	 * 
 	 * <p>The semantics of the resolved locations are implementation-dependent.
 	 */
 	private static interface LocationsResolver {
@@ -236,6 +239,7 @@ public abstract class ContextLoaderUtils {
 		 * Resolves path-based resources from the {@link ContextConfiguration#locations() locations}
 		 * and {@link ContextConfiguration#value() value} attributes of the supplied
 		 * {@link ContextConfiguration} annotation.
+		 * 
 		 * <p>Ignores the {@link ContextConfiguration#classes() classes} attribute. 
 		 * @throws IllegalStateException if both the locations and value
 		 * attributes have been declared
@@ -270,6 +274,7 @@ public abstract class ContextLoaderUtils {
 		/**
 		 * Resolves class names from the {@link ContextConfiguration#classes() classes}
 		 * attribute of the supplied {@link ContextConfiguration} annotation.
+		 * 
 		 * <p>Ignores the {@link ContextConfiguration#locations() locations}
 		 * and {@link ContextConfiguration#value() value} attributes.
 		 */

org.springframework.test/src/main/java/org/springframework/test/context/ResourceTypeAwareContextLoader.java

@@ -20,9 +20,11 @@ package org.springframework.test.context;
  * Extension of the {@link ContextLoader} API for context loaders that
  * are aware of the type of context configuration resources that they
  * support.
+ * 
  * <p>Prior to Spring 3.1, context loaders supported only String-based
  * resource locations; as of Spring 3.1 context loaders may choose to
  * support either String-based or Class-based resources (but not both).
+ * 
  * <p>If a context loader does not implement this interface it is assumed
  * that the loader supports String-based resource locations.
  *
@@ -34,6 +36,7 @@ public interface ResourceTypeAwareContextLoader extends ContextLoader {
 	/**
 	 * Enumeration of context configuration resource types that a given
 	 * <code>ContextLoader</code> can support.
+	 * 
 	 * <p>The enum constants have a one-to-one correlation to attributes
 	 * of the {@link ContextConfiguration} annotation.
 	 */

org.springframework.test/src/main/java/org/springframework/test/context/support/AnnotationConfigContextLoader.java

@@ -58,10 +58,12 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader
 	 * Registers {@link org.springframework.context.annotation.Configuration configuration classes}
 	 * in the supplied {@link AnnotationConfigApplicationContext} from the specified
 	 * class names.
+	 * 
 	 * <p>Each class name must be the <em>fully qualified class name</em> of an
 	 * annotated configuration class, component, or feature specification. The
 	 * <code>AnnotationConfigApplicationContext</code> assumes the responsibility
 	 * of loading the appropriate bean definitions.
+	 * 
 	 * <p>Note that this method does not call {@link #createBeanDefinitionReader}.
 	 * @param context the context in which the configuration classes should be registered
 	 * @param classNames the names of configuration classes to register in the context
@@ -106,6 +108,7 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader
 	/**
 	 * Generates the default {@link org.springframework.context.annotation.Configuration configuration class}
 	 * names array based on the supplied class.
+	 * 
 	 * <p>For example, if the supplied class is <code>com.example.MyTest</code>,
 	 * the generated array will contain a single string with a value of
 	 * &quot;com.example.MyTest<code>&lt;suffix&gt;</code>&quot;,