From 102674be20694698b904f7be11b1421f18abffaa Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Mon, 20 Jun 2011 19:44:30 +0000 Subject: [PATCH] [SPR-8386] Completed JavaDoc for ContextLoaderUtils regarding the SmartContextLoader SPI. --- .../test/context/ContextLoaderUtils.java | 152 +++++++++--------- 1 file changed, 80 insertions(+), 72 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 1601ff921d..295ce15d9f 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 @@ -32,12 +32,14 @@ import org.springframework.util.ObjectUtils; import org.springframework.util.StringUtils; /** - * Utility methods for working with {@link ContextLoader ContextLoaders}, - * resource locations and classes, and active bean definition profiles. + * Utility methods for working with {@link ContextLoader ContextLoaders} and + * {@link SmartContextLoader SmartContextLoaders} and resolving resource locations, + * configuration classes, and active bean definition profiles. * * @author Sam Brannen * @since 3.1 * @see ContextLoader + * @see SmartContextLoader * @see ContextConfiguration * @see ContextConfigurationAttributes * @see ActiveProfiles @@ -47,11 +49,31 @@ abstract class ContextLoaderUtils { 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 String DEFAULT_CONTEXT_LOADER_CLASS_NAME = "org.springframework.test.context.support.GenericXmlContextLoader"; + private ContextLoaderUtils() { + /* no-op */ + } + /** - * TODO Document resolveContextConfigurationAttributes(). + * 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 + * 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, + * including configuration attributes from superclasses if appropriate + * (never null) + * @throws IllegalArgumentException if the supplied class is null + * or if {@link ContextConfiguration @ContextConfiguration} is not + * present on the supplied class */ static List resolveContextConfigurationAttributes(Class clazz) { Assert.notNull(clazz, "Class must not be null"); @@ -88,25 +110,24 @@ abstract class ContextLoaderUtils { } /** - * Resolves the {@link ContextLoader} {@link Class} to use for the - * supplied {@link Class testClass} and then instantiates and returns - * that ContextLoader. - * + * Resolve the {@link ContextLoader} {@link Class class} to use for the + * supplied {@link Class testClass} and {@link ContextConfigurationAttributes} + * and then instantiate and return that {@code ContextLoader}. *

If the supplied defaultContextLoaderClassName is * null or empty, the standard - * default context loader class name ({@value #STANDARD_DEFAULT_CONTEXT_LOADER_CLASS_NAME}) + * default context loader class name {@value #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 + * {@link #resolveContextLoaderClass()}. + * @param testClass the test class for which the {@code ContextLoader} * should be resolved (must not be null) - * @param configAttributesList TODO Document configAttributesList parameter + * @param configAttributesList the resolved configuration attributes for the + * test class hierarchy * @param defaultContextLoaderClassName the name of the default - * ContextLoader class to use (may be null) - * - * @return the resolved ContextLoader for the supplied + * {@code ContextLoader} class to use (may be null) + * @return the resolved {@code ContextLoader} for the supplied * testClass (never null) - * @see #resolveContextLoaderClass(Class, String) + * @see #resolveContextLoaderClass() + * @see #resolveContextConfigurationAttributes() */ static ContextLoader resolveContextLoader(Class testClass, List configAttributesList, String defaultContextLoaderClassName) { @@ -114,7 +135,7 @@ abstract class ContextLoaderUtils { Assert.notEmpty(configAttributesList, "ContextConfigurationAttributes list must not be null or empty"); if (!StringUtils.hasText(defaultContextLoaderClassName)) { - defaultContextLoaderClassName = STANDARD_DEFAULT_CONTEXT_LOADER_CLASS_NAME; + defaultContextLoaderClassName = DEFAULT_CONTEXT_LOADER_CLASS_NAME; } Class contextLoaderClass = resolveContextLoaderClass(testClass, configAttributesList, @@ -124,31 +145,33 @@ abstract class ContextLoaderUtils { } /** - * Resolves the {@link ContextLoader} {@link Class} to use for the supplied - * {@link Class test class}. - * + * Resolve the {@link ContextLoader} {@link Class} to use for the supplied + * {@link ContextConfigurationAttributes} list. + *

This method will iterate over the supplied configuration attributes + * and execute the following algorithm: *

    - *
  1. If the {@link ContextConfiguration#loader() loader} attribute of - * {@link ContextConfiguration @ContextConfiguration} is configured - * with an explicit class, that class will be returned.
    2. - *
  2. If a loader class is not specified, the class hierarchy - * will be traversed to find a parent class annotated with - * @ContextConfiguration; go to step #1.
    3. - *
  3. If no explicit loader class is found after traversing - * the class hierarchy, an attempt will be made to load and return the class - * with the supplied defaultContextLoaderClassName.
    4. + *
  4. If {@link ContextConfigurationAttributes#getContextLoaderClass()} + * returns an explicit implementation class, that class will be returned.
    5. + *
  5. If an explicit {@code ContextLoader} implementation class is not + * specified, the next {@link ContextConfigurationAttributes} instance in + * the supplied list will be processed; go to step #1.
    6. + *
  6. If no explicit loader class is found after processing + * all {@link ContextConfigurationAttributes} instances, an attempt will be + * made to load and return the class with the supplied + * defaultContextLoaderClassName.
    7. *
- * - * @param testClass the class for which to resolve the ContextLoader - * class; must not be null - * @param configAttributesList TODO Document configAttributesList parameter + * @param testClass the class for which to resolve the {@code ContextLoader} + * class; used solely for logging purposes; must not be null + * @param configAttributesList the resolved configuration attributes for the + * test class hierarchy; must not be null or empty * @param defaultContextLoaderClassName the name of the default - * ContextLoader class to use; must not be null or empty - * - * @return the ContextLoader class to use for the specified class + * {@code ContextLoader} class to use; must not be null or empty + * @return the {@code ContextLoader} class to use for the specified class * (never null) - * @throws IllegalArgumentException if {@link ContextConfiguration - * @ContextConfiguration} is not present on the supplied class + * @throws IllegalArgumentException if {@code @ContextConfiguration} is not + * present on the supplied test class + * @see #resolveContextLoader() + * @see #resolveContextConfigurationAttributes() */ @SuppressWarnings("unchecked") static Class resolveContextLoaderClass(Class testClass, @@ -191,20 +214,18 @@ abstract class ContextLoaderUtils { } /** - * Resolves active bean definition profiles for the supplied - * {@link Class class}. - * - *

Note that the {@link ActiveProfiles#inheritProfiles() inheritProfiles} + * 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 * 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 * active profiles from superclasses if appropriate (never null) + * @see org.springframework.test.context.ActiveProfiles + * @see org.springframework.context.annotation.Profile */ static String[] resolveActiveProfiles(Class clazz) { Assert.notNull(clazz, "Class must not be null"); @@ -256,34 +277,21 @@ abstract class ContextLoaderUtils { return StringUtils.toStringArray(activeProfiles); } - /* - * Resolves {@link ApplicationContext} resource locations for the supplied - * {@link Class class}, using the supplied {@link ContextLoader} to {@link - * ContextLoader#processLocations(Class, String...) process} the locations. - * - *

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, locations defined in the annotated class will be - * appended to the locations defined in superclasses. - * - * @param contextLoader the ContextLoader to use for processing the - * locations (must not be null) - * - * @param clazz the class for which to resolve the resource locations (must - * not be null) - * - * @return the list of ApplicationContext resource locations for the - * specified class, including locations from superclasses if appropriate - * (never null) - * - * @throws IllegalArgumentException if {@link ContextConfiguration - * @ContextConfiguration} is not present on the supplied class - */ - /** - * TODO Document buildMergedContextConfiguration(). + * 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 + * {@code ContextLoader} class to use (may be null) + * @return the merged context configuration + * @see #resolveContextConfigurationAttributes() + * @see #resolveContextLoader() + * @see SmartContextLoader#processContextConfiguration() + * @see ContextLoader#processLocations() + * @see #resolveActiveProfiles() + * @see MergedContextConfiguration */ static MergedContextConfiguration buildMergedContextConfiguration(Class testClass, String defaultContextLoaderClassName) {