Improve extensibility of TestContext bootstrapping & context caching

 - DefaultBootstrapContext and DefaultCacheAwareContextLoaderDelegate
   are now public classes in the 'support' subpackage.

 - Introduced getCacheAwareContextLoaderDelegate() in
   AbstractTestContextBootstrapper as an extension point for configuring
   custom ContextCache support.

 - Introduced reflection-based createBootstrapContext() utility method
   in BootstrapUtils; TestContextManager now delegates to BootstrapUtils
   in order to avoid package cycles.

 - Introduced logStatistics() method in the ContextCache API and defined
   statistics logging category as a constant.

 - DefaultCacheAwareContextLoaderDelegate now delegates to
   ContextCache.logStatistics().

Issue: SPR-12683

Author: sbrannen

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

@@ -35,7 +35,8 @@ public interface BootstrapContext {
 
 	/**
 	 * Get the {@link CacheAwareContextLoaderDelegate} to use for transparent
-	 * interaction with the <em>context cache</em>.
+	 * interaction with the {@code ContextCache}.
+	 * @return the context loader delegate (never {@code null})
 	 */
 	CacheAwareContextLoaderDelegate getCacheAwareContextLoaderDelegate();
 

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 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,6 +16,8 @@
 
 package org.springframework.test.context;
 
+import java.lang.reflect.Constructor;
+
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 
@@ -36,6 +38,10 @@
  */
 abstract class BootstrapUtils {
 
+	private static final String DEFAULT_BOOTSTRAP_CONTEXT_CLASS_NAME = "org.springframework.test.context.support.DefaultBootstrapContext";
+
+	private static final String DEFAULT_CACHE_AWARE_CONTEXT_LOADER_DELEGATE_CLASS_NAME = "org.springframework.test.context.support.DefaultCacheAwareContextLoaderDelegate";
+
 	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);
@@ -45,6 +51,55 @@ private BootstrapUtils() {
 		/* no-op */
 	}
 
+	/**
+	 * Create the {@code BootstrapContext} for the specified {@linkplain Class test class}.
+	 *
+	 * <p>Uses reflection to create a {@link org.springframework.test.context.support.DefaultBootstrapContext}
+	 * that uses a {@link org.springframework.test.context.support.DefaultCacheAwareContextLoaderDelegate}.
+	 *
+	 * @param testClass the test class for which the bootstrap context should be created
+	 * @return a new {@code BootstrapContext}; never {@code null}
+	 */
+	@SuppressWarnings("unchecked")
+	static BootstrapContext createBootstrapContext(Class<?> testClass) {
+		CacheAwareContextLoaderDelegate cacheAwareContextLoaderDelegate = createCacheAwareContextLoaderDelegate();
+
+		Class<? extends BootstrapContext> clazz = null;
+		try {
+			clazz = (Class<? extends BootstrapContext>) ClassUtils.forName(DEFAULT_BOOTSTRAP_CONTEXT_CLASS_NAME,
+				BootstrapUtils.class.getClassLoader());
+
+			Constructor<? extends BootstrapContext> constructor = clazz.getConstructor(Class.class,
+				CacheAwareContextLoaderDelegate.class);
+
+			if (logger.isDebugEnabled()) {
+				logger.debug(String.format("Instantiating BootstrapContext using constructor [%s]", constructor));
+			}
+			return instantiateClass(constructor, testClass, cacheAwareContextLoaderDelegate);
+		}
+		catch (Throwable t) {
+			throw new IllegalStateException("Could not load BootstrapContext [" + clazz + "]", t);
+		}
+	}
+
+	@SuppressWarnings("unchecked")
+	private static CacheAwareContextLoaderDelegate createCacheAwareContextLoaderDelegate() {
+		Class<? extends CacheAwareContextLoaderDelegate> clazz = null;
+		try {
+			clazz = (Class<? extends CacheAwareContextLoaderDelegate>) ClassUtils.forName(
+				DEFAULT_CACHE_AWARE_CONTEXT_LOADER_DELEGATE_CLASS_NAME, BootstrapUtils.class.getClassLoader());
+
+			if (logger.isDebugEnabled()) {
+				logger.debug(String.format("Instantiating CacheAwareContextLoaderDelegate from class [%s]",
+					clazz.getName()));
+			}
+			return instantiateClass(clazz, CacheAwareContextLoaderDelegate.class);
+		}
+		catch (Throwable t) {
+			throw new IllegalStateException("Could not load CacheAwareContextLoaderDelegate [" + clazz + "]", t);
+		}
+	}
+
 	/**
 	 * Resolve the {@link TestContextBootstrapper} type for the test class in the
 	 * supplied {@link BootstrapContext}, instantiate it, and provide it a reference

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

@@ -40,6 +40,8 @@ public interface CacheAwareContextLoaderDelegate {
 	 * configured in the given {@code MergedContextConfiguration}.
 	 * <p>If the context is present in the {@code ContextCache} it will simply
 	 * be returned; otherwise, it will be loaded, stored in the cache, and returned.
+	 * <p>The cache statistics should be logged by invoking
+	 * {@link ContextCache#logStatistics()}.
 	 * @param mergedContextConfiguration the merged context configuration to use
 	 * to load the application context; never {@code null}
 	 * @return the application context

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

@@ -41,6 +41,13 @@
  */
 public interface ContextCache {
 
+	/**
+	 * The name of the logging category used for reporting {@code ContextCache}
+	 * statistics.
+	 */
+	public static final String CONTEXT_CACHE_LOGGING_CATEGORY = "org.springframework.test.context.cache";
+
+
 	/**
 	 * Determine whether there is a cached context for the given key.
 	 * @param key the context key (never {@code null})
@@ -126,19 +133,18 @@ public interface ContextCache {
 	void clearStatistics();
 
 	/**
-	 * Generate a text string containing the implementation type of this
-	 * cache and its statistics.
-	 * <p>The value returned by this method will be used primarily for
-	 * logging purposes.
-	 * <p>Specifically, the returned string should contain the name of the
-	 * concrete {@code ContextCache} implementation, the {@linkplain #size},
-	 * {@linkplain #getParentContextCount() parent context count},
-	 * {@linkplain #getHitCount() hit count}, {@linkplain #getMissCount()
-	 * miss count}, and any other information useful in monitoring the
-	 * state of this cache.
-	 * @return a string representation of this cache, including statistics
+	 * Log the statistics for this {@code ContextCache} at {@code DEBUG} level
+	 * using the {@value #CONTEXT_CACHE_LOGGING_CATEGORY} logging category.
+	 * <p>The following information should be logged.
+	 * <ul>
+	 * <li>name of the concrete {@code ContextCache} implementation</li>
+	 * <li>{@linkplain #size}</li>
+	 * <li>{@linkplain #getParentContextCount() parent context count}</li>
+	 * <li>{@linkplain #getHitCount() hit count}</li>
+	 * <li>{@linkplain #getMissCount() miss count}</li>
+	 * <li>any other information useful for monitoring the state of this cache</li>
+	 * </ul>
 	 */
-	@Override
-	abstract String toString();
+	void logStatistics();
 
 }

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

@@ -102,22 +102,23 @@ public class TestContextManager {
 	 */
 	public TestContextManager(Class<?> testClass) {
 		BootstrapContext bootstrapContext = createBootstrapContext(testClass);
-		TestContextBootstrapper testContextBootstrapper = BootstrapUtils.resolveTestContextBootstrapper(bootstrapContext);
-		this.testContext = testContextBootstrapper.buildTestContext();
-		registerTestExecutionListeners(testContextBootstrapper.getTestExecutionListeners());
+		TestContextBootstrapper bootstrapper = BootstrapUtils.resolveTestContextBootstrapper(bootstrapContext);
+		this.testContext = bootstrapper.buildTestContext();
+		registerTestExecutionListeners(bootstrapper.getTestExecutionListeners());
 	}
 
 	/**
 	 * Create the {@code BootstrapContext} for the specified {@linkplain Class test class}.
-	 * <p>The default implementation creates a {@link DefaultBootstrapContext} that
-	 * uses the {@link DefaultCacheAwareContextLoaderDelegate}.
+	 * <p>The default implementation creates a
+	 * {@link org.springframework.test.context.support.DefaultBootstrapContext DefaultBootstrapContext}
+	 * that uses a
+	 * {@link org.springframework.test.context.support.DefaultCacheAwareContextLoaderDelegate DefaultCacheAwareContextLoaderDelegate}.
 	 * <p>Can be overridden by subclasses as necessary.
 	 * @param testClass the test class for which the bootstrap context should be created
 	 * @return a new {@code BootstrapContext}; never {@code null}
 	 */
 	protected BootstrapContext createBootstrapContext(Class<?> testClass) {
-		CacheAwareContextLoaderDelegate cacheAwareContextLoaderDelegate = new DefaultCacheAwareContextLoaderDelegate();
-		return new DefaultBootstrapContext(testClass, cacheAwareContextLoaderDelegate);
+		return BootstrapUtils.createBootstrapContext(testClass);
 	}
 
 	/**

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

@@ -38,6 +38,7 @@
 import org.springframework.core.io.support.SpringFactoriesLoader;
 import org.springframework.test.context.BootstrapContext;
 import org.springframework.test.context.CacheAwareContextLoaderDelegate;
+import org.springframework.test.context.ContextCache;
 import org.springframework.test.context.ContextConfiguration;
 import org.springframework.test.context.ContextConfigurationAttributes;
 import org.springframework.test.context.ContextHierarchy;
@@ -67,6 +68,9 @@
  * <li>{@link #processMergedContextConfiguration}
  * </ul>
  *
+ * <p>To plug in custom {@link ContextCache} support, override
+ * {@link #getCacheAwareContextLoaderDelegate()}.
+ *
  * @author Sam Brannen
  * @author Juergen Hoeller
  * @since 4.1
@@ -96,17 +100,17 @@ public BootstrapContext getBootstrapContext() {
 
 	/**
 	 * Build a new {@link DefaultTestContext} using the {@linkplain Class test class}
-	 * and {@link CacheAwareContextLoaderDelegate} in the {@link BootstrapContext}
-	 * associated with this bootstrapper and by delegating to
-	 * {@link #buildMergedContextConfiguration()}.
+	 * in the {@link BootstrapContext} associated with this bootstrapper and
+	 * by delegating to {@link #buildMergedContextConfiguration()} and
+	 * {@link #getCacheAwareContextLoaderDelegate()}.
 	 * <p>Concrete subclasses may choose to override this method to return a
 	 * custom {@link TestContext} implementation.
 	 * @since 4.2
 	 */
 	@Override
 	public TestContext buildTestContext() {
-		return new DefaultTestContext(bootstrapContext.getTestClass(), buildMergedContextConfiguration(),
-			bootstrapContext.getCacheAwareContextLoaderDelegate());
+		return new DefaultTestContext(getBootstrapContext().getTestClass(), buildMergedContextConfiguration(),
+			getCacheAwareContextLoaderDelegate());
 	}
 
 	/**
@@ -282,7 +286,7 @@ protected List<String> getDefaultTestExecutionListenerClassNames() {
 	@Override
 	public final MergedContextConfiguration buildMergedContextConfiguration() {
 		Class<?> testClass = getBootstrapContext().getTestClass();
-		CacheAwareContextLoaderDelegate cacheAwareContextLoaderDelegate = getBootstrapContext().getCacheAwareContextLoaderDelegate();
+		CacheAwareContextLoaderDelegate cacheAwareContextLoaderDelegate = getCacheAwareContextLoaderDelegate();
 
 		if (MetaAnnotationUtils.findAnnotationDescriptorForTypes(testClass, ContextConfiguration.class,
 			ContextHierarchy.class) == null) {
@@ -471,6 +475,20 @@ protected Class<? extends ContextLoader> resolveExplicitContextLoaderClass(
 		return null;
 	}
 
+	/**
+	 * Get the {@link CacheAwareContextLoaderDelegate} to use for transparent
+	 * interaction with the {@code ContextCache}.
+	 * <p>The default implementation simply delegates to
+	 * {@code getBootstrapContext().getCacheAwareContextLoaderDelegate()}.
+	 * <p>Concrete subclasses may choose to override this method to return a
+	 * custom {@code CacheAwareContextLoaderDelegate} implementation with
+	 * custom {@link ContextCache} support.
+	 * @return the context loader delegate (never {@code null})
+	 */
+	protected CacheAwareContextLoaderDelegate getCacheAwareContextLoaderDelegate() {
+		return getBootstrapContext().getCacheAwareContextLoaderDelegate();
+	}
+
 	/**
 	 * Determine the default {@link ContextLoader} {@linkplain Class class}
 	 * to use for the supplied test class.

spring-test/src/main/java/org/springframework/test/context/DefaultBootstrapContext.java renamed to spring-test/src/main/java/org/springframework/test/context/support/DefaultBootstrapContext.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -14,9 +14,11 @@
  * limitations under the License.
  */
 
-package org.springframework.test.context;
+package org.springframework.test.context.support;
 
 import org.springframework.core.style.ToStringCreator;
+import org.springframework.test.context.BootstrapContext;
+import org.springframework.test.context.CacheAwareContextLoaderDelegate;
 import org.springframework.util.Assert;
 
 /**
@@ -25,13 +27,19 @@
  * @author Sam Brannen
  * @since 4.1
  */
-class DefaultBootstrapContext implements BootstrapContext {
+public class DefaultBootstrapContext implements BootstrapContext {
 
 	private final Class<?> testClass;
 	private final CacheAwareContextLoaderDelegate cacheAwareContextLoaderDelegate;
 
 
-	DefaultBootstrapContext(Class<?> testClass, CacheAwareContextLoaderDelegate cacheAwareContextLoaderDelegate) {
+	/**
+	 * Construct a new {@code DefaultBootstrapContext} from the supplied arguments.
+	 * @param testClass the test class for this bootstrap context; never {@code null}
+	 * @param cacheAwareContextLoaderDelegate the context loader delegate to use for
+	 * transparent interaction with the {@code ContextCache}; never {@code null}
+	 */
+	public DefaultBootstrapContext(Class<?> testClass, CacheAwareContextLoaderDelegate cacheAwareContextLoaderDelegate) {
 		Assert.notNull(testClass, "Test class must not be null");
 		Assert.notNull(cacheAwareContextLoaderDelegate, "CacheAwareContextLoaderDelegate must not be null");
 		this.testClass = testClass;

spring-test/src/main/java/org/springframework/test/context/DefaultCacheAwareContextLoaderDelegate.java renamed to spring-test/src/main/java/org/springframework/test/context/support/DefaultCacheAwareContextLoaderDelegate.java

@@ -14,34 +14,37 @@
  * limitations under the License.
  */
 
-package org.springframework.test.context;
+package org.springframework.test.context.support;
 
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 
 import org.springframework.context.ApplicationContext;
 import org.springframework.test.annotation.DirtiesContext.HierarchyMode;
-import org.springframework.test.context.support.DefaultContextCache;
+import org.springframework.test.context.CacheAwareContextLoaderDelegate;
+import org.springframework.test.context.ContextCache;
+import org.springframework.test.context.ContextLoader;
+import org.springframework.test.context.MergedContextConfiguration;
+import org.springframework.test.context.SmartContextLoader;
 import org.springframework.util.Assert;
 
 /**
  * Default implementation of the {@link CacheAwareContextLoaderDelegate} interface.
  *
+ * <p>To use a static {@code DefaultContextCache}, invoke the
+ * {@link #DefaultCacheAwareContextLoaderDelegate()} constructor; otherwise,
+ * invoke the {@link #DefaultCacheAwareContextLoaderDelegate(ContextCache)}
+ * and provide a custom {@link ContextCache} implementation.
+ *
  * @author Sam Brannen
  * @since 4.1
  */
-class DefaultCacheAwareContextLoaderDelegate implements CacheAwareContextLoaderDelegate {
+public class DefaultCacheAwareContextLoaderDelegate implements CacheAwareContextLoaderDelegate {
 
 	private static final Log logger = LogFactory.getLog(DefaultCacheAwareContextLoaderDelegate.class);
 
-	private static final Log statsLogger = LogFactory.getLog("org.springframework.test.context.cache");
-
 	/**
-	 * Default cache of Spring application contexts.
-	 *
-	 * <p>This default cache is static, so that each context can be cached
-	 * and reused for all subsequent tests that declare the same unique
-	 * context configuration within the same JVM process.
+	 * Default static cache of Spring application contexts.
 	 */
 	static final ContextCache defaultContextCache = new DefaultContextCache();
 
@@ -50,28 +53,39 @@ class DefaultCacheAwareContextLoaderDelegate implements CacheAwareContextLoaderD
 
 	/**
 	 * Construct a new {@code DefaultCacheAwareContextLoaderDelegate} using
-	 * a static {@code DefaultContextCache}.
+	 * a static {@link DefaultContextCache}.
+	 * <p>This default cache is static so that each context can be cached
+	 * and reused for all subsequent tests that declare the same unique
+	 * context configuration within the same JVM process.
+	 * @see #DefaultCacheAwareContextLoaderDelegate(ContextCache)
 	 */
-	DefaultCacheAwareContextLoaderDelegate() {
+	public DefaultCacheAwareContextLoaderDelegate() {
 		this(defaultContextCache);
 	}
 
 	/**
 	 * Construct a new {@code DefaultCacheAwareContextLoaderDelegate} using
-	 * the supplied {@code ContextCache}.
+	 * the supplied {@link ContextCache}.
+	 * @see #DefaultCacheAwareContextLoaderDelegate()
 	 */
-	DefaultCacheAwareContextLoaderDelegate(ContextCache contextCache) {
+	public DefaultCacheAwareContextLoaderDelegate(ContextCache contextCache) {
 		Assert.notNull(contextCache, "ContextCache must not be null");
 		this.contextCache = contextCache;
 	}
 
+	/**
+	 * Get the {@link ContextCache} used by this context loader delegate.
+	 */
+	protected ContextCache getContextCache() {
+		return this.contextCache;
+	}
 
 	/**
 	 * Load the {@code ApplicationContext} for the supplied merged context configuration.
 	 * <p>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)
+	protected ApplicationContext loadContextInternal(MergedContextConfiguration mergedContextConfiguration)
 			throws Exception {
 
 		ContextLoader contextLoader = mergedContextConfiguration.getContextLoader();
@@ -118,9 +132,7 @@ public ApplicationContext loadContext(MergedContextConfiguration mergedContextCo
 				}
 			}
 
-			if (statsLogger.isDebugEnabled()) {
-				statsLogger.debug("Spring test ApplicationContext cache statistics: " + this.contextCache);
-			}
+			this.contextCache.logStatistics();
 
 			return context;
 		}