Support automatic discovery of default TELs

Prior to this commit, there was no declarative mechanism for a custom
TestExecutionListener to be registered as a default
TestExecutionListener.

This commit introduces support for discovering default
TestExecutionListener implementations via the SpringFactoriesLoader
mechanism. Specifically, the spring-test module declares all core
default TestExecutionListeners under the
org.springframework.test.context.TestExecutionListener key in its
META-INF/spring.factories properties file, and third-party frameworks
and developers can contribute to the list of default
TestExecutionListeners in the same manner.

 - AbstractTestContextBootstrapper uses the SpringFactoriesLoader to
   look up the class names of all registered default
   TestExecutionListeners and sorts the instantiated listeners using
   AnnotationAwareOrderComparator.

 - DefaultTestContextBootstrapper and WebTestContextBootstrapper now
   rely on the SpringFactoriesLoader mechanism for finding default
   TestExecutionListeners instead of hard coding fully qualified class
   names.

 - To ensure that default TestExecutionListeners are registered in the
   correct order, each can implement Ordered or declare @order.

 - AbstractTestExecutionListener and all default TestExecutionListeners
   provided by Spring now implement Ordered with appropriate values.

 - Introduced "copy constructors" in MergedContextConfiguration and
   WebMergedContextConfiguration

 - SpringFactoriesLoader now uses AnnotationAwareOrderComparator
   instead of OrderComparator.

Issue: SPR-11466

Author: sbrannen

spring-core/src/main/java/org/springframework/core/io/support/SpringFactoriesLoader.java

@@ -27,7 +27,7 @@
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 
-import org.springframework.core.OrderComparator;
+import org.springframework.core.annotation.AnnotationAwareOrderComparator;
 import org.springframework.core.io.UrlResource;
 import org.springframework.util.Assert;
 import org.springframework.util.ClassUtils;
@@ -48,20 +48,21 @@
  *
  * @author Arjen Poutsma
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 3.2
  */
 public abstract class SpringFactoriesLoader {
 
 	/** The location to look for the factories. Can be present in multiple JAR files. */
-	private static final String FACTORIES_RESOURCE_LOCATION = "META-INF/spring.factories";
+	public static final String FACTORIES_RESOURCE_LOCATION = "META-INF/spring.factories";
 
 	private static final Log logger = LogFactory.getLog(SpringFactoriesLoader.class);
 
 
 	/**
 	 * Load the factory implementations of the given type from the default location,
 	 * using the given class loader.
-	 * <p>The returned factories are ordered in accordance with the {@link OrderComparator}.
+	 * <p>The returned factories are ordered in accordance with the {@link AnnotationAwareOrderComparator}.
 	 * @param factoryClass the interface or abstract class representing the factory
 	 * @param classLoader the ClassLoader to use for loading (can be {@code null} to use the default)
 	 */
@@ -79,7 +80,7 @@ public static <T> List<T> loadFactories(Class<T> factoryClass, ClassLoader class
 		for (String factoryName : factoryNames) {
 			result.add(instantiateFactory(factoryName, factoryClass, classLoaderToUse));
 		}
-		OrderComparator.sort(result);
+		AnnotationAwareOrderComparator.sort(result);
 		return result;
 	}
 

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

@@ -79,6 +79,7 @@ public class MergedContextConfiguration implements Serializable {
 	private final String[] propertySourceProperties;
 	private final ContextLoader contextLoader;
 	private final CacheAwareContextLoaderDelegate cacheAwareContextLoaderDelegate;
+
 	private final MergedContextConfiguration parent;
 
 
@@ -185,6 +186,18 @@ public MergedContextConfiguration(
 			cacheAwareContextLoaderDelegate, parent);
 	}
 
+	/**
+	 * Create a new {@code MergedContextConfiguration} instance by copying
+	 * all fields from the supplied {@code MergedContextConfiguration}.
+	 * @since 4.1
+	 */
+	public MergedContextConfiguration(MergedContextConfiguration mergedConfig) {
+		this(mergedConfig.testClass, mergedConfig.locations, mergedConfig.classes,
+			mergedConfig.contextInitializerClasses, mergedConfig.activeProfiles, mergedConfig.propertySourceLocations,
+			mergedConfig.propertySourceProperties, mergedConfig.contextLoader,
+			mergedConfig.cacheAwareContextLoaderDelegate, mergedConfig.parent);
+	}
+
 	/**
 	 * Create a new {@code MergedContextConfiguration} instance for the
 	 * supplied parameters.

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

@@ -63,8 +63,16 @@ public interface TestContextBootstrapper {
 	 * for the test class in the {@link BootstrapContext} associated with this bootstrapper.
 	 * <p>If {@link TestExecutionListeners @TestExecutionListeners} is not
 	 * <em>present</em> on the test class in the {@code BootstrapContext},
-	 * <em>default</em> listeners should be returned. Concrete implementations
-	 * are free to determine what comprises the set of default listeners.
+	 * <em>default</em> listeners should be returned. Furthermore, default
+	 * listeners must be sorted using
+	 * {@link org.springframework.core.annotation.AnnotationAwareOrderComparator
+	 * AnnotationAwareOrderComparator}.
+	 * <p>Concrete implementations are free to determine what comprises the
+	 * set of default listeners. However, by default, the Spring TestContext
+	 * Framework will use the
+	 * {@link org.springframework.core.io.support.SpringFactoriesLoader SpringFactoriesLoader}
+	 * mechanism to look up all {@code TestExecutionListener} class names
+	 * configured in all {@code META-INF/spring.factories} files on the classpath.
 	 * <p>The {@link TestExecutionListeners#inheritListeners() inheritListeners}
 	 * flag of {@link TestExecutionListeners @TestExecutionListeners} must be
 	 * taken into consideration. Specifically, if the {@code inheritListeners}

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

@@ -23,7 +23,13 @@
  * <p>Concrete implementations must provide a {@code public} no-args constructor,
  * so that listeners can be instantiated transparently by tools and configuration
  * mechanisms.
- * <p>Spring provides the following out-of-the-box implementations:
+ * <p>Implementations may optionally declare the position in which they should
+ * be ordered among the chain of default listeners via the
+ * {@link org.springframework.core.Ordered Order} interface or
+ * {@link org.springframework.core.annotation.Order @Order} annotation. See
+ * {@link TestContextBootstrapper#getTestExecutionListeners()} for details.
+ * <p>Spring provides the following out-of-the-box implementations (all of
+ * which are annotated with {@code @Order}):
  * <ul>
  * <li>{@link org.springframework.test.context.web.ServletTestExecutionListener
  * ServletTestExecutionListener}</li>

spring-test/src/main/java/org/springframework/test/context/jdbc/SqlScriptsTestExecutionListener.java

@@ -89,6 +89,14 @@ public class SqlScriptsTestExecutionListener extends AbstractTestExecutionListen
 	private static final Log logger = LogFactory.getLog(SqlScriptsTestExecutionListener.class);
 
 
+	/**
+	 * Returns {@code 5000}.
+	 */
+	@Override
+	public final int getOrder() {
+		return 5000;
+	}
+
 	/**
 	 * Execute SQL scripts configured via {@link Sql @Sql} for the supplied
 	 * {@link TestContext} <em>before</em> the current test method.

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

@@ -31,7 +31,9 @@
 import org.springframework.context.ApplicationContextInitializer;
 import org.springframework.context.ConfigurableApplicationContext;
 import org.springframework.core.annotation.AnnotationAttributes;
+import org.springframework.core.annotation.AnnotationAwareOrderComparator;
 import org.springframework.core.annotation.AnnotationUtils;
+import org.springframework.core.io.support.SpringFactoriesLoader;
 import org.springframework.test.context.BootstrapContext;
 import org.springframework.test.context.CacheAwareContextLoaderDelegate;
 import org.springframework.test.context.ContextConfiguration;
@@ -55,11 +57,10 @@
  * provides most of the behavior required by a bootstrapper.
  *
  * <p>Concrete subclasses typically will only need to provide implementations for
- * the following {@code abstract} methods:
+ * the following methods:
  * <ul>
- * <li>{@link #getDefaultTestExecutionListenerClassNames}
  * <li>{@link #getDefaultContextLoaderClass}
- * <li>{@link #buildMergedContextConfiguration}
+ * <li>{@link #processMergedContextConfiguration}
  * </ul>
  *
  * @author Sam Brannen
@@ -98,16 +99,18 @@ public final List<TestExecutionListener> getTestExecutionListeners() {
 		Class<?> clazz = getBootstrapContext().getTestClass();
 		Class<TestExecutionListeners> annotationType = TestExecutionListeners.class;
 		List<Class<? extends TestExecutionListener>> classesList = new ArrayList<Class<? extends TestExecutionListener>>();
+		boolean usingDefaults = false;
 
 		AnnotationDescriptor<TestExecutionListeners> descriptor = MetaAnnotationUtils.findAnnotationDescriptor(clazz,
 			annotationType);
 
 		// Use defaults?
 		if (descriptor == null) {
 			if (logger.isDebugEnabled()) {
-				logger.debug("@TestExecutionListeners is not present for class [" + clazz.getName()
-						+ "]: using defaults.");
+				logger.debug(String.format("@TestExecutionListeners is not present for class [%s]: using defaults.",
+					clazz.getName()));
 			}
+			usingDefaults = true;
 			classesList.addAll(getDefaultTestExecutionListenerClasses());
 		}
 		else {
@@ -142,6 +145,20 @@ else if (!ObjectUtils.isEmpty(valueListenerClasses)) {
 			}
 		}
 
+		List<TestExecutionListener> listeners = instantiateListeners(classesList);
+
+		// Sort by Ordered/@Order if we loaded default listeners.
+		if (usingDefaults) {
+			AnnotationAwareOrderComparator.sort(listeners);
+		}
+
+		if (logger.isInfoEnabled()) {
+			logger.info(String.format("Using TestExecutionListeners: %s", listeners));
+		}
+		return listeners;
+	}
+
+	private List<TestExecutionListener> instantiateListeners(List<Class<? extends TestExecutionListener>> classesList) {
 		List<TestExecutionListener> listeners = new ArrayList<TestExecutionListener>(classesList.size());
 		for (Class<? extends TestExecutionListener> listenerClass : classesList) {
 			NoClassDefFoundError ncdfe = null;
@@ -194,6 +211,28 @@ protected Set<Class<? extends TestExecutionListener>> getDefaultTestExecutionLis
 		return defaultListenerClasses;
 	}
 
+	/**
+	 * Get the names of the default {@link TestExecutionListener} classes for
+	 * this bootstrapper.
+	 * <p>The default implementation looks up all
+	 * {@code org.springframework.test.context.TestExecutionListener} entries
+	 * configured in all {@code META-INF/spring.factories} files on the classpath.
+	 * <p>This method is invoked by {@link #getDefaultTestExecutionListenerClasses()}.
+	 * @return an <em>unmodifiable</em> list of names of default {@code TestExecutionListener}
+	 * classes
+	 * @see SpringFactoriesLoader#loadFactoryNames
+	 */
+	protected List<String> getDefaultTestExecutionListenerClassNames() {
+		final List<String> classNames = SpringFactoriesLoader.loadFactoryNames(TestExecutionListener.class,
+			getClass().getClassLoader());
+
+		if (logger.isInfoEnabled()) {
+			logger.info(String.format("Loaded default TestExecutionListener class names from location [%s]: %s",
+				SpringFactoriesLoader.FACTORIES_RESOURCE_LOCATION, classNames));
+		}
+		return Collections.unmodifiableList(classNames);
+	}
+
 	/**
 	 * {@inheritDoc}
 	 */
@@ -302,9 +341,11 @@ private MergedContextConfiguration buildMergedContextConfiguration(Class<?> test
 		String[] activeProfiles = ActiveProfilesUtils.resolveActiveProfiles(testClass);
 		MergedTestPropertySources mergedTestPropertySources = TestPropertySourceUtils.buildMergedTestPropertySources(testClass);
 
-		return buildMergedContextConfiguration(testClass, locations, classes, initializerClasses, activeProfiles,
-			mergedTestPropertySources.getLocations(), mergedTestPropertySources.getProperties(), contextLoader,
-			cacheAwareContextLoaderDelegate, parentConfig);
+		MergedContextConfiguration mergedConfig = new MergedContextConfiguration(testClass, locations, classes,
+			initializerClasses, activeProfiles, mergedTestPropertySources.getLocations(),
+			mergedTestPropertySources.getProperties(), contextLoader, cacheAwareContextLoaderDelegate, parentConfig);
+
+		return processMergedContextConfiguration(mergedConfig);
 	}
 
 	/**
@@ -383,15 +424,6 @@ private Class<? extends ContextLoader> resolveExplicitContextLoaderClass(
 		return null;
 	}
 
-	/**
-	 * Get the names of the default {@link TestExecutionListener} classes for
-	 * this bootstrapper.
-	 * <p>This method is invoked by {@link #getDefaultTestExecutionListenerClasses()}.
-	 * @return an <em>unmodifiable</em> list of names of default {@code
-	 * TestExecutionListener} classes
-	 */
-	protected abstract List<String> getDefaultTestExecutionListenerClassNames();
-
 	/**
 	 * Determine the default {@link ContextLoader} class to use for the supplied
 	 * test class.
@@ -403,34 +435,19 @@ private Class<? extends ContextLoader> resolveExplicitContextLoaderClass(
 	protected abstract Class<? extends ContextLoader> getDefaultContextLoaderClass(Class<?> testClass);
 
 	/**
-	 * Build a {@link MergedContextConfiguration} instance from the supplied,
-	 * merged values.
-	 * <p>Concrete subclasses typically will only need to instantiate
-	 * {@link MergedContextConfiguration} (or a specialized subclass thereof)
-	 * from the provided values; further processing and merging of values is likely
-	 * unnecessary.
-	 * @param testClass the test class for which the {@code MergedContextConfiguration}
-	 * should be built (must not be {@code null})
-	 * @param locations the merged resource locations
-	 * @param classes the merged annotated classes
-	 * @param initializerClasses the merged context initializer classes
-	 * @param activeProfiles the merged active bean definition profiles
-	 * @param propertySourceLocations the merged {@code PropertySource} locations
-	 * @param propertySourceProperties the merged {@code PropertySource} properties
-	 * @param contextLoader the resolved {@code ContextLoader}
-	 * @param cacheAwareContextLoaderDelegate the cache-aware context loader delegate
-	 * to be provided to the instantiated {@code MergedContextConfiguration}
-	 * @param parentConfig the merged context configuration for the parent application
-	 * context in a context hierarchy, or {@code null} if there is no parent
-	 * @return the fully initialized {@code MergedContextConfiguration}
+	 * Process the supplied, newly instantiated {@link MergedContextConfiguration} instance.
+	 * <p>The returned {@link MergedContextConfiguration} instance may be a wrapper
+	 * around or a replacement for the original.
+	 * <p>The default implementation simply returns the supplied instance unmodified.
+	 * <p>Concrete subclasses may choose to return a specialized subclass of
+	 * {@link MergedContextConfiguration} based on properties in the supplied instance.
+	 * @param mergedConfig the {@code MergedContextConfiguration} to process;
+	 * never {@code null}
+	 * @return a fully initialized {@code MergedContextConfiguration}; never
+	 * {@code null}
 	 */
-	protected abstract MergedContextConfiguration buildMergedContextConfiguration(
-			Class<?> testClass,
-			String[] locations,
-			Class<?>[] classes,
-			Set<Class<? extends ApplicationContextInitializer<? extends ConfigurableApplicationContext>>> initializerClasses,
-			String[] activeProfiles, String[] propertySourceLocations, String[] propertySourceProperties,
-			ContextLoader contextLoader, CacheAwareContextLoaderDelegate cacheAwareContextLoaderDelegate,
-			MergedContextConfiguration parentConfig);
+	protected MergedContextConfiguration processMergedContextConfiguration(MergedContextConfiguration mergedConfig) {
+		return mergedConfig;
+	}
 
 }

spring-test/src/main/java/org/springframework/test/context/support/AbstractTestExecutionListener.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.
@@ -16,6 +16,7 @@
 
 package org.springframework.test.context.support;
 
+import org.springframework.core.Ordered;
 import org.springframework.test.context.TestContext;
 import org.springframework.test.context.TestExecutionListener;
 
@@ -28,7 +29,7 @@
  * @author Juergen Hoeller
  * @since 2.5
  */
-public abstract class AbstractTestExecutionListener implements TestExecutionListener {
+public abstract class AbstractTestExecutionListener implements TestExecutionListener, Ordered {
 
 	/**
 	 * The default implementation is <em>empty</em>. Can be overridden by
@@ -75,4 +76,16 @@ public void afterTestClass(TestContext testContext) throws Exception {
 		/* no-op */
 	}
 
+	/**
+	 * The default implementation returns {@link Ordered#LOWEST_PRECEDENCE},
+	 * thereby ensuring that custom listeners are ordered after default
+	 * listeners supplied by the framework. Can be overridden by subclasses
+	 * as necessary.
+	 * @since 4.1
+	 */
+	@Override
+	public int getOrder() {
+		return Ordered.LOWEST_PRECEDENCE;
+	}
+
 }