From ef79d7cc8abbe0722f10f2ce8d60f99e0cae9aaf Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Sat, 9 Apr 2011 14:34:16 +0000 Subject: [PATCH] [SPR-6184] Fleshed out JavaDoc for ResourceTypeAwareContextLoader and ContextLoaderUtils. --- .../test/context/ContextLoaderUtils.java | 56 ++++++++++++++++--- .../ResourceTypeAwareContextLoader.java | 29 ++++++---- 2 files changed, 66 insertions(+), 19 deletions(-) diff --git a/org.springframework.test/src/main/java/org/springframework/test/context/ContextLoaderUtils.java b/org.springframework.test/src/main/java/org/springframework/test/context/ContextLoaderUtils.java index 8ca43ff18a0..829e430abd3 100644 --- a/org.springframework.test/src/main/java/org/springframework/test/context/ContextLoaderUtils.java +++ b/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}. - * - *

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 ContextLoader. + *

If the supplied defaultContextLoaderClassName is + * null or empty, the standard + * 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 ContextLoader * should be resolved (must not be null) * @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}. *

    *
  1. If the {@link ContextConfiguration#loader() loader} attribute of @@ -200,13 +208,38 @@ public abstract class ContextLoaderUtils { } + /** + * Strategy interface for resolving application context resource locations. + *

    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 ContextConfiguration + * for which to resolve resource locations + * @param declaringClass the class that declared ContextConfiguration + * @return an array of application context resource locations + * (can be null or empty) + */ String[] resolveLocations(ContextConfiguration contextConfiguration, Class declaringClass); } + /** + * LocationsResolver 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. + *

    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 { } } + /** + * LocationsResolver 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. + *

    Ignores the {@link ContextConfiguration#locations() locations} + * and {@link ContextConfiguration#value() value} attributes. + */ public String[] resolveLocations(ContextConfiguration contextConfiguration, Class declaringClass) { String[] classNames = null; diff --git a/org.springframework.test/src/main/java/org/springframework/test/context/ResourceTypeAwareContextLoader.java b/org.springframework.test/src/main/java/org/springframework/test/context/ResourceTypeAwareContextLoader.java index b0254975683..80be7ace0e8 100644 --- a/org.springframework.test/src/main/java/org/springframework/test/context/ResourceTypeAwareContextLoader.java +++ b/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. + *

    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). + *

    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 + * ContextLoader can support. + *

    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 - * ContextLoader. - * - * @return the context resource type supported by this ContextLoader + * @return the context configuration resource type supported by this ContextLoader */ ResourceType getResourceType();