Deprecate custom/default CtxLdr class name in TCF

Once the new bootstrap strategy for the TestContext framework (TCF) is
introduced in Spring Framework 4.1, a TestContextBootstrapper will
assume full responsibility for determining what ContextLoader to use as
the default. Consequently, the previous support for supplying the class
name for a custom, default ContextLoader will no longer be applicable.

This commit therefore officially deprecates support for custom, default
ContextLoader class names via the following mechanisms:

 - The TestContextManager(Class, String) constructor

 - The getDefaultContextLoaderClassName(Class) method in
   SpringJUnit4ClassRunner

Issue: SPR-11682

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

@@ -53,18 +53,18 @@ import static org.springframework.test.context.MetaAnnotationUtils.*;
  * <ul>
  * <li>{@link #beforeTestClass() before test class execution}: prior to any
  * <em>before class methods</em> of a particular testing framework (e.g., JUnit
- * 4's {@link org.junit.BeforeClass &#064;BeforeClass})</li>
+ * 4's {@link org.junit.BeforeClass @BeforeClass})</li>
  * <li>{@link #prepareTestInstance(Object) test instance preparation}:
  * immediately following instantiation of the test instance</li>
  * <li>{@link #beforeTestMethod(Object, Method) before test method execution}:
  * prior to any <em>before methods</em> of a particular testing framework (e.g.,
- * JUnit 4's {@link org.junit.Before &#064;Before})</li>
+ * JUnit 4's {@link org.junit.Before @Before})</li>
  * <li>{@link #afterTestMethod(Object, Method, Throwable) after test method
  * execution}: after any <em>after methods</em> of a particular testing
- * framework (e.g., JUnit 4's {@link org.junit.After &#064;After})</li>
+ * framework (e.g., JUnit 4's {@link org.junit.After @After})</li>
  * <li>{@link #afterTestClass() after test class execution}: after any
  * <em>after class methods</em> of a particular testing framework (e.g., JUnit
- * 4's {@link org.junit.AfterClass &#064;AfterClass})</li>
+ * 4's {@link org.junit.AfterClass @AfterClass})</li>
  * </ul>
  *
  * @author Sam Brannen
@@ -109,12 +109,15 @@ public class TestContextManager {
 	 * Constructs a new {@code TestContextManager} for the specified {@linkplain Class
 	 * test class} and automatically {@link #registerTestExecutionListeners registers} the
 	 * {@link TestExecutionListener TestExecutionListeners} configured for the test class
-	 * via the {@link TestExecutionListeners &#064;TestExecutionListeners} annotation.
+	 * via the {@link TestExecutionListeners @TestExecutionListeners} annotation.
 	 * @param testClass the test class to be managed
 	 * @param defaultContextLoaderClassName the name of the default {@code ContextLoader}
 	 * class to use (may be {@code null})
 	 * @see #registerTestExecutionListeners(TestExecutionListener...)
+	 * @deprecated Spring Framework 4.1 will introduce a bootstrap strategy for
+	 * the TestContext framework at which point this constructor will be removed.
 	 */
+	@Deprecated
 	public TestContextManager(Class<?> testClass, String defaultContextLoaderClassName) {
 		this.testContext = new DefaultTestContext(testClass, contextCache, defaultContextLoaderClassName);
 		registerTestExecutionListeners(retrieveTestExecutionListeners(testClass));
@@ -164,10 +167,10 @@ public class TestContextManager {
 
 	/**
 	 * Retrieve an array of newly instantiated {@link TestExecutionListener TestExecutionListeners}
-	 * for the specified {@link Class class}. If {@link TestExecutionListeners &#064;TestExecutionListeners}
+	 * for the specified {@link Class class}. If {@link TestExecutionListeners @TestExecutionListeners}
 	 * is not <em>present</em> on the supplied class, the default listeners will be returned.
 	 * <p>Note that the {@link TestExecutionListeners#inheritListeners() inheritListeners} flag of
-	 * {@link TestExecutionListeners &#064;TestExecutionListeners} will be taken into consideration.
+	 * {@link TestExecutionListeners @TestExecutionListeners} will be taken into consideration.
 	 * Specifically, if the {@code inheritListeners} flag is set to {@code true}, listeners
 	 * defined in the annotated class will be appended to the listeners defined in superclasses.
 	 * @param clazz the test class for which the listeners should be retrieved
@@ -268,7 +271,7 @@ public class TestContextManager {
 	 * Hook for pre-processing a test class <em>before</em> execution of any
 	 * tests within the class. Should be called prior to any framework-specific
 	 * <em>before class methods</em> (e.g., methods annotated with JUnit's
-	 * {@link org.junit.BeforeClass &#064;BeforeClass}).
+	 * {@link org.junit.BeforeClass @BeforeClass}).
 	 * <p>An attempt will be made to give each registered
 	 * {@link TestExecutionListener} a chance to pre-process the test class
 	 * execution. If a listener throws an exception, however, the remaining
@@ -334,7 +337,7 @@ public class TestContextManager {
 	 * {@link Method test method}, for example for setting up test fixtures,
 	 * starting a transaction, etc. Should be called prior to any
 	 * framework-specific <em>before methods</em> (e.g., methods annotated with
-	 * JUnit's {@link org.junit.Before &#064;Before}).
+	 * JUnit's {@link org.junit.Before @Before}).
 	 * <p>The managed {@link TestContext} will be updated with the supplied
 	 * {@code testInstance} and {@code testMethod}.
 	 * <p>An attempt will be made to give each registered
@@ -372,7 +375,7 @@ public class TestContextManager {
 	 * {@link Method test method}, for example for tearing down test fixtures,
 	 * ending a transaction, etc. Should be called after any framework-specific
 	 * <em>after methods</em> (e.g., methods annotated with JUnit's
-	 * {@link org.junit.After &#064;After}).
+	 * {@link org.junit.After @After}).
 	 * <p>The managed {@link TestContext} will be updated with the supplied
 	 * {@code testInstance}, {@code testMethod}, and
 	 * {@code exception}.
@@ -424,7 +427,7 @@ public class TestContextManager {
 	 * Hook for post-processing a test class <em>after</em> execution of all
 	 * tests within the class. Should be called after any framework-specific
 	 * <em>after class methods</em> (e.g., methods annotated with JUnit's
-	 * {@link org.junit.AfterClass &#064;AfterClass}).
+	 * {@link org.junit.AfterClass @AfterClass}).
 	 * <p>Each registered {@link TestExecutionListener} will be given a chance to
 	 * post-process the test class. If a listener throws an exception, the
 	 * remaining registered listeners will still be called, but the first

spring-test/src/main/java/org/springframework/test/context/junit4/SpringJUnit4ClassRunner.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.
@@ -65,16 +65,14 @@ import org.springframework.util.ReflectionUtils;
  * TestExecutionListeners})</em>
  * </p>
  * <ul>
- * <li>{@link Test#expected() &#064;Test(expected=...)}</li>
- * <li>{@link Test#timeout() &#064;Test(timeout=...)}</li>
- * <li>{@link Timed &#064;Timed}</li>
- * <li>{@link Repeat &#064;Repeat}</li>
- * <li>{@link Ignore &#064;Ignore}</li>
+ * <li>{@link Test#expected() @Test(expected=...)}</li>
+ * <li>{@link Test#timeout() @Test(timeout=...)}</li>
+ * <li>{@link Timed @Timed}</li>
+ * <li>{@link Repeat @Repeat}</li>
+ * <li>{@link Ignore @Ignore}</li>
  * <li>
- * {@link org.springframework.test.annotation.ProfileValueSourceConfiguration
- * &#064;ProfileValueSourceConfiguration}</li>
- * <li>{@link org.springframework.test.annotation.IfProfileValue
- * &#064;IfProfileValue}</li>
+ * {@link org.springframework.test.annotation.ProfileValueSourceConfiguration @ProfileValueSourceConfiguration}</li>
+ * <li>{@link org.springframework.test.annotation.IfProfileValue @IfProfileValue}</li>
  * </ul>
  * <p>
  * <b>NOTE:</b> As of Spring 3.0, {@code SpringJUnit4ClassRunner} requires
@@ -131,20 +129,23 @@ public class SpringJUnit4ClassRunner extends BlockJUnit4ClassRunner {
 	 * Get the name of the default {@code ContextLoader} class to use for
 	 * the supplied test class. The named class will be used if the test class
 	 * does not explicitly declare a {@code ContextLoader} class via the
-	 * {@code &#064;ContextConfiguration} annotation.
+	 * {@code @ContextConfiguration} annotation.
 	 * <p>The default implementation returns {@code null}, thus implying use
 	 * of the <em>standard</em> default {@code ContextLoader} class name.
-	 * Can be overridden by subclasses.
+	 * <p>Can be overridden by subclasses.
 	 * @param clazz the test class
 	 * @return {@code null}
+	 * @deprecated Spring Framework 4.1 will introduce a bootstrap strategy for
+	 * the TestContext framework at which point this method will be removed.
 	 */
+	@Deprecated
 	protected String getDefaultContextLoaderClassName(Class<?> clazz) {
 		return null;
 	}
 
 	/**
 	 * Returns a description suitable for an ignored test class if the test is
-	 * disabled via {@code &#064;IfProfileValue} at the class-level, and
+	 * disabled via {@code @IfProfileValue} at the class-level, and
 	 * otherwise delegates to the parent implementation.
 	 * @see ProfileValueUtils#isTestEnabledInThisEnvironment(Class)
 	 */
@@ -158,7 +159,7 @@ public class SpringJUnit4ClassRunner extends BlockJUnit4ClassRunner {
 
 	/**
 	 * Check whether the test is enabled in the first place. This prevents
-	 * classes with a non-matching {@code &#064;IfProfileValue} annotation
+	 * classes with a non-matching {@code @IfProfileValue} annotation
 	 * from running altogether, even skipping the execution of
 	 * {@code prepareTestInstance()} {@code TestExecutionListener}
 	 * methods.
@@ -260,13 +261,13 @@ public class SpringJUnit4ClassRunner extends BlockJUnit4ClassRunner {
 	 * {@link #withPotentialRepeat(FrameworkMethod, Object, Statement) with
 	 * potential repeats} of the entire execution chain.
 	 * <p>Furthermore, support for timeouts has been moved down the execution chain
-	 * in order to include execution of {@link org.junit.Before &#064;Before}
-	 * and {@link org.junit.After &#064;After} methods within the timed
+	 * in order to include execution of {@link org.junit.Before @Before}
+	 * and {@link org.junit.After @After} methods within the timed
 	 * execution. Note that this differs from the default JUnit behavior of
-	 * executing {@code &#064;Before} and {@code &#064;After} methods
+	 * executing {@code @Before} and {@code @After} methods
 	 * in the main thread while executing the actual test method in a separate
-	 * thread. Thus, the end effect is that {@code &#064;Before} and
-	 * {@code &#064;After} methods will be executed in the same thread as
+	 * thread. Thus, the end effect is that {@code @Before} and
+	 * {@code @After} methods will be executed in the same thread as
 	 * the test method. As a consequence, JUnit-specified timeouts will work
 	 * fine in combination with Spring transactions. Note that JUnit-specific
 	 * timeouts still differ from Spring-specific timeouts in that the former
@@ -324,9 +325,9 @@ public class SpringJUnit4ClassRunner extends BlockJUnit4ClassRunner {
 	}
 
 	/**
-	 * Returns {@code true} if {@link Ignore &#064;Ignore} is present for
+	 * Returns {@code true} if {@link Ignore @Ignore} is present for
 	 * the supplied {@link FrameworkMethod test method} or if the test method is
-	 * disabled via {@code &#064;IfProfileValue}.
+	 * disabled via {@code @IfProfileValue}.
 	 * @see ProfileValueUtils#isTestEnabledInThisEnvironment(Method, Class)
 	 */
 	protected boolean isTestMethodIgnored(FrameworkMethod frameworkMethod) {
@@ -362,8 +363,8 @@ public class SpringJUnit4ClassRunner extends BlockJUnit4ClassRunner {
 	}
 
 	/**
-	 * Supports both Spring's {@link Timed &#064;Timed} and JUnit's
-	 * {@link Test#timeout() &#064;Test(timeout=...)} annotations, but not both
+	 * Supports both Spring's {@link Timed @Timed} and JUnit's
+	 * {@link Test#timeout() @Test(timeout=...)} annotations, but not both
 	 * simultaneously. Returns either a {@link SpringFailOnTimeout}, a
 	 * {@link FailOnTimeout}, or the unmodified, supplied {@link Statement} as
 	 * appropriate.
@@ -397,8 +398,8 @@ public class SpringJUnit4ClassRunner extends BlockJUnit4ClassRunner {
 	}
 
 	/**
-	 * Retrieves the configured JUnit {@code timeout} from the {@link Test
-	 * &#064;Test} annotation on the supplied {@link FrameworkMethod test method}.
+	 * Retrieves the configured JUnit {@code timeout} from the {@link Test @Test}
+	 * annotation on the supplied {@link FrameworkMethod test method}.
 	 * @return the timeout, or {@code 0} if none was specified.
 	 */
 	protected long getJUnitTimeout(FrameworkMethod frameworkMethod) {
@@ -408,7 +409,7 @@ public class SpringJUnit4ClassRunner extends BlockJUnit4ClassRunner {
 
 	/**
 	 * Retrieves the configured Spring-specific {@code timeout} from the
-	 * {@link Timed &#064;Timed} annotation on the supplied
+	 * {@link Timed @Timed} annotation on the supplied
 	 * {@link FrameworkMethod test method}.
 	 * @return the timeout, or {@code 0} if none was specified.
 	 */
@@ -453,7 +454,7 @@ public class SpringJUnit4ClassRunner extends BlockJUnit4ClassRunner {
 	}
 
 	/**
-	 * Supports Spring's {@link Repeat &#064;Repeat} annotation by returning a
+	 * Supports Spring's {@link Repeat @Repeat} annotation by returning a
 	 * {@link SpringRepeat} statement initialized with the configured repeat
 	 * count or {@code 1} if no repeat count is configured.
 	 * @see SpringRepeat