Explicit javadoc note on publishEvent hand-off semantics

See gh-21025

Author: jhoeller

Diff for: spring-context/src/main/java/org/springframework/context/ApplicationEventPublisher.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2019 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.
@@ -18,14 +18,16 @@
 
 /**
  * Interface that encapsulates event publication functionality.
- * Serves as super-interface for {@link ApplicationContext}.
+ *
+ * <p>Serves as a super-interface for {@link ApplicationContext}.
  *
  * @author Juergen Hoeller
  * @author Stephane Nicoll
  * @since 1.1.1
  * @see ApplicationContext
  * @see ApplicationEventPublisherAware
  * @see org.springframework.context.ApplicationEvent
+ * @see org.springframework.context.event.ApplicationEventMulticaster
  * @see org.springframework.context.event.EventPublicationInterceptor
  */
 @FunctionalInterface
@@ -34,9 +36,16 @@ public interface ApplicationEventPublisher {
 	/**
 	 * Notify all <strong>matching</strong> listeners registered with this
 	 * application of an application event. Events may be framework events
-	 * (such as RequestHandledEvent) or application-specific events.
+	 * (such as ContextRefreshedEvent) or application-specific events.
+	 * <p>Such an event publication step is effectively a hand-off to the
+	 * multicaster and does not imply synchronous/asynchronous execution
+	 * or even immediate execution at all. Event listeners are encouraged
+	 * to be as efficient as possible, individually using asynchronous
+	 * execution for longer-running and potentially blocking operations.
 	 * @param event the event to publish
-	 * @see org.springframework.web.context.support.RequestHandledEvent
+	 * @see #publishEvent(Object)
+	 * @see org.springframework.context.event.ContextRefreshedEvent
+	 * @see org.springframework.context.event.ContextClosedEvent
 	 */
 	default void publishEvent(ApplicationEvent event) {
 		publishEvent((Object) event);
@@ -47,8 +56,14 @@ default void publishEvent(ApplicationEvent event) {
 	 * application of an event.
 	 * <p>If the specified {@code event} is not an {@link ApplicationEvent},
 	 * it is wrapped in a {@link PayloadApplicationEvent}.
+	 * <p>Such an event publication step is effectively a hand-off to the
+	 * multicaster and does not imply synchronous/asynchronous execution
+	 * or even immediate execution at all. Event listeners are encouraged
+	 * to be as efficient as possible, individually using asynchronous
+	 * execution for longer-running and potentially blocking operations.
 	 * @param event the event to publish
 	 * @since 4.2
+	 * @see #publishEvent(ApplicationEvent)
 	 * @see PayloadApplicationEvent
 	 */
 	void publishEvent(Object event);