Improve docs on SseEmitter onComplete/onError

Issue: SPR-16548

spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/ResponseBodyEmitter.java

@@ -66,13 +66,16 @@ public class ResponseBodyEmitter {
 	@Nullable
 	private final Long timeout;
 
-	private final Set<DataWithMediaType> earlySendAttempts = new LinkedHashSet<>(8);
-
 	@Nullable
 	private Handler handler;
 
+	/** Store send data before handler is initialized */
+	private final Set<DataWithMediaType> earlySendAttempts = new LinkedHashSet<>(8);
+
+	/** Store complete invocation before handler is initialized */
 	private boolean complete;
 
+	/** Store completeWithError invocation before handler is initialized */
 	@Nullable
 	private Throwable failure;
 
@@ -147,6 +150,11 @@ public class ResponseBodyEmitter {
 	 * Write the given object to the response.
 	 * <p>If any exception occurs a dispatch is made back to the app server where
 	 * Spring MVC will pass the exception through its exception handling mechanism.
+	 * <p><strong>Note:</strong> if the send fails with an IOException, you do
+	 * not need to call {@link #completeWithError(Throwable)} in order to clean
+	 * up. Instead the Servlet container creates a notification that results in a
+	 * dispatch where Spring MVC invokes exception resolvers and completes
+	 * processing.
 	 * @param object the object to write
 	 * @throws IOException raised when an I/O error occurs
 	 * @throws java.lang.IllegalStateException wraps any other errors
@@ -156,9 +164,8 @@ public class ResponseBodyEmitter {
 	}
 
 	/**
-	 * Write the given object to the response also using a MediaType hint.
-	 * <p>If any exception occurs a dispatch is made back to the app server where
-	 * Spring MVC will pass the exception through its exception handling mechanism.
+	 * Overloaded variant of {@link #send(Object)} that also accepts a MediaType
+	 * hint for how to serialize the given Object.
 	 * @param object the object to write
 	 * @param mediaType a MediaType hint for selecting an HttpMessageConverter
 	 * @throws IOException raised when an I/O error occurs
@@ -187,13 +194,12 @@ public class ResponseBodyEmitter {
 	}
 
 	/**
-	 * Complete request processing.
-	 * <p>A dispatch is made into the app server where Spring MVC completes
-	 * asynchronous request processing.
-	 * <p><strong>Note:</strong> you do not need to call this method after an
-	 * {@link IOException} from any of the {@code send} methods. The Servlet
-	 * container will generate an error notification that Spring MVC will process
-	 * and handle through the exception resolver mechanism and then complete.
+	 * Complete request processing by performing a dispatch into the servlet
+	 * container, where Spring MVC is invoked once more, and completes the
+	 * request processing lifecycle.
+	 * <p><strong>Note:</strong> this method should be called by the application
+	 * to complete request processing. It should not be used after container
+	 * related events such as an error while {@link #send(Object) sending}.
 	 */
 	public synchronized void complete() {
 		this.complete = true;
@@ -205,7 +211,13 @@ public class ResponseBodyEmitter {
 	/**
 	 * Complete request processing with an error.
 	 * <p>A dispatch is made into the app server where Spring MVC will pass the
-	 * exception through its exception handling mechanism.
+	 * exception through its exception handling mechanism. Note however that
+	 * at this stage of request processing, the response is committed and the
+	 * response status can no longer be changed.
+	 * <p><strong>Note:</strong> this method should be called by the application
+	 * to complete request processing with an error. It should not be used after
+	 * container related events such as an error while
+	 * {@link #send(Object) sending}.
 	 */
 	public synchronized void completeWithError(Throwable ex) {
 		this.complete = true;

spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/SseEmitter.java

@@ -82,6 +82,10 @@ public class SseEmitter extends ResponseBodyEmitter {
 	 * SseEmitter emitter = new SseEmitter();
 	 * emitter.send(event().data(myObject));
 	 * </pre>
+	 *
+	 * <p>Please, see {@link ResponseBodyEmitter#send(Object) parent Javadoc}
+	 * for important notes on exception handling.
+	 *
 	 * @param object the object to write
 	 * @throws IOException raised when an I/O error occurs
 	 * @throws java.lang.IllegalStateException wraps any other errors
@@ -99,6 +103,10 @@ public class SseEmitter extends ResponseBodyEmitter {
 	 * SseEmitter emitter = new SseEmitter();
 	 * emitter.send(event().data(myObject, MediaType.APPLICATION_JSON));
 	 * </pre>
+	 *
+	 * <p>Please, see {@link ResponseBodyEmitter#send(Object) parent Javadoc}
+	 * for important notes on exception handling.
+	 *
 	 * @param object the object to write
 	 * @param mediaType a MediaType hint for selecting an HttpMessageConverter
 	 * @throws IOException raised when an I/O error occurs