Introduce context bootstrap strategy in the TCF

Work done in conjunction with SPR-5243 and SPR-4588 introduced physical
package cycles in the spring-test module. The work performed in
conjunction with SPR-9924 uses reflection to resolve these physical
package cycles; however, prior to this commit the logical package
cycles still remain.

Furthermore, over time it has become apparent that the Spring
TestContext Framework (TCF) could better serve application developers
and especially third-party framework developers by providing a more
flexible mechanism for "bootstrapping" the TCF. For example, prior to
this commit, default TestExecutionListeners could only be registered by
subclassing TestContextManager (and SpringJUnit4ClassRunner if using
JUnit). Similarly, the default ContextLoader could only be set by
subclassing SpringJUnit4ClassRunner for JUnit and by copying and
modifying AbstractTestNGSpringContextTests for TestNG.

This commit addresses the aforementioned issues by introducing a
bootstrap strategy in the TestContext framework that is responsible for
determining default TestExecutionListeners and the default
ContextLoader in an extensible fashion. The new TestContextBootstrapper
SPI also provides a mechanism for supporting various types of
MergedContextConfiguration depending on the feature set of the context
loaders supported by the strategy.

The following provides an overview of the most significant changes in
this commit.

 - Introduced TestContextBootstrapper strategy SPI, BootstrapContext,
   and @BootstrapWith.

 - Introduced AbstractTestContextBootstrapper,
   DefaultTestContextBootstrapper, and WebTestContextBootstrapper
   implementations of the TestContextBootstrapper SPI and extracted
   related reflection code from ContextLoaderUtils & TestContextManager.

 - Introduced BootstrapUtils for retrieving the TestContextBootstrapper
   from @BootstrapWith, falling back to a default if @BootstrapWith is
   not present.

 - @WebAppConfiguration is now annotated with
   @BootstrapWith(WebTestContextBootstrapper.class).

 - CacheAwareContextLoaderDelegate is now an interface with a new
   DefaultCacheAwareContextLoaderDelegate implementation class.

 - Introduced closeContext(MergedContextConfiguration, HierarchyMode) in
   CacheAwareContextLoaderDelegate.

 - DefaultTestContext now uses CacheAwareContextLoaderDelegate instead
   of interacting directly with the ContextCache.

 - DefaultTestContext now delegates to a TestContextBootstrapper for
   building the MergedContextConfiguration.

 - TestContextManager now delegates to TestContextBootstrapper for
   retrieving TestExecutionListeners.

 - Deleted TestContextManager(Class, String) constructor and
   SpringJUnit4ClassRunner.getDefaultContextLoaderClassName(Class)
   method since default ContextLoader support is now implemented by
   TestContextBootstrappers.

 - Extracted ActiveProfilesUtils from ContextLoaderUtils.

 - Extracted ApplicationContextInitializerUtils from ContextLoaderUtils.

 - MetaAnnotationUtils is now a public utility class in the test.util
   package.

 - Removed restriction in @activeprofiles that a custom resolver cannot
   be used with the 'value' or 'profiles' attributes.

 - Introduced DefaultActiveProfilesResolver.

Issue: SPR-9955

Author: sbrannen

spring-test/src/main/java/org/springframework/test/context/ActiveProfiles.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.
@@ -50,29 +50,23 @@
 	/**
 	 * Alias for {@link #profiles}.
 	 *
-	 * <p>This attribute may <strong>not</strong> be used in conjunction
-	 * with {@link #profiles} or {@link #resolver}, but it may be used
-	 * <em>instead</em> of them.
+	 * <p>This attribute may <strong>not</strong> be used in conjunction with
+	 * {@link #profiles}, but it may be used <em>instead</em> of {@link #profiles}.
 	 */
 	String[] value() default {};
 
 	/**
 	 * The bean definition profiles to activate.
 	 *
-	 * <p>This attribute may <strong>not</strong> be used in conjunction
-	 * with {@link #value} or {@link #resolver}, but it may be used
-	 * <em>instead</em> of them.
+	 * <p>This attribute may <strong>not</strong> be used in conjunction with
+	 * {@link #value}, but it may be used <em>instead</em> of {@link #value}.
 	 */
 	String[] profiles() default {};
 
 	/**
 	 * The type of {@link ActiveProfilesResolver} to use for resolving the active
 	 * bean definition profiles programmatically.
 	 *
-	 * <p>This attribute may <strong>not</strong> be used in conjunction
-	 * with {@link #profiles} or {@link #value}, but it may be used <em>instead</em>
-	 * of them in order to resolve the active profiles programmatically.
-	 *
 	 * @since 4.0
 	 * @see ActiveProfilesResolver
 	 */

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

@@ -0,0 +1,42 @@
+/*
+ * 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.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.test.context;
+
+/**
+ * {@code BootstrapContext} encapsulates the context in which the <em>Spring
+ * TestContext Framework</em> is bootstrapped.
+ *
+ * @author Sam Brannen
+ * @since 4.1
+ * @see BootstrapWith
+ * @see TestContextBootstrapper
+ */
+public interface BootstrapContext {
+
+	/**
+	 * Get the {@link Class test class} for this bootstrap context.
+	 * @return the test class (never {@code null})
+	 */
+	Class<?> getTestClass();
+
+	/**
+	 * Get the {@link CacheAwareContextLoaderDelegate} to use for transparent
+	 * interaction with the <em>context cache</em>.
+	 */
+	CacheAwareContextLoaderDelegate getCacheAwareContextLoaderDelegate();
+
+}

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

@@ -0,0 +1,92 @@
+/*
+ * 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.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.test.context;
+
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
+import org.springframework.util.ClassUtils;
+
+import static org.springframework.beans.BeanUtils.*;
+import static org.springframework.core.annotation.AnnotationUtils.*;
+
+/**
+ * {@code BootstrapUtils} is a collection of utility methods to assist with
+ * bootstrapping the <em>Spring TestContext Framework</em>.
+ *
+ * @author Sam Brannen
+ * @since 4.1
+ * @see BootstrapWith
+ * @see BootstrapContext
+ * @see TestContextBootstrapper
+ */
+abstract class BootstrapUtils {
+
+	private static final String DEFAULT_TEST_CONTEXT_BOOTSTRAPPER_CLASS_NAME = "org.springframework.test.context.support.DefaultTestContextBootstrapper";
+
+	private static final Log logger = LogFactory.getLog(BootstrapUtils.class);
+
+
+	private BootstrapUtils() {
+		/* no-op */
+	}
+
+	/**
+	 * Resolve the {@link TestContextBootstrapper} type for the test class in the
+	 * supplied {@link BootstrapContext}, instantiate it, and provide it a reference
+	 * to the {@link BootstrapContext}.
+	 *
+	 * <p>If the {@link BootstrapWith @BootstrapWith} annotation is present on
+	 * the test class, either directly or as a meta-annotation, then its
+	 * {@link BootstrapWith#value value} will be used as the bootstrapper type.
+	 * Otherwise, the {@link org.springframework.test.context.support.DefaultTestContextBootstrapper
+	 * DefaultTestContextBootstrapper} will be used.
+	 *
+	 * @param bootstrapContext the bootstrap context to use
+	 * @return a fully configured {@code TestContextBootstrapper}
+	 */
+	@SuppressWarnings("unchecked")
+	static TestContextBootstrapper resolveTestContextBootstrapper(BootstrapContext bootstrapContext) {
+		Class<?> testClass = bootstrapContext.getTestClass();
+
+		Class<? extends TestContextBootstrapper> clazz = null;
+		try {
+			BootstrapWith bootstrapWith = findAnnotation(testClass, BootstrapWith.class);
+			if (bootstrapWith != null && !TestContextBootstrapper.class.equals(bootstrapWith.value())) {
+				clazz = bootstrapWith.value();
+			}
+			else {
+				clazz = (Class<? extends TestContextBootstrapper>) ClassUtils.forName(
+					DEFAULT_TEST_CONTEXT_BOOTSTRAPPER_CLASS_NAME, BootstrapUtils.class.getClassLoader());
+			}
+
+			if (logger.isDebugEnabled()) {
+				logger.debug(String.format("Instantiating TestContextBootstrapper from class [%s]", clazz.getName()));
+			}
+
+			TestContextBootstrapper testContextBootstrapper = instantiateClass(clazz, TestContextBootstrapper.class);
+			testContextBootstrapper.setBootstrapContext(bootstrapContext);
+
+			return testContextBootstrapper;
+		}
+		catch (Throwable t) {
+			throw new IllegalStateException("Could not load TestContextBootstrapper [" + clazz
+					+ "]. Specify @BootstrapWith's 'value' attribute "
+					+ "or make the default bootstrapper class available.", t);
+		}
+	}
+
+}

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

@@ -0,0 +1,50 @@
+/*
+ * 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.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.test.context;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * {@code @BootstrapWith} defines class-level metadata that is used to determine
+ * how to bootstrap the <em>Spring TestContext Framework</em>.
+ *
+ * <p>This annotation may also be used as a <em>meta-annotation</em> to create
+ * custom <em>composed annotations</em>.
+ *
+ * @author Sam Brannen
+ * @since 4.1
+ * @see BootstrapContext
+ * @see TestContextBootstrapper
+ */
+@Documented
+@Inherited
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface BootstrapWith {
+
+	/**
+	 * The {@link TestContextBootstrapper} to use to bootstrap the <em>Spring
+	 * TestContext Framework</em>.
+	 */
+	Class<? extends TestContextBootstrapper> value() default TestContextBootstrapper.class;
+
+}

spring-test/src/main/java/org/springframework/test/context/CacheAwareContextLoaderDelegate.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.
@@ -16,97 +16,61 @@
 
 package org.springframework.test.context;
 
-import org.apache.commons.logging.Log;
-import org.apache.commons.logging.LogFactory;
 import org.springframework.context.ApplicationContext;
-import org.springframework.util.Assert;
+import org.springframework.context.ConfigurableApplicationContext;
+import org.springframework.test.annotation.DirtiesContext.HierarchyMode;
 
 /**
- * {@code CacheAwareContextLoaderDelegate} loads application contexts from
- * {@link MergedContextConfiguration} by delegating to the
- * {@link ContextLoader} configured in the {@code MergedContextConfiguration}
- * and interacting transparently with the {@link ContextCache} behind the scenes.
+ * A {@code CacheAwareContextLoaderDelegate} is responsible for {@linkplain
+ * #loadContext loading} and {@linkplain #closeContext closing} application
+ * contexts, interacting transparently with a <em>context cache</em> behind
+ * the scenes.
  *
- * <p>Note: {@code CacheAwareContextLoaderDelegate} does not implement the
+ * <p>Note: {@code CacheAwareContextLoaderDelegate} does not extend the
  * {@link ContextLoader} or {@link SmartContextLoader} interface.
  *
  * @author Sam Brannen
  * @since 3.2.2
  */
-public class CacheAwareContextLoaderDelegate {
-
-	private static final Log logger = LogFactory.getLog(CacheAwareContextLoaderDelegate.class);
-
-	private final ContextCache contextCache;
-
-
-	CacheAwareContextLoaderDelegate(ContextCache contextCache) {
-		Assert.notNull(contextCache, "ContextCache must not be null");
-		this.contextCache = contextCache;
-	}
+public interface CacheAwareContextLoaderDelegate {
 
 	/**
-	 * Load the {@code ApplicationContext} for the supplied merged context
-	 * configuration. Supports both the {@link SmartContextLoader} and
-	 * {@link ContextLoader} SPIs.
-	 * @throws Exception if an error occurs while loading the application context
-	 */
-	private ApplicationContext loadContextInternal(MergedContextConfiguration mergedContextConfiguration)
-			throws Exception {
-		ContextLoader contextLoader = mergedContextConfiguration.getContextLoader();
-		Assert.notNull(contextLoader, "Cannot load an ApplicationContext with a NULL 'contextLoader'. "
-				+ "Consider annotating your test class with @ContextConfiguration or @ContextHierarchy.");
-
-		ApplicationContext applicationContext;
-
-		if (contextLoader instanceof SmartContextLoader) {
-			SmartContextLoader smartContextLoader = (SmartContextLoader) contextLoader;
-			applicationContext = smartContextLoader.loadContext(mergedContextConfiguration);
-		}
-		else {
-			String[] locations = mergedContextConfiguration.getLocations();
-			Assert.notNull(locations, "Cannot load an ApplicationContext with a NULL 'locations' array. "
-					+ "Consider annotating your test class with @ContextConfiguration or @ContextHierarchy.");
-			applicationContext = contextLoader.loadContext(locations);
-		}
-
-		return applicationContext;
-	}
-
-	/**
-	 * Load the {@link ApplicationContext application context} for the supplied
-	 * merged context configuration.
+	 * Load the {@linkplain ApplicationContext application context} for the supplied
+	 * {@link MergedContextConfiguration} by delegating to the {@link ContextLoader}
+	 * configured in the given {@code MergedContextConfiguration}.
+	 *
+	 * <p>If the context is present in the <em>context cache</em> it will simply
+	 * be returned; otherwise, it will be loaded, stored in the cache, and returned.
 	 *
-	 * <p>If the context is present in the cache it will simply be returned;
-	 * otherwise, it will be loaded, stored in the cache, and returned.
+	 * @param mergedContextConfiguration the merged context configuration to use
+	 * to load the application context; never {@code null}
 	 * @return the application context
 	 * @throws IllegalStateException if an error occurs while retrieving or
 	 * loading the application context
 	 */
-	public ApplicationContext loadContext(MergedContextConfiguration mergedContextConfiguration) {
-		synchronized (contextCache) {
-			ApplicationContext context = contextCache.get(mergedContextConfiguration);
-			if (context == null) {
-				try {
-					context = loadContextInternal(mergedContextConfiguration);
-					if (logger.isDebugEnabled()) {
-						logger.debug(String.format("Storing ApplicationContext in cache under key [%s].",
-							mergedContextConfiguration));
-					}
-					contextCache.put(mergedContextConfiguration, context);
-				}
-				catch (Exception ex) {
-					throw new IllegalStateException("Failed to load ApplicationContext", ex);
-				}
-			}
-			else {
-				if (logger.isDebugEnabled()) {
-					logger.debug(String.format("Retrieved ApplicationContext from cache with key [%s].",
-						mergedContextConfiguration));
-				}
-			}
-			return context;
-		}
-	}
+	ApplicationContext loadContext(MergedContextConfiguration mergedContextConfiguration);
+
+	/**
+	 * Remove the {@linkplain ApplicationContext application context} for the
+	 * supplied {@link MergedContextConfiguration} from the <em>context cache</em>
+	 * and {@linkplain ConfigurableApplicationContext#close() close} it if it is
+	 * an instance of {@link ConfigurableApplicationContext}.
+	 *
+	 * <p>The semantics of the supplied {@code HierarchyMode} must be honored when
+	 * removing the context from the cache. See the Javadoc for {@link HierarchyMode}
+	 * for details.
+	 *
+	 * <p>Generally speaking, this method should only be called if the state of
+	 * a singleton bean has been changed (potentially affecting future interaction
+	 * with the context) or if the context needs to be prematurely removed from
+	 * the cache.
+	 *
+	 * @param mergedContextConfiguration the merged context configuration for the
+	 * application context to close; never {@code null}
+	 * @param hierarchyMode the hierarchy mode; may be {@code null} if the context
+	 * is not part of a hierarchy
+	 * @since 4.1
+	 */
+	void closeContext(MergedContextConfiguration mergedContextConfiguration, HierarchyMode hierarchyMode);
 
 }

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

@@ -91,6 +91,7 @@
 	 *
 	 * <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
 	 */
@@ -120,6 +121,7 @@
 	 *
 	 * <p>This attribute may <strong>not</strong> be used in conjunction with
 	 * {@link #value}, but it may be used instead of {@link #value}.
+	 *
 	 * @since 2.5
 	 * @see #inheritLocations
 	 */