Support classes AND locations in @ContextConfiguration

Prior to this commit, the Spring TestContext Framework did not support
the declaration of both 'locations' and 'classes' within
@ContextConfiguration at the same time.

This commit addresses this in the following manner:

 - ContextConfigurationAttributes no longer throws an
   IllegalArgumentException if both 'locations' and 'classes' are
   supplied to its constructor.

 - Concrete SmartContextLoader implementations now validate the
   supplied MergedContextConfiguration before attempting to load the
   ApplicationContext. See validateMergedContextConfiguration().

 - Introduced tests for hybrid context loaders like the one used in
   Spring Boot. See HybridContextLoaderTests.

 - Updated the Testing chapter of the reference manual so that it no
   longer states that locations and classes cannot be used
   simultaneously, mentioning Spring Boot as well.

 - The Javadoc for @ContextConfiguration has been updated accordingly.

 - Added hasLocations(), hasClasses(), and hasResources() convenience
   methods to MergedContextConfiguration.

Issue: SPR-11634
(cherry picked from commit 1f017c4)

Author: sbrannen

spring-test/.springBeans

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <beansProjectDescription>
 	<version>1</version>
-	<pluginVersion><![CDATA[3.1.0.201210040510-RELEASE]]></pluginVersion>
+	<pluginVersion><![CDATA[3.5.0.201402030809-M2]]></pluginVersion>
 	<configSuffixes>
 		<configSuffix><![CDATA[xml]]></configSuffix>
 	</configSuffixes>
@@ -11,7 +11,10 @@
 		<config>src/test/java/org/springframework/test/context/junit4/aci/xml/MultipleInitializersXmlConfigTests-context.xml</config>
 		<config>src/test/resources/org/springframework/test/context/web/RequestAndSessionScopedBeansWacTests-context.xml</config>
 		<config>src/test/resources/org/springframework/test/context/hierarchies/web/DispatcherWacRootWacEarTests-context.xml</config>
+		<config>src/test/java/org/springframework/test/context/junit4/hybrid/hybrid-config.xml</config>
 	</configs>
+	<autoconfigs>
+	</autoconfigs>
 	<configSets>
 	</configSets>
 </beansProjectDescription>

spring-test/src/main/java/org/springframework/test/context/ContextConfiguration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 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.
@@ -36,11 +36,14 @@
  *
  * <p>Prior to Spring 3.1, only path-based resource locations were supported.
  * As of Spring 3.1, {@linkplain #loader context loaders} may choose to support
- * either path-based or class-based resources (but not both). Consequently
+ * <em>either</em> path-based <em>or</em> class-based resources. As of Spring
+ * 4.0.4, {@linkplain #loader context loaders} may choose to support path-based
+ * <em>and</em> class-based resources simultaneously. Consequently
  * {@code @ContextConfiguration} can be used to declare either path-based
- * resource locations (via the {@link #locations} or {@link #value}
- * attribute) <i>or</i> annotated classes (via the {@link #classes}
- * attribute).
+ * resource locations (via the {@link #locations} or {@link #value} attribute)
+ * <em>or</em> annotated classes (via the {@link #classes} attribute). Note,
+ * however, that most implementations of {@link SmartContextLoader} only support
+ * a single resource type.
  *
  * <h3>Annotated Classes</h3>
  *
@@ -86,9 +89,8 @@
 	/**
 	 * Alias for {@link #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}.
+	 * <p>This attribute may <strong>not</strong> be used in conjunction with
+	 * {@link #locations}, but it may be used instead of {@link #locations}.
 	 * @since 3.0
 	 * @see #inheritLocations
 	 */
@@ -117,8 +119,7 @@
 	 * loaders.
 	 *
 	 * <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}.
+	 * {@link #value}, but it may be used instead of {@link #value}.
 	 * @since 2.5
 	 * @see #inheritLocations
 	 */
@@ -135,9 +136,6 @@
 	 * <em>annotated classes</em> are specified. See the documentation for
 	 * {@link #loader} for further details regarding default loaders.
 	 *
-	 * <p>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

spring-test/src/main/java/org/springframework/test/context/ContextConfigurationAttributes.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 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.
@@ -29,9 +29,8 @@
 import org.springframework.util.StringUtils;
 
 /**
- * {@code ContextConfigurationAttributes} encapsulates the context
- * configuration attributes declared on a test class via
- * {@link ContextConfiguration @ContextConfiguration}.
+ * {@code ContextConfigurationAttributes} encapsulates the context configuration
+ * attributes declared via {@link ContextConfiguration @ContextConfiguration}.
  *
  * @author Sam Brannen
  * @since 3.1
@@ -111,8 +110,9 @@ public ContextConfigurationAttributes(Class<?> declaringClass, ContextConfigurat
 
 	/**
 	 * Construct a new {@link ContextConfigurationAttributes} instance for the
-	 * supplied {@link ContextConfiguration @ContextConfiguration} annotation and
-	 * the {@linkplain Class test class} that declared it.
+	 * supplied {@link AnnotationAttributes} (parsed from a
+	 * {@link ContextConfiguration @ContextConfiguration} annotation) and
+	 * the {@linkplain Class test class} that declared them.
 	 * @param declaringClass the test class that declared {@code @ContextConfiguration}
 	 * @param annAttrs the annotation attributes from which to retrieve the attributes
 	 */
@@ -140,7 +140,7 @@ public ContextConfigurationAttributes(Class<?> declaringClass, AnnotationAttribu
 	 * @param inheritLocations the {@code inheritLocations} flag declared via {@code @ContextConfiguration}
 	 * @param contextLoaderClass the {@code ContextLoader} class declared via {@code @ContextConfiguration}
 	 * @throws IllegalArgumentException if the {@code declaringClass} or {@code contextLoaderClass} is
-	 * {@code null}, or if the {@code locations} and {@code classes} are both non-empty
+	 * {@code null}
 	 * @deprecated as of Spring 3.2, use
 	 * {@link #ContextConfigurationAttributes(Class, String[], Class[], boolean, Class[], boolean, String, Class)}
 	 * instead
@@ -165,7 +165,7 @@ public ContextConfigurationAttributes(Class<?> declaringClass, String[] location
 	 * @param inheritInitializers the {@code inheritInitializers} flag declared via {@code @ContextConfiguration}
 	 * @param contextLoaderClass the {@code ContextLoader} class declared via {@code @ContextConfiguration}
 	 * @throws IllegalArgumentException if the {@code declaringClass} or {@code contextLoaderClass} is
-	 * {@code null}, or if the {@code locations} and {@code classes} are both non-empty
+	 * {@code null}
 	 */
 	public ContextConfigurationAttributes(Class<?> declaringClass, String[] locations, Class<?>[] classes,
 			boolean inheritLocations,
@@ -190,7 +190,7 @@ public ContextConfigurationAttributes(Class<?> declaringClass, String[] location
 	 * @param name the name of level in the context hierarchy, or {@code null} if not applicable
 	 * @param contextLoaderClass the {@code ContextLoader} class declared via {@code @ContextConfiguration}
 	 * @throws IllegalArgumentException if the {@code declaringClass} or {@code contextLoaderClass} is
-	 * {@code null}, or if the {@code locations} and {@code classes} are both non-empty
+	 * {@code null}
 	 */
 	public ContextConfigurationAttributes(Class<?> declaringClass, String[] locations, Class<?>[] classes,
 			boolean inheritLocations,
@@ -200,14 +200,13 @@ public ContextConfigurationAttributes(Class<?> declaringClass, String[] location
 		Assert.notNull(declaringClass, "declaringClass must not be null");
 		Assert.notNull(contextLoaderClass, "contextLoaderClass must not be null");
 
-		if (!ObjectUtils.isEmpty(locations) && !ObjectUtils.isEmpty(classes)) {
-			String msg = String.format(
+		if (!ObjectUtils.isEmpty(locations) && !ObjectUtils.isEmpty(classes) && logger.isDebugEnabled()) {
+			logger.debug(String.format(
 				"Test class [%s] has been configured with @ContextConfiguration's 'locations' (or 'value') %s "
-						+ "and 'classes' %s attributes. Only one declaration of resources "
-						+ "is permitted per @ContextConfiguration annotation.", declaringClass.getName(),
-				ObjectUtils.nullSafeToString(locations), ObjectUtils.nullSafeToString(classes));
-			logger.error(msg);
-			throw new IllegalArgumentException(msg);
+						+ "and 'classes' %s attributes. Most SmartContextLoader implementations support "
+						+ "only one declaration of resources per @ContextConfiguration annotation.",
+				declaringClass.getName(), ObjectUtils.nullSafeToString(locations),
+				ObjectUtils.nullSafeToString(classes)));
 		}
 
 		this.declaringClass = declaringClass;

spring-test/src/main/java/org/springframework/test/context/MergedContextConfiguration.java

@@ -226,6 +226,46 @@ public Class<?>[] getClasses() {
 		return classes;
 	}
 
+	/**
+	 * Determine if this {@code MergedContextConfiguration} instance has
+	 * path-based resource locations.
+	 *
+	 * @return {@code true} if the {@link #getLocations() locations} array is not empty
+	 * @since 4.0.4
+	 * @see #hasResources()
+	 * @see #hasClasses()
+	 */
+	public boolean hasLocations() {
+		return !ObjectUtils.isEmpty(getLocations());
+	}
+
+	/**
+	 * Determine if this {@code MergedContextConfiguration} instance has
+	 * class-based resources.
+	 *
+	 * @return {@code true} if the {@link #getClasses() classes} array is not empty
+	 * @since 4.0.4
+	 * @see #hasResources()
+	 * @see #hasLocations()
+	 */
+	public boolean hasClasses() {
+		return !ObjectUtils.isEmpty(getClasses());
+	}
+
+	/**
+	 * Determine if this {@code MergedContextConfiguration} instance has
+	 * either path-based resource locations or class-based resources.
+	 *
+	 * @return {@code true} if either the {@link #getLocations() locations}
+	 * or the {@link #getClasses() classes} array is not empty
+	 * @since 4.0.4
+	 * @see #hasLocations()
+	 * @see #hasClasses()
+	 */
+	public boolean hasResources() {
+		return hasLocations() || hasClasses();
+	}
+
 	/**
 	 * Get the merged {@code ApplicationContextInitializer} classes for the
 	 * {@linkplain #getTestClass() test class}.

spring-test/src/main/java/org/springframework/test/context/support/AbstractGenericContextLoader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 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.
@@ -68,6 +68,8 @@ public abstract class AbstractGenericContextLoader extends AbstractContextLoader
 	 * <p>Implementation details:
 	 *
 	 * <ul>
+	 * <li>Calls {@link #validateMergedContextConfiguration(MergedContextConfiguration)}
+	 * to allow subclasses to validate the supplied configuration before proceeding.</li>
 	 * <li>Creates a {@link GenericApplicationContext} instance.</li>
 	 * <li>If the supplied {@code MergedContextConfiguration} references a
 	 * {@linkplain MergedContextConfiguration#getParent() parent configuration},
@@ -106,6 +108,8 @@ public final ConfigurableApplicationContext loadContext(MergedContextConfigurati
 				mergedConfig));
 		}
 
+		validateMergedContextConfiguration(mergedConfig);
+
 		GenericApplicationContext context = new GenericApplicationContext();
 
 		ApplicationContext parent = mergedConfig.getParentApplicationContext();
@@ -123,6 +127,20 @@ public final ConfigurableApplicationContext loadContext(MergedContextConfigurati
 		return context;
 	}
 
+	/**
+	 * Validate the supplied {@link MergedContextConfiguration} with respect to
+	 * what this context loader supports.
+	 * <p>The default implementation is a <em>no-op</em> but can be overridden by
+	 * subclasses as appropriate.
+	 * @param mergedConfig the merged configuration to validate
+	 * @throws IllegalStateException if the supplied configuration is not valid
+	 * for this context loader
+	 * @since 4.0.4
+	 */
+	protected void validateMergedContextConfiguration(MergedContextConfiguration mergedConfig) {
+		/* no-op */
+	}
+
 	/**
 	 * Load a Spring ApplicationContext from the supplied {@code locations}.
 	 *

spring-test/src/main/java/org/springframework/test/context/support/AnnotationConfigContextLoader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2014 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.
@@ -76,9 +76,8 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader
 	 */
 	@Override
 	public void processContextConfiguration(ContextConfigurationAttributes configAttributes) {
-		if (ObjectUtils.isEmpty(configAttributes.getClasses()) && isGenerateDefaultLocations()) {
-			Class<?>[] defaultConfigClasses = detectDefaultConfigurationClasses(configAttributes.getDeclaringClass());
-			configAttributes.setClasses(defaultConfigClasses);
+		if (!configAttributes.hasClasses() && isGenerateDefaultLocations()) {
+			configAttributes.setClasses(detectDefaultConfigurationClasses(configAttributes.getDeclaringClass()));
 		}
 	}
 
@@ -148,6 +147,24 @@ protected String getResourceSuffix() {
 
 	// --- AbstractGenericContextLoader ----------------------------------------
 
+	/**
+	 * Ensure that the supplied {@link MergedContextConfiguration} does not
+	 * contain {@link MergedContextConfiguration#getLocations() locations}.
+	 * @since 4.0.4
+	 * @see AbstractGenericContextLoader#validateMergedContextConfiguration
+	 */
+	@Override
+	protected void validateMergedContextConfiguration(MergedContextConfiguration mergedConfig) {
+		if (mergedConfig.hasLocations()) {
+			String msg = String.format(
+				"Test class [%s] has been configured with @ContextConfiguration's 'locations' (or 'value') attribute %s, "
+						+ "but %s does not support resource locations.", mergedConfig.getTestClass().getName(),
+				ObjectUtils.nullSafeToString(mergedConfig.getLocations()), getClass().getSimpleName());
+			logger.error(msg);
+			throw new IllegalStateException(msg);
+		}
+	}
+
 	/**
 	 * Register classes in the supplied {@link GenericApplicationContext context}
 	 * from the classes in the supplied {@link MergedContextConfiguration}.

spring-test/src/main/java/org/springframework/test/context/support/AnnotationConfigContextLoaderUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2014 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.
@@ -83,7 +83,7 @@ private static boolean isDefaultConfigurationClassCandidate(Class<?> clazz) {
 	 * configuration classes that comply with the constraints required of
 	 * {@code @Configuration} class implementations. If a potential candidate
 	 * configuration class does not meet these requirements, this method will log a
-	 * warning, and the potential candidate class will be ignored.
+	 * debug message, and the potential candidate class will be ignored.
 	 * @param declaringClass the test class that declared {@code @ContextConfiguration}
 	 * @return an array of default configuration classes, potentially empty but
 	 * never {@code null}

spring-test/src/main/java/org/springframework/test/context/support/GenericPropertiesContextLoader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2014 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.
@@ -21,6 +21,8 @@
 import org.springframework.beans.factory.support.BeanDefinitionReader;
 import org.springframework.beans.factory.support.PropertiesBeanDefinitionReader;
 import org.springframework.context.support.GenericApplicationContext;
+import org.springframework.test.context.MergedContextConfiguration;
+import org.springframework.util.ObjectUtils;
 
 /**
  * Concrete implementation of {@link AbstractGenericContextLoader} that reads
@@ -45,8 +47,26 @@ protected BeanDefinitionReader createBeanDefinitionReader(final GenericApplicati
 	 * Returns "{@code -context.properties}".
 	 */
 	@Override
-	public String getResourceSuffix() {
+	protected String getResourceSuffix() {
 		return "-context.properties";
 	}
 
+	/**
+	 * Ensure that the supplied {@link MergedContextConfiguration} does not
+	 * contain {@link MergedContextConfiguration#getClasses() classes}.
+	 * @since 4.0.4
+	 * @see AbstractGenericContextLoader#validateMergedContextConfiguration
+	 */
+	@Override
+	protected void validateMergedContextConfiguration(MergedContextConfiguration mergedConfig) {
+		if (mergedConfig.hasClasses()) {
+			String msg = String.format(
+				"Test class [%s] has been configured with @ContextConfiguration's 'classes' attribute %s, "
+						+ "but %s does not support annotated classes.", mergedConfig.getTestClass().getName(),
+				ObjectUtils.nullSafeToString(mergedConfig.getClasses()), getClass().getSimpleName());
+			logger.error(msg);
+			throw new IllegalStateException(msg);
+		}
+	}
+
 }

spring-test/src/main/java/org/springframework/test/context/support/GenericXmlContextLoader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2014 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.
@@ -19,6 +19,8 @@
 import org.springframework.beans.factory.support.BeanDefinitionReader;
 import org.springframework.beans.factory.xml.XmlBeanDefinitionReader;
 import org.springframework.context.support.GenericApplicationContext;
+import org.springframework.test.context.MergedContextConfiguration;
+import org.springframework.util.ObjectUtils;
 
 /**
  * Concrete implementation of {@link AbstractGenericContextLoader} that reads
@@ -43,8 +45,26 @@ protected BeanDefinitionReader createBeanDefinitionReader(final GenericApplicati
 	 * Returns "{@code -context.xml}".
 	 */
 	@Override
-	public String getResourceSuffix() {
+	protected String getResourceSuffix() {
 		return "-context.xml";
 	}
 
+	/**
+	 * Ensure that the supplied {@link MergedContextConfiguration} does not
+	 * contain {@link MergedContextConfiguration#getClasses() classes}.
+	 * @since 4.0.4
+	 * @see AbstractGenericContextLoader#validateMergedContextConfiguration
+	 */
+	@Override
+	protected void validateMergedContextConfiguration(MergedContextConfiguration mergedConfig) {
+		if (mergedConfig.hasClasses()) {
+			String msg = String.format(
+				"Test class [%s] has been configured with @ContextConfiguration's 'classes' attribute %s, "
+						+ "but %s does not support annotated classes.", mergedConfig.getTestClass().getName(),
+				ObjectUtils.nullSafeToString(mergedConfig.getClasses()), getClass().getSimpleName());
+			logger.error(msg);
+			throw new IllegalStateException(msg);
+		}
+	}
+
 }