Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[SPR-6184] completed JavaDoc for @ContextConfiguration.

Browse Source
This commit is contained in:
Sam Brannen
2011-04-10 23:20:05 +00:00
parent 36970115ed
commit 68b4687311
5 changed files with 96 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
org.springframework.test/src/main/java/org/springframework/test/context/ContextConfiguration.java
View File

@@ -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

4
org.springframework.test/src/main/java/org/springframework/test/context/ContextLoader.java
View File

@@ -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>
*

11
org.springframework.test/src/main/java/org/springframework/test/context/ContextLoaderUtils.java
View File

@@ -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.
*/

3
org.springframework.test/src/main/java/org/springframework/test/context/ResourceTypeAwareContextLoader.java
View File

@@ -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.
*/

3
org.springframework.test/src/main/java/org/springframework/test/context/support/AnnotationConfigContextLoader.java
View File

@@ -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;,