Polish support for publishing TestContext lifecycle events

See gh-18490

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

@@ -44,6 +44,8 @@ package org.springframework.test.context;
  * <p>Spring provides the following out-of-the-box implementations (all of
  * which implement {@code Ordered}):
  * <ul>
+ * <li>{@link org.springframework.test.context.event.EventPublishingTestExecutionListener
+ * EventPublishingTestExecutionListener} (not registered by default)</li>
  * <li>{@link org.springframework.test.context.web.ServletTestExecutionListener
  * ServletTestExecutionListener}</li>
  * <li>{@link org.springframework.test.context.support.DirtiesContextBeforeModesTestExecutionListener
@@ -56,13 +58,12 @@ package org.springframework.test.context;
  * TransactionalTestExecutionListener}</li>
  * <li>{@link org.springframework.test.context.jdbc.SqlScriptsTestExecutionListener
  * SqlScriptsTestExecutionListener}</li>
- * <li>{@link org.springframework.test.context.event.EventPublishingTestExecutionListener
- * EventPublishingTestExecutionListener} (not registered by default)</li>
  * </ul>
  *
  * @author Sam Brannen
  * @author Juergen Hoeller
  * @since 2.5
+ * @see TestExecutionListeners @TestExecutionListeners
  * @see TestContextManager
  * @see org.springframework.test.context.support.AbstractTestExecutionListener
  */

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

@@ -61,12 +61,13 @@ public @interface TestExecutionListeners {
 	 * the {@link TestContextManager}.
 	 * <p>This attribute may <strong>not</strong> be used in conjunction with
 	 * {@link #value}, but it may be used instead of {@link #value}.
+	 * @see org.springframework.test.context.event.EventPublishingTestExecutionListener
 	 * @see org.springframework.test.context.web.ServletTestExecutionListener
+	 * @see org.springframework.test.context.support.DirtiesContextBeforeModesTestExecutionListener
 	 * @see org.springframework.test.context.support.DependencyInjectionTestExecutionListener
 	 * @see org.springframework.test.context.support.DirtiesContextTestExecutionListener
 	 * @see org.springframework.test.context.transaction.TransactionalTestExecutionListener
 	 * @see org.springframework.test.context.jdbc.SqlScriptsTestExecutionListener
-	 * @see org.springframework.test.context.event.EventPublishingTestExecutionListener
 	 */
 	@AliasFor("value")
 	Class<? extends TestExecutionListener>[] listeners() default {};

spring-test/src/main/java/org/springframework/test/context/event/AfterTestClassEvent.java

@@ -19,17 +19,19 @@ package org.springframework.test.context.event;
 import org.springframework.test.context.TestContext;
 
 /**
- * {@link TestContextEvent} published by {@link EventPublishingTestExecutionListener} when
- * {@link org.springframework.test.context.TestExecutionListener#afterTestClass(TestContext)} is called.
+ * {@link TestContextEvent} published by the {@link EventPublishingTestExecutionListener} when
+ * {@link org.springframework.test.context.TestExecutionListener#afterTestClass(TestContext)}
+ * is invoked.
  *
  * @author Frank Scheffler
  * @since 5.2
- * @see org.springframework.test.context.event.annotation.AfterTestClass
+ * @see org.springframework.test.context.event.annotation.AfterTestClass @AfterTestClass
  */
 @SuppressWarnings("serial")
 public class AfterTestClassEvent extends TestContextEvent {
 
-    public AfterTestClassEvent(TestContext source) {
-        super(source);
-    }
+	public AfterTestClassEvent(TestContext source) {
+		super(source);
+	}
+
 }

spring-test/src/main/java/org/springframework/test/context/event/AfterTestExecutionEvent.java

@@ -19,18 +19,19 @@ package org.springframework.test.context.event;
 import org.springframework.test.context.TestContext;
 
 /**
- * {@link TestContextEvent} published by {@link EventPublishingTestExecutionListener} when
- * {@link org.springframework.test.context.TestExecutionListener#afterTestExecution(TestContext)} is called.
+ * {@link TestContextEvent} published by the {@link EventPublishingTestExecutionListener} when
+ * {@link org.springframework.test.context.TestExecutionListener#afterTestExecution(TestContext)}
+ * is invoked.
  *
  * @author Frank Scheffler
  * @since 5.2
- * @see org.springframework.test.context.event.annotation.AfterTestExecution
+ * @see org.springframework.test.context.event.annotation.AfterTestExecution @AfterTestExecution
  */
 @SuppressWarnings("serial")
 public class AfterTestExecutionEvent extends TestContextEvent {
 
-    public AfterTestExecutionEvent(TestContext source) {
-        super(source);
-    }
+	public AfterTestExecutionEvent(TestContext source) {
+		super(source);
+	}
 
 }

spring-test/src/main/java/org/springframework/test/context/event/AfterTestMethodEvent.java

@@ -19,18 +19,19 @@ package org.springframework.test.context.event;
 import org.springframework.test.context.TestContext;
 
 /**
- * {@link TestContextEvent} published by {@link EventPublishingTestExecutionListener} when
- * {@link org.springframework.test.context.TestExecutionListener#afterTestMethod(TestContext)} is called.
+ * {@link TestContextEvent} published by the {@link EventPublishingTestExecutionListener} when
+ * {@link org.springframework.test.context.TestExecutionListener#afterTestMethod(TestContext)}
+ * is invoked.
  *
  * @author Frank Scheffler
  * @since 5.2
- * @see org.springframework.test.context.event.annotation.AfterTestMethod
+ * @see org.springframework.test.context.event.annotation.AfterTestMethod @AfterTestMethod
  */
 @SuppressWarnings("serial")
 public class AfterTestMethodEvent extends TestContextEvent {
 
-    public AfterTestMethodEvent(TestContext source) {
-        super(source);
-    }
+	public AfterTestMethodEvent(TestContext source) {
+		super(source);
+	}
 
 }

spring-test/src/main/java/org/springframework/test/context/event/BeforeTestClassEvent.java

@@ -19,18 +19,19 @@ package org.springframework.test.context.event;
 import org.springframework.test.context.TestContext;
 
 /**
- * {@link TestContextEvent} published by {@link EventPublishingTestExecutionListener} when
- * {@link org.springframework.test.context.TestExecutionListener#beforeTestClass(TestContext)} is called.
+ * {@link TestContextEvent} published by the {@link EventPublishingTestExecutionListener} when
+ * {@link org.springframework.test.context.TestExecutionListener#beforeTestClass(TestContext)}
+ * is invoked.
  *
  * @author Frank Scheffler
  * @since 5.2
- * @see org.springframework.test.context.event.annotation.BeforeTestClass
+ * @see org.springframework.test.context.event.annotation.BeforeTestClass @BeforeTestClass
  */
 @SuppressWarnings("serial")
 public class BeforeTestClassEvent extends TestContextEvent {
 
-    public BeforeTestClassEvent(TestContext source) {
-        super(source);
-    }
+	public BeforeTestClassEvent(TestContext source) {
+		super(source);
+	}
 
 }

spring-test/src/main/java/org/springframework/test/context/event/BeforeTestExecutionEvent.java

@@ -19,18 +19,19 @@ package org.springframework.test.context.event;
 import org.springframework.test.context.TestContext;
 
 /**
- * {@link TestContextEvent} published by {@link EventPublishingTestExecutionListener} when
- * {@link org.springframework.test.context.TestExecutionListener#beforeTestExecution(TestContext)} is called.
+ * {@link TestContextEvent} published by the {@link EventPublishingTestExecutionListener} when
+ * {@link org.springframework.test.context.TestExecutionListener#beforeTestExecution(TestContext)}
+ * is invoked.
  *
  * @author Frank Scheffler
  * @since 5.2
- * @see org.springframework.test.context.event.annotation.BeforeTestExecution
+ * @see org.springframework.test.context.event.annotation.BeforeTestExecution @BeforeTestExecution
  */
 @SuppressWarnings("serial")
 public class BeforeTestExecutionEvent extends TestContextEvent {
 
-    public BeforeTestExecutionEvent(TestContext source) {
-        super(source);
-    }
+	public BeforeTestExecutionEvent(TestContext source) {
+		super(source);
+	}
 
 }

spring-test/src/main/java/org/springframework/test/context/event/BeforeTestMethodEvent.java

@@ -19,18 +19,19 @@ package org.springframework.test.context.event;
 import org.springframework.test.context.TestContext;
 
 /**
- * {@link TestContextEvent} published by {@link EventPublishingTestExecutionListener} when
- * {@link org.springframework.test.context.TestExecutionListener#beforeTestMethod(TestContext)} is called.
+ * {@link TestContextEvent} published by the {@link EventPublishingTestExecutionListener} when
+ * {@link org.springframework.test.context.TestExecutionListener#beforeTestMethod(TestContext)}
+ * is invoked.
  *
  * @author Frank Scheffler
  * @since 5.2
- * @see org.springframework.test.context.event.annotation.BeforeTestMethod
+ * @see org.springframework.test.context.event.annotation.BeforeTestMethod @BeforeTestMethod
  */
 @SuppressWarnings("serial")
 public class BeforeTestMethodEvent extends TestContextEvent {
 
-    public BeforeTestMethodEvent(TestContext source) {
-        super(source);
-    }
+	public BeforeTestMethodEvent(TestContext source) {
+		super(source);
+	}
 
 }

spring-test/src/main/java/org/springframework/test/context/event/EventPublishingTestExecutionListener.java

@@ -16,72 +16,119 @@
 
 package org.springframework.test.context.event;
 
+import org.springframework.core.Ordered;
 import org.springframework.test.context.TestContext;
 import org.springframework.test.context.support.AbstractTestExecutionListener;
 
 /**
- * {@link org.springframework.test.context.TestExecutionListener} that may be used to publish test life-cycle event to
- * the Spring test {@link org.springframework.context.ApplicationContext}.
+ * {@link org.springframework.test.context.TestExecutionListener TestExecutionListener}
+ * that publishes test lifecycle events to a Spring test
+ * {@link org.springframework.context.ApplicationContext ApplicationContext}.
  *
- * <p>These events may be consumed for various reasons, such as resetting {@em mock} beans or tracing test
- * execution. Since these events may consumed as part of regular Spring beans, they can be shared among
- * different test classes.
+ * <p>These events may be consumed for various reasons, such as resetting <em>mock</em>
+ * beans or tracing test execution. Since these events may be consumed by regular
+ * Spring beans, they can be shared among different test classes.
+ * 
+ * <h3>Supported Events</h3>
+ * <ul>
+ * <li>{@link BeforeTestClassEvent}</li>
+ * <li>{@link PrepareTestInstanceEvent}</li>
+ * <li>{@link BeforeTestMethodEvent}</li>
+ * <li>{@link BeforeTestExecutionEvent}</li>
+ * <li>{@link AfterTestExecutionEvent}</li>
+ * <li>{@link AfterTestMethodEvent}</li>
+ * <li>{@link AfterTestClassEvent}</li>
+ * </ul>
  *
- * <p>This {@link org.springframework.test.context.TestExecutionListener} is not active by default. Test classes
- * should be annotated using {@link org.springframework.test.context.TestExecutionListeners}, if they want to use it.
- * Alternatively, it may be added to {@code spring.factories}, if needed.
+ * <p>Note that this {@code TestExecutionListener} is not registered by default,
+ * but it may be registered for a given test class via
+ * {@link org.springframework.test.context.TestExecutionListeners @TestExecutionListeners}
+ * or globally via the {@link org.springframework.core.io.support.SpringFactoriesLoader
+ * SpringFactoriesLoader} mechanism (consult the Javadoc and Spring reference manual for
+ * details).
  *
  * @author Frank Scheffler
+ * @author Sam Brannen
  * @since 5.2
- * @see org.springframework.test.context.event.annotation.BeforeTestClass
- * @see org.springframework.test.context.event.annotation.PrepareTestInstance
- * @see org.springframework.test.context.event.annotation.BeforeTestMethod
- * @see org.springframework.test.context.event.annotation.BeforeTestExecution
- * @see org.springframework.test.context.event.annotation.AfterTestExecution
- * @see org.springframework.test.context.event.annotation.AfterTestMethod
- * @see org.springframework.test.context.event.annotation.AfterTestClass
+ * @see org.springframework.test.context.event.annotation.BeforeTestClass @BeforeTestClass
+ * @see org.springframework.test.context.event.annotation.PrepareTestInstance @PrepareTestInstance
+ * @see org.springframework.test.context.event.annotation.BeforeTestMethod @BeforeTestMethod
+ * @see org.springframework.test.context.event.annotation.BeforeTestExecution @BeforeTestExecution
+ * @see org.springframework.test.context.event.annotation.AfterTestExecution @AfterTestExecution
+ * @see org.springframework.test.context.event.annotation.AfterTestMethod @AfterTestMethod
+ * @see org.springframework.test.context.event.annotation.AfterTestClass @AfterTestClass
  */
 public class EventPublishingTestExecutionListener extends AbstractTestExecutionListener {
 
-    @Override
-    public void beforeTestClass(TestContext testContext) {
-        testContext.getApplicationContext().publishEvent(
-                new BeforeTestClassEvent(testContext));
-    }
+	/**
+	 * Returns {@link Ordered#HIGHEST_PRECEDENCE}.
+	 */
+	@Override
+	public int getOrder() {
+		return Ordered.HIGHEST_PRECEDENCE;
+	}
 
-    @Override
-    public void prepareTestInstance(TestContext testContext) {
-        testContext.getApplicationContext().publishEvent(
-                new PrepareTestInstanceEvent(testContext));
-    }
+	/**
+	 * Publishes a {@link BeforeTestClassEvent} to the {@code ApplicationContext}
+	 * for the supplied {@link TestContext}.
+	 */
+	@Override
+	public void beforeTestClass(TestContext testContext) {
+		testContext.getApplicationContext().publishEvent(new BeforeTestClassEvent(testContext));
+	}
 
-    @Override
-    public void beforeTestMethod(TestContext testContext) {
-        testContext.getApplicationContext().publishEvent(
-                new BeforeTestMethodEvent(testContext));
-    }
+	/**
+	 * Publishes a {@link PrepareTestInstanceEvent} to the {@code ApplicationContext}
+	 * for the supplied {@link TestContext}.
+	 */
+	@Override
+	public void prepareTestInstance(TestContext testContext) {
+		testContext.getApplicationContext().publishEvent(new PrepareTestInstanceEvent(testContext));
+	}
 
-    @Override
-    public void beforeTestExecution(TestContext testContext) {
-        testContext.getApplicationContext().publishEvent(
-                new BeforeTestExecutionEvent(testContext));
-    }
+	/**
+	 * Publishes a {@link BeforeTestMethodEvent} to the {@code ApplicationContext}
+	 * for the supplied {@link TestContext}.
+	 */
+	@Override
+	public void beforeTestMethod(TestContext testContext) {
+		testContext.getApplicationContext().publishEvent(new BeforeTestMethodEvent(testContext));
+	}
 
-    @Override
-    public void afterTestExecution(TestContext testContext) {
-        testContext.getApplicationContext().publishEvent(
-                new AfterTestExecutionEvent(testContext));
-    }
+	/**
+	 * Publishes a {@link BeforeTestExecutionEvent} to the {@code ApplicationContext}
+	 * for the supplied {@link TestContext}.
+	 */
+	@Override
+	public void beforeTestExecution(TestContext testContext) {
+		testContext.getApplicationContext().publishEvent(new BeforeTestExecutionEvent(testContext));
+	}
 
-    @Override
-    public void afterTestMethod(TestContext testContext) {
-        testContext.getApplicationContext().publishEvent(
-                new AfterTestMethodEvent(testContext));
-    }
+	/**
+	 * Publishes an {@link AfterTestExecutionEvent} to the {@code ApplicationContext}
+	 * for the supplied {@link TestContext}.
+	 */
+	@Override
+	public void afterTestExecution(TestContext testContext) {
+		testContext.getApplicationContext().publishEvent(new AfterTestExecutionEvent(testContext));
+	}
+
+	/**
+	 * Publishes an {@link AfterTestMethodEvent} to the {@code ApplicationContext}
+	 * for the supplied {@link TestContext}.
+	 */
+	@Override
+	public void afterTestMethod(TestContext testContext) {
+		testContext.getApplicationContext().publishEvent(new AfterTestMethodEvent(testContext));
+	}
+
+	/**
+	 * Publishes an {@link AfterTestClassEvent} to the {@code ApplicationContext}
+	 * for the supplied {@link TestContext}.
+	 */
+	@Override
+	public void afterTestClass(TestContext testContext) {
+		testContext.getApplicationContext().publishEvent(new AfterTestClassEvent(testContext));
+	}
 
-    @Override
-    public void afterTestClass(TestContext testContext) {
-        testContext.getApplicationContext().publishEvent(
-                new AfterTestClassEvent(testContext));
-    }
 }

spring-test/src/main/java/org/springframework/test/context/event/PrepareTestInstanceEvent.java

@@ -19,18 +19,19 @@ package org.springframework.test.context.event;
 import org.springframework.test.context.TestContext;
 
 /**
- * {@link TestContextEvent} published by {@link EventPublishingTestExecutionListener} when
- * {@link org.springframework.test.context.TestExecutionListener#prepareTestInstance(TestContext)} is called.
+ * {@link TestContextEvent} published by the {@link EventPublishingTestExecutionListener} when
+ * {@link org.springframework.test.context.TestExecutionListener#prepareTestInstance(TestContext)}
+ * is invoked.
  *
  * @author Frank Scheffler
  * @since 5.2
- * @see org.springframework.test.context.event.annotation.PrepareTestInstance
+ * @see org.springframework.test.context.event.annotation.PrepareTestInstance @PrepareTestInstance
  */
 @SuppressWarnings("serial")
 public class PrepareTestInstanceEvent extends TestContextEvent {
 
-    public PrepareTestInstanceEvent(TestContext source) {
-        super(source);
-    }
+	public PrepareTestInstanceEvent(TestContext source) {
+		super(source);
+	}
 
 }

spring-test/src/main/java/org/springframework/test/context/event/TestContextEvent.java

@@ -20,25 +20,31 @@ import org.springframework.context.ApplicationEvent;
 import org.springframework.test.context.TestContext;
 
 /**
- * Base class for events published by {@link EventPublishingTestExecutionListener}.
+ * Base class for events published by the {@link EventPublishingTestExecutionListener}.
  *
  * @author Frank Scheffler
+ * @author Sam Brannen
  * @since 5.2
  */
 @SuppressWarnings("serial")
 public abstract class TestContextEvent extends ApplicationEvent {
 
-    public TestContextEvent(TestContext source) {
-        super(source);
-    }
+	/**
+	 * Create a new {@code TestContextEvent}.
+	 * @param source the {@code TestContext} associated with this event
+	 * (must not be {@code null})
+	 */
+	public TestContextEvent(TestContext source) {
+		super(source);
+	}
+
+	/**
+	 * Get the {@code TestContext} associated with this event.
+	 * @return the {@code TestContext} associated with this event (never {@code null})
+	 */
+	@Override
+	public TestContext getSource() {
+		return (TestContext) super.getSource();
+	}
 
-    /*
-     * (non-Javadoc)
-     *
-     * @see java.util.EventObject#getSource()
-     */
-    @Override
-    public TestContext getSource() {
-        return (TestContext) super.getSource();
-    }
 }

spring-test/src/main/java/org/springframework/test/context/event/annotation/AfterTestClass.java

@@ -16,30 +16,34 @@
 
 package org.springframework.test.context.event.annotation;
 
-import org.springframework.context.event.EventListener;
-import org.springframework.test.context.event.AfterTestClassEvent;
-
 import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
+import org.springframework.context.event.EventListener;
+import org.springframework.test.context.event.AfterTestClassEvent;
+
 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * {@link EventListener} annotation used to consume {@link AfterTestClassEvent}s published
- * by {@link org.springframework.test.context.event.EventPublishingTestExecutionListener}.
+ * {@link EventListener @EventListener} annotation used to consume a
+ * {@link AfterTestClassEvent} published by the
+ * {@link org.springframework.test.context.event.EventPublishingTestExecutionListener
+ * EventPublishingTestExecutionListener}.
  *
- * <p>This annotation may be used on {@link EventListener}-compliant methods within the Spring test
- * {@link org.springframework.context.ApplicationContext}, typically within
- * {@link org.springframework.context.annotation.Configuration}s. A method annotated hereby will be
- * called as part of the {@link org.springframework.test.context.TestExecutionListener#afterTestClass(org.springframework.test.context.TestContext)}
- * life-cycle method.
+ * <p>This annotation may be used on {@code @EventListener}-compliant methods within
+ * a Spring test {@link org.springframework.context.ApplicationContext ApplicationContext}
+ * &mdash; for example, on methods in a
+ * {@link org.springframework.context.annotation.Configuration @Configuration}
+ * class. A method annotated with this annotation will be invoked as part of the
+ * {@link org.springframework.test.context.TestExecutionListener#afterTestClass}
+ * lifecycle.
  *
- * <p>Make sure {@link org.springframework.test.context.event.EventPublishingTestExecutionListener} is enabled,
- * for this annotation to have an effect, e.g. by annotation your test class with
- * {@link org.springframework.test.context.TestExecutionListeners} accordingly.
+ * <p>The {@code EventPublishingTestExecutionListener} must be registered in order
+ * for this annotation to have an effect &mdash; for example, via
+ * {@link org.springframework.test.context.TestExecutionListeners @TestExecutionListeners}.
  *
  * @author Frank Scheffler
  * @since 5.2
@@ -47,7 +51,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  */
 @Documented
 @Retention(RUNTIME)
-@Target({METHOD, ANNOTATION_TYPE})
+@Target({ METHOD, ANNOTATION_TYPE })
 @EventListener(AfterTestClassEvent.class)
 public @interface AfterTestClass {
 }

spring-test/src/main/java/org/springframework/test/context/event/annotation/AfterTestExecution.java

@@ -16,30 +16,34 @@
 
 package org.springframework.test.context.event.annotation;
 
-import org.springframework.context.event.EventListener;
-import org.springframework.test.context.event.AfterTestExecutionEvent;
-
 import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
+import org.springframework.context.event.EventListener;
+import org.springframework.test.context.event.AfterTestExecutionEvent;
+
 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * {@link EventListener} annotation used to consume {@link AfterTestExecutionEvent}s published
- * by {@link org.springframework.test.context.event.EventPublishingTestExecutionListener}.
+ * {@link EventListener @EventListener} annotation used to consume a
+ * {@link AfterTestExecutionEvent} published by the
+ * {@link org.springframework.test.context.event.EventPublishingTestExecutionListener
+ * EventPublishingTestExecutionListener}.
  *
- * <p>This annotation may be used on {@link EventListener}-compliant methods within the Spring test
- * {@link org.springframework.context.ApplicationContext}, typically within
- * {@link org.springframework.context.annotation.Configuration}s. A method annotated hereby will be
- * called as part of the {@link org.springframework.test.context.TestExecutionListener#afterTestExecution(org.springframework.test.context.TestContext)}
- * life-cycle method.
+ * <p>This annotation may be used on {@code @EventListener}-compliant methods within
+ * a Spring test {@link org.springframework.context.ApplicationContext ApplicationContext}
+ * &mdash; for example, on methods in a
+ * {@link org.springframework.context.annotation.Configuration @Configuration}
+ * class. A method annotated with this annotation will be invoked as part of the
+ * {@link org.springframework.test.context.TestExecutionListener#afterTestExecution}
+ * lifecycle.
  *
- * <p>Make sure {@link org.springframework.test.context.event.EventPublishingTestExecutionListener} is enabled,
- * for this annotation to have an effect, e.g. by annotation your test class with
- * {@link org.springframework.test.context.TestExecutionListeners} accordingly.
+ * <p>The {@code EventPublishingTestExecutionListener} must be registered in order
+ * for this annotation to have an effect &mdash; for example, via
+ * {@link org.springframework.test.context.TestExecutionListeners @TestExecutionListeners}.
  *
  * @author Frank Scheffler
  * @since 5.2
@@ -47,7 +51,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  */
 @Documented
 @Retention(RUNTIME)
-@Target({METHOD, ANNOTATION_TYPE})
+@Target({ METHOD, ANNOTATION_TYPE })
 @EventListener(AfterTestExecutionEvent.class)
 public @interface AfterTestExecution {
 }

spring-test/src/main/java/org/springframework/test/context/event/annotation/AfterTestMethod.java

@@ -16,30 +16,34 @@
 
 package org.springframework.test.context.event.annotation;
 
-import org.springframework.context.event.EventListener;
-import org.springframework.test.context.event.AfterTestMethodEvent;
-
 import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
+import org.springframework.context.event.EventListener;
+import org.springframework.test.context.event.AfterTestMethodEvent;
+
 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * {@link EventListener} annotation used to consume {@link AfterTestMethodEvent}s published
- * by {@link org.springframework.test.context.event.EventPublishingTestExecutionListener}.
+ * {@link EventListener @EventListener} annotation used to consume a
+ * {@link AfterTestMethodEvent} published by the
+ * {@link org.springframework.test.context.event.EventPublishingTestExecutionListener
+ * EventPublishingTestExecutionListener}.
  *
- * <p>This annotation may be used on {@link EventListener}-compliant methods within the Spring test
- * {@link org.springframework.context.ApplicationContext}, typically within
- * {@link org.springframework.context.annotation.Configuration}s. A method annotated hereby will be
- * called as part of the {@link org.springframework.test.context.TestExecutionListener#afterTestMethod(org.springframework.test.context.TestContext)}
- * life-cycle method.
+ * <p>This annotation may be used on {@code @EventListener}-compliant methods within
+ * a Spring test {@link org.springframework.context.ApplicationContext ApplicationContext}
+ * &mdash; for example, on methods in a
+ * {@link org.springframework.context.annotation.Configuration @Configuration}
+ * class. A method annotated with this annotation will be invoked as part of the
+ * {@link org.springframework.test.context.TestExecutionListener#afterTestMethod}
+ * lifecycle.
  *
- * <p>Make sure {@link org.springframework.test.context.event.EventPublishingTestExecutionListener} is enabled,
- * for this annotation to have an effect, e.g. by annotation your test class with
- * {@link org.springframework.test.context.TestExecutionListeners} accordingly.
+ * <p>The {@code EventPublishingTestExecutionListener} must be registered in order
+ * for this annotation to have an effect &mdash; for example, via
+ * {@link org.springframework.test.context.TestExecutionListeners @TestExecutionListeners}.
  *
  * @author Frank Scheffler
  * @since 5.2
@@ -47,7 +51,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  */
 @Documented
 @Retention(RUNTIME)
-@Target({METHOD, ANNOTATION_TYPE})
+@Target({ METHOD, ANNOTATION_TYPE })
 @EventListener(AfterTestMethodEvent.class)
 public @interface AfterTestMethod {
 }

spring-test/src/main/java/org/springframework/test/context/event/annotation/BeforeTestClass.java

@@ -16,30 +16,34 @@
 
 package org.springframework.test.context.event.annotation;
 
-import org.springframework.context.event.EventListener;
-import org.springframework.test.context.event.BeforeTestClassEvent;
-
 import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
+import org.springframework.context.event.EventListener;
+import org.springframework.test.context.event.BeforeTestClassEvent;
+
 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * {@link EventListener} annotation used to consume {@link BeforeTestClassEvent}s published
- * by {@link org.springframework.test.context.event.EventPublishingTestExecutionListener}.
+ * {@link EventListener @EventListener} annotation used to consume a
+ * {@link BeforeTestClassEvent} published by the
+ * {@link org.springframework.test.context.event.EventPublishingTestExecutionListener
+ * EventPublishingTestExecutionListener}.
  *
- * <p>This annotation may be used on {@link EventListener}-compliant methods within the Spring test
- * {@link org.springframework.context.ApplicationContext}, typically within
- * {@link org.springframework.context.annotation.Configuration}s. A method annotated hereby will be
- * called as part of the {@link org.springframework.test.context.TestExecutionListener#beforeTestClass(org.springframework.test.context.TestContext)}
- * life-cycle method.
+ * <p>This annotation may be used on {@code @EventListener}-compliant methods within
+ * a Spring test {@link org.springframework.context.ApplicationContext ApplicationContext}
+ * &mdash; for example, on methods in a
+ * {@link org.springframework.context.annotation.Configuration @Configuration}
+ * class. A method annotated with this annotation will be invoked as part of the
+ * {@link org.springframework.test.context.TestExecutionListener#beforeTestClass}
+ * lifecycle.
  *
- * <p>Make sure {@link org.springframework.test.context.event.EventPublishingTestExecutionListener} is enabled,
- * for this annotation to have an effect, e.g. by annotation your test class with
- * {@link org.springframework.test.context.TestExecutionListeners} accordingly.
+ * <p>The {@code EventPublishingTestExecutionListener} must be registered in order
+ * for this annotation to have an effect &mdash; for example, via
+ * {@link org.springframework.test.context.TestExecutionListeners @TestExecutionListeners}.
  *
  * @author Frank Scheffler
  * @since 5.2
@@ -47,7 +51,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  */
 @Documented
 @Retention(RUNTIME)
-@Target({METHOD, ANNOTATION_TYPE})
+@Target({ METHOD, ANNOTATION_TYPE })
 @EventListener(BeforeTestClassEvent.class)
 public @interface BeforeTestClass {
 }

spring-test/src/main/java/org/springframework/test/context/event/annotation/BeforeTestExecution.java

@@ -16,30 +16,34 @@
 
 package org.springframework.test.context.event.annotation;
 
-import org.springframework.context.event.EventListener;
-import org.springframework.test.context.event.BeforeTestExecutionEvent;
-
 import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
+import org.springframework.context.event.EventListener;
+import org.springframework.test.context.event.BeforeTestExecutionEvent;
+
 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * {@link EventListener} annotation used to consume {@link BeforeTestExecutionEvent}s published
- * by {@link org.springframework.test.context.event.EventPublishingTestExecutionListener}.
+ * {@link EventListener @EventListener} annotation used to consume a
+ * {@link BeforeTestExecution} published by the
+ * {@link org.springframework.test.context.event.EventPublishingTestExecutionListener
+ * EventPublishingTestExecutionListener}.
  *
- * <p>This annotation may be used on {@link EventListener}-compliant methods within the Spring test
- * {@link org.springframework.context.ApplicationContext}, typically within
- * {@link org.springframework.context.annotation.Configuration}s. A method annotated hereby will be
- * called as part of the {@link org.springframework.test.context.TestExecutionListener#beforeTestExecution(org.springframework.test.context.TestContext)}
- * life-cycle method.
+ * <p>This annotation may be used on {@code @EventListener}-compliant methods within
+ * a Spring test {@link org.springframework.context.ApplicationContext ApplicationContext}
+ * &mdash; for example, on methods in a
+ * {@link org.springframework.context.annotation.Configuration @Configuration}
+ * class. A method annotated with this annotation will be invoked as part of the
+ * {@link org.springframework.test.context.TestExecutionListener#beforeTestExecution}
+ * lifecycle.
  *
- * <p>Make sure {@link org.springframework.test.context.event.EventPublishingTestExecutionListener} is enabled,
- * for this annotation to have an effect, e.g. by annotation your test class with
- * {@link org.springframework.test.context.TestExecutionListeners} accordingly.
+ * <p>The {@code EventPublishingTestExecutionListener} must be registered in order
+ * for this annotation to have an effect &mdash; for example, via
+ * {@link org.springframework.test.context.TestExecutionListeners @TestExecutionListeners}.
  *
  * @author Frank Scheffler
  * @since 5.2
@@ -47,7 +51,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  */
 @Documented
 @Retention(RUNTIME)
-@Target({METHOD, ANNOTATION_TYPE})
+@Target({ METHOD, ANNOTATION_TYPE })
 @EventListener(BeforeTestExecutionEvent.class)
 public @interface BeforeTestExecution {
 }

spring-test/src/main/java/org/springframework/test/context/event/annotation/BeforeTestMethod.java

@@ -16,30 +16,34 @@
 
 package org.springframework.test.context.event.annotation;
 
-import org.springframework.context.event.EventListener;
-import org.springframework.test.context.event.BeforeTestMethodEvent;
-
 import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
+import org.springframework.context.event.EventListener;
+import org.springframework.test.context.event.BeforeTestMethodEvent;
+
 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * {@link EventListener} annotation used to consume {@link BeforeTestMethodEvent}s published
- * by {@link org.springframework.test.context.event.EventPublishingTestExecutionListener}.
+ * {@link EventListener @EventListener} annotation used to consume a
+ * {@link BeforeTestMethodEvent} published by the
+ * {@link org.springframework.test.context.event.EventPublishingTestExecutionListener
+ * EventPublishingTestExecutionListener}.
  *
- * <p>This annotation may be used on {@link EventListener}-compliant methods within the Spring test
- * {@link org.springframework.context.ApplicationContext}, typically within
- * {@link org.springframework.context.annotation.Configuration}s. A method annotated hereby will be
- * called as part of the {@link org.springframework.test.context.TestExecutionListener#beforeTestMethod(org.springframework.test.context.TestContext)}
- * life-cycle method.
+ * <p>This annotation may be used on {@code @EventListener}-compliant methods within
+ * a Spring test {@link org.springframework.context.ApplicationContext ApplicationContext}
+ * &mdash; for example, on methods in a
+ * {@link org.springframework.context.annotation.Configuration @Configuration}
+ * class. A method annotated with this annotation will be invoked as part of the
+ * {@link org.springframework.test.context.TestExecutionListener#beforeTestMethod}
+ * lifecycle.
  *
- * <p>Make sure {@link org.springframework.test.context.event.EventPublishingTestExecutionListener} is enabled,
- * for this annotation to have an effect, e.g. by annotation your test class with
- * {@link org.springframework.test.context.TestExecutionListeners} accordingly.
+ * <p>The {@code EventPublishingTestExecutionListener} must be registered in order
+ * for this annotation to have an effect &mdash; for example, via
+ * {@link org.springframework.test.context.TestExecutionListeners @TestExecutionListeners}.
  *
  * @author Frank Scheffler
  * @since 5.2
@@ -47,7 +51,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  */
 @Documented
 @Retention(RUNTIME)
-@Target({METHOD, ANNOTATION_TYPE})
+@Target({ METHOD, ANNOTATION_TYPE })
 @EventListener(BeforeTestMethodEvent.class)
 public @interface BeforeTestMethod {
 }

spring-test/src/main/java/org/springframework/test/context/event/annotation/PrepareTestInstance.java

@@ -28,18 +28,22 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * {@link EventListener} annotation used to consume {@link PrepareTestInstanceEvent}s published
- * by {@link org.springframework.test.context.event.EventPublishingTestExecutionListener}.
+ * {@link EventListener @EventListener} annotation used to consume a
+ * {@link PrepareTestInstanceEvent} published by the
+ * {@link org.springframework.test.context.event.EventPublishingTestExecutionListener
+ * EventPublishingTestExecutionListener}.
  *
- * <p>This annotation may be used on {@link EventListener}-compliant methods within the Spring test
- * {@link org.springframework.context.ApplicationContext}, typically within
- * {@link org.springframework.context.annotation.Configuration}s. A method annotated hereby will be
- * called as part of the {@link org.springframework.test.context.TestExecutionListener#prepareTestInstance(org.springframework.test.context.TestContext)}
- * life-cycle method.
+ * <p>This annotation may be used on {@code @EventListener}-compliant methods within
+ * a Spring test {@link org.springframework.context.ApplicationContext ApplicationContext}
+ * &mdash; for example, on methods in a
+ * {@link org.springframework.context.annotation.Configuration @Configuration}
+ * class. A method annotated with this annotation will be invoked as part of the
+ * {@link org.springframework.test.context.TestExecutionListener#prepareTestInstance}
+ * lifecycle.
  *
- * <p>Make sure {@link org.springframework.test.context.event.EventPublishingTestExecutionListener} is enabled,
- * for this annotation to have an effect, e.g. by annotation your test class with
- * {@link org.springframework.test.context.TestExecutionListeners} accordingly.
+ * <p>The {@code EventPublishingTestExecutionListener} must be registered in order
+ * for this annotation to have an effect &mdash; for example, via
+ * {@link org.springframework.test.context.TestExecutionListeners @TestExecutionListeners}.
  *
  * @author Frank Scheffler
  * @since 5.2
@@ -47,7 +51,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  */
 @Documented
 @Retention(RUNTIME)
-@Target({METHOD, ANNOTATION_TYPE})
+@Target({ METHOD, ANNOTATION_TYPE })
 @EventListener(PrepareTestInstanceEvent.class)
 public @interface PrepareTestInstance {
 }