[SPR-4702] JavaDoc updates

Author: sbrannen

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

@@ -54,6 +54,10 @@ public interface TestExecutionListener {
 	 * <p>
 	 * This method should be called immediately before framework-specific
 	 * <em>before class</em> lifecycle callbacks.
+	 * <p>
+	 * If a given testing framework (e.g., JUnit 3.8) does not support
+	 * <em>before class</em> lifecycle callbacks, this method will not be called
+	 * for that framework.
 	 * 
 	 * @param testContext the test context for the test; never <code>null</code>
 	 * @throws Exception allows any exception to propagate
@@ -108,6 +112,10 @@ public interface TestExecutionListener {
 	 * <p>
 	 * This method should be called immediately after framework-specific
 	 * <em>after class</em> lifecycle callbacks.
+	 * <p>
+	 * If a given testing framework (e.g., JUnit 3.8) does not support
+	 * <em>after class</em> lifecycle callbacks, this method will not be called
+	 * for that framework.
 	 * 
 	 * @param testContext the test context for the test; never <code>null</code>
 	 * @throws Exception allows any exception to propagate

org.springframework.test/src/main/java/org/springframework/test/context/junit38/AbstractJUnit38SpringContextTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2008 the original author or authors.
+ * Copyright 2002-2009 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.
@@ -21,9 +21,9 @@
 
 import junit.framework.AssertionFailedError;
 import junit.framework.TestCase;
+
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
-
 import org.springframework.context.ApplicationContext;
 import org.springframework.context.ApplicationContextAware;
 import org.springframework.test.annotation.ExpectedException;
@@ -39,47 +39,67 @@
 
 /**
  * <p>
- * Abstract base {@link TestCase} which integrates the
- * <em>Spring TestContext Framework</em> with explicit
- * {@link ApplicationContext} testing support in a <strong>JUnit 3.8</strong>
- * environment.
+ * Abstract base {@link TestCase} which integrates the <i>Spring TestContext
+ * Framework</i> and explicit {@link ApplicationContext} testing support in a
+ * <strong>JUnit 3.8</strong> environment.
  * </p>
  * <p>
  * Concrete subclasses:
  * </p>
  * <ul>
  * <li>Typically declare a class-level
- * {@link org.springframework.test.context.ContextConfiguration @ContextConfiguration}
- * annotation to configure the {@link ApplicationContext application context}
- * {@link org.springframework.test.context.ContextConfiguration#locations() resource locations}.
- * <em>If your test does not need to load an
- * application context, you may choose to omit the
- * {@link org.springframework.test.context.ContextConfiguration @ContextConfiguration} declaration and configure
- * the appropriate {@link org.springframework.test.context.TestExecutionListener TestExecutionListeners}
- * manually.</em></li>
+ * {@link org.springframework.test.context.ContextConfiguration
+ * &#064;ContextConfiguration} annotation to configure the
+ * {@link ApplicationContext application context}
+ * {@link org.springframework.test.context.ContextConfiguration#locations()
+ * resource locations}. <i>If your test does not need to load an application
+ * context, you may choose to omit the
+ * {@link org.springframework.test.context.ContextConfiguration
+ * &#064;ContextConfiguration} declaration and configure the appropriate
+ * {@link org.springframework.test.context.TestExecutionListener
+ * TestExecutionListeners} manually.</i></li>
  * <li>Must declare public constructors which match the signatures of
- * {@link #AbstractJUnit38SpringContextTests() AbstractJUnit38SpringContextTests()}
- * and
- * {@link #AbstractJUnit38SpringContextTests(String) AbstractJUnit38SpringContextTests(String)}
- * and delegate to <code>super();</code> and <code>super(name);</code>
- * respectively.</li>
+ * {@link #AbstractJUnit38SpringContextTests()
+ * AbstractJUnit38SpringContextTests()} and
+ * {@link #AbstractJUnit38SpringContextTests(String)
+ * AbstractJUnit38SpringContextTests(String)} and delegate to
+ * <code>super();</code> and <code>super(name);</code> respectively.</li>
  * </ul>
  * <p>
  * The following list constitutes all annotations currently supported directly
- * by <code>AbstractJUnit38SpringContextTests</code>.
- * <em>(Note that additional annotations may be supported by various
- * {@link org.springframework.test.context.TestExecutionListener TestExecutionListeners})</em>
+ * by <code>AbstractJUnit38SpringContextTests</code>. <i>(Note that additional
+ * annotations may be supported by various
+ * {@link org.springframework.test.context.TestExecutionListener
+ * TestExecutionListeners})</i>
  * </p>
  * <ul>
- * <li>{@link org.springframework.test.annotation.DirtiesContext @DirtiesContext}
- * (via the configured {@link DirtiesContextTestExecutionListener})</li>
- * <li>{@link org.springframework.test.annotation.ProfileValueSourceConfiguration @ProfileValueSourceConfiguration}</li>
- * <li>{@link IfProfileValue @IfProfileValue}</li>
- * <li>{@link ExpectedException @ExpectedException}</li>
- * <li>{@link Timed @Timed}</li>
- * <li>{@link Repeat @Repeat}</li>
+ * <li>{@link org.springframework.test.annotation.DirtiesContext
+ * &#064;DirtiesContext} (via the configured
+ * {@link DirtiesContextTestExecutionListener}; only supported on methods for
+ * JUnit 3.8)</li>
+ * <li>
+ * {@link org.springframework.test.annotation.ProfileValueSourceConfiguration
+ * &#064;ProfileValueSourceConfiguration}</li>
+ * <li>{@link IfProfileValue &#064;IfProfileValue}</li>
+ * <li>{@link ExpectedException &#064;ExpectedException}</li>
+ * <li>{@link Timed &#064;Timed}</li>
+ * <li>{@link Repeat &#064;Repeat}</li>
  * </ul>
- *
+ * <p>
+ * JUnit 3.8 does not support <i>before class</i> or <i>after class</i>
+ * lifecycle callbacks. The following
+ * {@link org.springframework.test.context.TestExecutionListener
+ * TestExecutionListener} methods are therefore unsupported in a JUnit 3.8
+ * environment:
+ * <ul>
+ * <li>
+ * {@link org.springframework.test.context.TestExecutionListener#beforeTestClass(org.springframework.test.context.TestContext)
+ * beforeTestClass()}</li>
+ * <li>
+ * {@link org.springframework.test.context.TestExecutionListener#afterTestClass(org.springframework.test.context.TestContext)
+ * afterTestClass()}</li>
+ * </ul>
+ * 
  * @author Sam Brannen
  * @author Juergen Hoeller
  * @since 2.5
@@ -90,7 +110,7 @@
  * @see org.springframework.test.context.junit4.AbstractJUnit4SpringContextTests
  * @see org.springframework.test.context.testng.AbstractTestNGSpringContextTests
  */
-@TestExecutionListeners({DependencyInjectionTestExecutionListener.class, DirtiesContextTestExecutionListener.class})
+@TestExecutionListeners( { DependencyInjectionTestExecutionListener.class, DirtiesContextTestExecutionListener.class })
 public abstract class AbstractJUnit38SpringContextTests extends TestCase implements ApplicationContextAware {
 
 	private static int disabledTestCount = 0;
@@ -117,18 +137,18 @@ public static int getDisabledTestCount() {
 
 	/**
 	 * {@link ProfileValueSource} available to subclasses but primarily intended
-	 * for internal use to provide support for
-	 * {@link IfProfileValue @IfProfileValue}.
+	 * for internal use to provide support for {@link IfProfileValue
+	 * &#064;IfProfileValue}.
 	 */
 	protected final ProfileValueSource profileValueSource;
 
 	private final TestContextManager testContextManager;
 
 
 	/**
-	 * Constructs a new AbstractJUnit38SpringContextTests instance;
-	 * initializes the internal {@link TestContextManager} for the current test;
-	 * and retrieves the configured (or default) {@link ProfileValueSource}.
+	 * Constructs a new AbstractJUnit38SpringContextTests instance; initializes
+	 * the internal {@link TestContextManager} for the current test; and
+	 * retrieves the configured (or default) {@link ProfileValueSource}.
 	 */
 	public AbstractJUnit38SpringContextTests() {
 		super();
@@ -141,6 +161,7 @@ public AbstractJUnit38SpringContextTests() {
 	 * supplied <code>name</code>; initializes the internal
 	 * {@link TestContextManager} for the current test; and retrieves the
 	 * configured (or default) {@link ProfileValueSource}.
+	 * 
 	 * @param name the name of the current test to execute
 	 */
 	public AbstractJUnit38SpringContextTests(String name) {
@@ -149,7 +170,6 @@ public AbstractJUnit38SpringContextTests(String name) {
 		this.profileValueSource = ProfileValueUtils.retrieveProfileValueSource(getClass());
 	}
 
-
 	/**
 	 * Sets the {@link ApplicationContext} to be used by this test instance,
 	 * provided via {@link ApplicationContextAware} semantics.
@@ -158,24 +178,26 @@ public final void setApplicationContext(final ApplicationContext applicationCont
 		this.applicationContext = applicationContext;
 	}
 
-
 	/**
 	 * Runs the <em>Spring TestContext Framework</em> test sequence.
-	 * <p>In addition to standard {@link TestCase#runBare()} semantics, this
+	 * <p>
+	 * In addition to standard {@link TestCase#runBare()} semantics, this
 	 * implementation performs the following:
 	 * <ul>
-	 * <li>Calls
-	 * {@link TestContextManager#prepareTestInstance(Object) prepareTestInstance()},
-	 * {@link TestContextManager#beforeTestMethod(Object,Method) beforeTestMethod()},
-	 * and
-	 * {@link TestContextManager#afterTestMethod(Object,Method,Throwable) afterTestMethod()}
-	 * on this test's {@link TestContextManager} at the appropriate test
-	 * execution points.</li>
-	 * <li>Provides support for {@link IfProfileValue @IfProfileValue}.</li>
-	 * <li>Provides support for {@link Repeat @Repeat}.</li>
-	 * <li>Provides support for {@link Timed @Timed}.</li>
-	 * <li>Provides support for {@link ExpectedException @ExpectedException}.</li>
+	 * <li>Calls {@link TestContextManager#prepareTestInstance(Object)
+	 * prepareTestInstance()},
+	 * {@link TestContextManager#beforeTestMethod(Object,Method)
+	 * beforeTestMethod()}, and
+	 * {@link TestContextManager#afterTestMethod(Object,Method,Throwable)
+	 * afterTestMethod()} on this test's {@link TestContextManager} at the
+	 * appropriate test execution points.</li>
+	 * <li>Provides support for {@link IfProfileValue &#064;IfProfileValue}.</li>
+	 * <li>Provides support for {@link Repeat &#064;Repeat}.</li>
+	 * <li>Provides support for {@link Timed &#064;Timed}.</li>
+	 * <li>Provides support for {@link ExpectedException
+	 * &#064;ExpectedException}.</li>
 	 * </ul>
+	 * 
 	 * @see ProfileValueUtils#isTestEnabledInThisEnvironment
 	 */
 	@Override
@@ -189,6 +211,7 @@ public void runBare() throws Throwable {
 		}
 
 		runTestTimed(new TestExecutionCallback() {
+
 			public void run() throws Throwable {
 				runManaged(testMethod);
 			}
@@ -214,10 +237,12 @@ private Method getTestMethod() {
 	}
 
 	/**
-	 * Runs a <em>timed</em> test via the supplied {@link TestExecutionCallback},
-	 * providing support for the {@link Timed @Timed} annotation.
+	 * Runs a <em>timed</em> test via the supplied {@link TestExecutionCallback}
+	 * , providing support for the {@link Timed &#064;Timed} annotation.
+	 * 
 	 * @param tec the test execution callback to run
-	 * @param testMethod the actual test method: used to retrieve the <code>timeout</code>
+	 * @param testMethod the actual test method: used to retrieve the
+	 * <code>timeout</code>
 	 * @throws Throwable if any exception is thrown
 	 * @see Timed
 	 * @see #runTest
@@ -243,21 +268,22 @@ private void runTestTimed(TestExecutionCallback tec, Method testMethod) throws T
 
 	/**
 	 * Runs a test via the supplied {@link TestExecutionCallback}, providing
-	 * support for the {@link ExpectedException @ExpectedException} and
-	 * {@link Repeat @Repeat} annotations.
+	 * support for the {@link ExpectedException &#064;ExpectedException} and
+	 * {@link Repeat &#064;Repeat} annotations.
+	 * 
 	 * @param tec the test execution callback to run
 	 * @param testMethod the actual test method: used to retrieve the
-	 * {@link ExpectedException @ExpectedException} and {@link Repeat @Repeat} annotations
+	 * {@link ExpectedException &#064;ExpectedException} and {@link Repeat
+	 * &#064;Repeat} annotations
 	 * @throws Throwable if any exception is thrown
 	 * @see ExpectedException
 	 * @see Repeat
 	 */
 	private void runTest(TestExecutionCallback tec, Method testMethod) throws Throwable {
 		ExpectedException expectedExceptionAnnotation = testMethod.getAnnotation(ExpectedException.class);
-		boolean exceptionIsExpected = (expectedExceptionAnnotation != null &&
-				expectedExceptionAnnotation.value() != null);
-		Class<? extends Throwable> expectedException =
-				(exceptionIsExpected ? expectedExceptionAnnotation.value() : null);
+		boolean exceptionIsExpected = (expectedExceptionAnnotation != null && expectedExceptionAnnotation.value() != null);
+		Class<? extends Throwable> expectedException = (exceptionIsExpected ? expectedExceptionAnnotation.value()
+				: null);
 
 		Repeat repeat = testMethod.getAnnotation(Repeat.class);
 		int runs = ((repeat != null) && (repeat.value() > 1)) ? repeat.value() : 1;
@@ -278,8 +304,8 @@ private void runTest(TestExecutionCallback tec, Method testMethod) throws Throwa
 				}
 				if (!expectedException.isAssignableFrom(ex.getClass())) {
 					// Wrap the unexpected throwable with an explicit message.
-					AssertionFailedError assertionError = new AssertionFailedError("Unexpected exception, expected <" +
-							expectedException.getName() + "> but was <" + ex.getClass().getName() + ">");
+					AssertionFailedError assertionError = new AssertionFailedError("Unexpected exception, expected <"
+							+ expectedException.getName() + "> but was <" + ex.getClass().getName() + ">");
 					assertionError.initCause(ex);
 					throw assertionError;
 				}
@@ -291,6 +317,7 @@ private void runTest(TestExecutionCallback tec, Method testMethod) throws Throwa
 	 * Calls {@link TestContextManager#beforeTestMethod(Object,Method)} and
 	 * {@link TestContextManager#afterTestMethod(Object,Method,Throwable)} at
 	 * the appropriate test execution points.
+	 * 
 	 * @param testMethod the test method to run
 	 * @throws Throwable if any exception is thrown
 	 * @see #runBare()
@@ -344,6 +371,7 @@ private void runManaged(Method testMethod) throws Throwable {
 	 * Records the supplied test method as <em>disabled</em> in the current
 	 * environment by incrementing the total number of disabled tests and
 	 * logging a debug message.
+	 * 
 	 * @param testMethod the test method that is disabled.
 	 * @see #getDisabledTestCount()
 	 */
@@ -357,8 +385,8 @@ protected void recordDisabled(Method testMethod) {
 
 
 	/**
-	 * Private inner class that defines a callback analogous to
-	 * {@link Runnable}, just declaring Throwable.
+	 * Private inner class that defines a callback analogous to {@link Runnable}
+	 * , just declaring Throwable.
 	 */
 	private static interface TestExecutionCallback {