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) or 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}. + * + *
This attribute may not 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}. + * *
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. + * *
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. + * + *
This attribute may not 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}. + * + *
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. + * + *
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. * + *
Note that this attribute may not 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 + * inherited. * - * Whether or not {@link #locations() resource locations} from superclasses - * should be inherited. *
The default value is true, which means that an annotated
- * class will inherit 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 inherit 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
- * extending the list of resource locations. In the following
- * example, the {@link org.springframework.context.ApplicationContext ApplicationContext}
- * for ExtendedTest will be loaded from
+ * extending the list of resource locations or configuration
+ * classes.
+ *
+ *
If inheritLocations is set to false, the
+ * resource locations or configuration classes for the annotated class
+ * will shadow and effectively replace any resource locations
+ * or configuration classes defined by a superclass.
+ *
+ *
In the following example that uses path-based resource locations, the + * {@link org.springframework.context.ApplicationContext ApplicationContext} + * for {@code ExtendedTest} will be loaded from * "base-context.xml" and * "extended-context.xml", in that order. Beans defined in * "extended-context.xml" may therefore override those defined in @@ -87,27 +130,46 @@ public @interface ContextConfiguration { *
* @ContextConfiguration("base-context.xml")
* public class BaseTest {
- * // ...
+ * // ...
* }
*
* @ContextConfiguration("extended-context.xml")
* public class ExtendedTest extends BaseTest {
- * // ...
+ * // ...
+ * }
+ *
+ *
+ * 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} and {@code ExtendedConfig} + * configuration classes, in that order. Beans defined in + * {@code ExtendedConfig} may therefore override those defined in + * {@code BaseConfig}. + *
+ * @ContextConfiguration(classes=BaseConfig.class, loader=AnnotationConfigContextLoader.class)
+ * public class BaseTest {
+ * // ...
+ * }
+ *
+ * @ContextConfiguration(classes=ExtendedConfig.class, loader=AnnotationConfigContextLoader.class)
+ * public class ExtendedTest extends BaseTest {
+ * // ...
* }
*
- * If inheritLocations is set to false, the
- * resource locations for the annotated class will shadow 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}.
+ *
* If not specified, the loader will be inherited from the first superclass
* which is annotated with @ContextConfiguration and specifies
* an explicit loader. If no class in the hierarchy specifies an explicit
* loader, a default loader will be used instead.
+ *
*
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 diff --git a/org.springframework.test/src/main/java/org/springframework/test/context/ContextLoader.java b/org.springframework.test/src/main/java/org/springframework/test/context/ContextLoader.java index 3371b880e98..b0c2a4e4044 100644 --- a/org.springframework.test/src/main/java/org/springframework/test/context/ContextLoader.java +++ b/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; * *
Spring provides the following out-of-the-box implementations: *
ContextLoader.
+ *
* If the supplied defaultContextLoaderClassName is
* null or empty, the standard
* default context loader class name ({@value #STANDARD_DEFAULT_CONTEXT_LOADER_CLASS_NAME})
@@ -68,7 +69,7 @@ public abstract class ContextLoaderUtils {
* testClass
* @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.
+ *
*
Note that the {@link ContextConfiguration#inheritLocations() * inheritLocations} flag of {@link ContextConfiguration * @ContextConfiguration} will be taken into consideration. @@ -171,7 +173,7 @@ public abstract class ContextLoaderUtils { * @throws IllegalArgumentException if {@link ContextConfiguration * @ContextConfiguration} is not present 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. + * *
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. + * *
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. + * *
Ignores the {@link ContextConfiguration#locations() locations} * and {@link ContextConfiguration#value() value} attributes. */ 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 80be7ace0e8..6c35da0750b 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 @@ -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. + * *
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.
*
@@ -34,6 +36,7 @@ public interface ResourceTypeAwareContextLoader extends ContextLoader {
/**
* 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. */ diff --git a/org.springframework.test/src/main/java/org/springframework/test/context/support/AnnotationConfigContextLoader.java b/org.springframework.test/src/main/java/org/springframework/test/context/support/AnnotationConfigContextLoader.java index ac9e44893b7..0a9d922a111 100644 --- a/org.springframework.test/src/main/java/org/springframework/test/context/support/AnnotationConfigContextLoader.java +++ b/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. + * *
Each class name must be the fully qualified class name of an
* annotated configuration class, component, or feature specification. The
* AnnotationConfigApplicationContext assumes the responsibility
* of loading the appropriate bean definitions.
+ *
*
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. + * *
For example, if the supplied class is com.example.MyTest,
* the generated array will contain a single string with a value of
* "com.example.MyTest<suffix>",