Merge from sbrannen/SPR-9955

* SPR-9955:
  Introduce context bootstrap strategy in the TCF

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