[SPR-6184] Fleshed out JavaDoc for ResourceTypeAwareContextLoader and ContextLoaderUtils.

git-svn-id: https://src.springframework.org/svn/spring-framework/trunk@4202 50f2f4bb-b051-0410-bef5-90022cba6387

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

@@ -31,9 +31,8 @@ import org.springframework.util.ObjectUtils;
 import org.springframework.util.StringUtils;
 
 /**
- * Utility methods for working with {@link ContextLoader ContextLoaders}.
- * 
- * <p>TODO Consider refactoring into a stateful ContextLoaderResolver.
+ * Utility methods for working with {@link ContextLoader ContextLoaders}
+ * and resource locations.
  * 
  * @author Sam Brannen
  * @since 3.1
@@ -41,17 +40,26 @@ import org.springframework.util.StringUtils;
  */
 public abstract class ContextLoaderUtils {
 
+	// TODO Consider refactoring ContextLoaderUtils into a stateful
+	// ContextLoaderResolver.
+
 	private static final Log logger = LogFactory.getLog(ContextLoaderUtils.class);
 
 	private static final String STANDARD_DEFAULT_CONTEXT_LOADER_CLASS_NAME = "org.springframework.test.context.support.GenericXmlContextLoader";
 
-	private static final ClassNameLocationsResolver classNameLocationsResolver = new ClassNameLocationsResolver();
 	private static final ResourcePathLocationsResolver resourcePathLocationsResolver = new ResourcePathLocationsResolver();
+	private static final ClassNameLocationsResolver classNameLocationsResolver = new ClassNameLocationsResolver();
 
 
 	/**
-	 * TODO Document resolveContextLoader().
-	 *
+	 * 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})
+	 * will be used. For details on the class resolution process, see
+	 * {@link #resolveContextLoaderClass(Class, String)}.
 	 * @param testClass the test class for which the <code>ContextLoader</code>
 	 * should be resolved (must not be <code>null</code>)
 	 * @param defaultContextLoaderClassName the name of the default
@@ -74,7 +82,7 @@ public abstract class ContextLoaderUtils {
 	}
 
 	/**
-	 * Retrieve the {@link ContextLoader} {@link Class} to use for the supplied
+	 * Resolve the {@link ContextLoader} {@link Class} to use for the supplied
 	 * {@link Class test class}.
 	 * <ol>
 	 * <li>If the {@link ContextConfiguration#loader() loader} attribute of
@@ -200,13 +208,38 @@ 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 {
 
+		/**
+		 * Resolves application context resource locations for the supplied
+		 * {@link ContextConfiguration} annotation and the class which declared it.
+		 * @param contextConfiguration the <code>ContextConfiguration</code>
+		 * for which to resolve resource locations
+		 * @param declaringClass the class that declared <code>ContextConfiguration</code>
+		 * @return an array of application context resource locations
+		 * (can be <code>null</code> or empty)
+		 */
 		String[] resolveLocations(ContextConfiguration contextConfiguration, Class<?> declaringClass);
 	}
 
+	/**
+	 * <code>LocationsResolver</code> that resolves locations as Strings,
+	 * which are assumed to be path-based resources.
+	 */
 	private static final class ResourcePathLocationsResolver implements LocationsResolver {
 
+		/**
+		 * 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
+		 */
 		public String[] resolveLocations(ContextConfiguration contextConfiguration, Class<?> declaringClass) {
 
 			String[] locations = contextConfiguration.locations();
@@ -229,8 +262,17 @@ public abstract class ContextLoaderUtils {
 		}
 	}
 
+	/**
+	 * <code>LocationsResolver</code> that converts classes to fully qualified class names.
+	 */
 	private static final class ClassNameLocationsResolver implements LocationsResolver {
 
+		/**
+		 * 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.
+		 */
 		public String[] resolveLocations(ContextConfiguration contextConfiguration, Class<?> declaringClass) {
 
 			String[] classNames = null;

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

@@ -17,7 +17,14 @@
 package org.springframework.test.context;
 
 /**
- * TODO Document ResourceTypeAwareContextLoader.
+ * 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.
  *
  * @author Sam Brannen
  * @since 3.1
@@ -25,22 +32,23 @@ package org.springframework.test.context;
 public interface ResourceTypeAwareContextLoader extends ContextLoader {
 
 	/**
-	 * TODO Document ResourceType.
+	 * 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.
 	 */
 	public static enum ResourceType {
 
 		/**
 		 * String-based resource locations.
-		 * 
-		 * @see ContextConfiguration#locations()
-		 * @see ContextConfiguration#value()
+		 * @see ContextConfiguration#locations
+		 * @see ContextConfiguration#value
 		 */
 		LOCATIONS,
 
 		/**
-		 * Configuration classes.
-		 * 
-		 * @see ContextConfiguration#classes()
+		 * Configuration class resources.
+		 * @see ContextConfiguration#classes
 		 */
 		CLASSES;
 
@@ -48,10 +56,7 @@ public interface ResourceTypeAwareContextLoader extends ContextLoader {
 
 
 	/**
-	 * Get the application context {@link ResourceType} supported by this
-	 * <code>ContextLoader</code>.
-	 *
-	 * @return the context resource type supported by this ContextLoader
+	 * @return the context configuration resource type supported by this ContextLoader
 	 */
 	ResourceType getResourceType();