Apply suggestions from code review

Co-authored-by: Greg Wilkins <[email protected]>

api/src/main/java/jakarta/servlet/ReadListener.java

@@ -50,19 +50,20 @@ public interface ReadListener extends EventListener {
     void onAllDataRead() throws IOException;
 
     /**
-     * Invoked when an error occurs reading data. This listener will be invoked if there is a problem with the underlying
-     * connection while data is being read from the stream. We consider data to be being read when the following conditions
-     * are met:
-     *
+     * Invoked when an error occurs reading data after {@link #setReadListener(ReadListener)} has been called. This method
+     * will be invoked if there is a problem while data is being read from the stream and either:
      * <ul>
-     * <li>{@link ServletInputStream#isReady()} has been invoked and returned false</li>
-     * <li>{@link ServletInputStream#close()} has not been called</li>
-     * <li>{@link ServletInputStream#read()} (or any other read method) has not returned {@code -1}</li>
+     * <li>{@link ServletInputStream#isReady()} has been invoked and returned false;</li>
+     * <li>or {@link ServletInputStream#close()} has been called, and the failure occurred before the response could be
+     * completed</li>
      * </ul>
-     *
-     * If these conditions are not met and the stream is still open then any failure notification will not be delivered
-     * until {@link ServletInputStream#isReady()} is invoked. {@code isReady} must return false in this situation, and then
-     * the failure will be delivered to this method.
+     * If these conditions are not met and the stream is still open then any failure notification will be delivered either:
+     * by an exception thrown from a {@code IO} operation after an invocation of {@link ServletInputStream#isReady()} has
+     * returned {@code true}; or by a call to this method after an invocation of {@link ServletInputStream#isReady()} has
+     * returned {@code false};
+     * <p>
+     * This method will not be invoked in any circumstances after {@link AsyncListener#onComplete(AsyncEvent)} has been
+     * called.
      *
      * @param t the throwable to indicate why the read operation failed
      */

api/src/main/java/jakarta/servlet/ServletInputStream.java

@@ -178,11 +178,12 @@ public int readLine(byte[] b, int off, int len) throws IOException {
      * If an attempt is made to read from the stream when the stream is in async mode and this method has not returned
      * {@code true} the method will throw an {@link IllegalStateException}.
      * <p>
-     * If an error occurs and {@link ReadListener#onError(Throwable)} is invoked then this method will always return false,
-     * as no further IO operations are allowed after {@code onError} notification.
+     * If an error occurs then either: this method will return {@code true} and an {@link IOException} will be thrown from a
+     * subsequent call to {@code read(...)}; or this method will return {@code false} and subsequently
+     * {@link ReadListener#onError(Throwable)} will be invoked with the error. Once the error has either been thrown or
+     * passed to {@link ReadListener#onError(Throwable)}, then this method will always return {@code true} and all further
+     * {@code read} operations will throw an {@link IOException}.
      * <p>
-     * Note that due to the requirement for {@code read} to never throw in async mode, this method must return false if a
-     * call to {@code read} would result in an exception.
      *
      * @return {@code true} if data can be obtained without blocking, otherwise returns {@code false}.
      * @see ReadListener
@@ -194,11 +195,10 @@ public int readLine(byte[] b, int off, int len) throws IOException {
      * Instructs the <code>ServletInputStream</code> to invoke the provided {@link ReadListener} when it is possible to
      * read.
      * <p>
-     * Note that after this method has been called methods on this stream that are documented to throw {@link IOException}
-     * will no longer throw these exceptions directly, instead any exception that occurs will be reported via
-     * {@link ReadListener#onError(Throwable)}. Please refer to this method for more information. This only applies to
-     * {@code IOException}, other exception types may still be thrown (e.g. methods can throw {@link IllegalStateException}
-     * if {@link #isReady()} has not returned true).
+     * Note that after this method has been called, methods on this stream that are documented to throw {@link IOException}
+     * might not throw these exceptions directly, instead they may be reported via {@link ReadListener#onError(Throwable)}
+     * after a call to {@link #isReady()} has returned {@code false}. Please refer to {@link #isReady()} method for more
+     * information.
      *
      * @param readListener the {@link ReadListener} that should be notified when it's possible to read.
      *

api/src/main/java/jakarta/servlet/ServletOutputStream.java

@@ -340,11 +340,11 @@ public void println(double d) throws IOException {
      * If an attempt is made to write to the stream when the stream is in async mode and this method has not returned
      * {@code true} the method will throw an {@link IllegalStateException}.
      * <p>
-     * If an error occurs and {@link WriteListener#onError(Throwable)} is invoked then this method will always return false,
-     * as no further IO operations are allowed after {@code onError} notification.
-     * <p>
-     * Note that due to the requirement for {@code write} to never throw in async mode, this method must return false if a
-     * call to {@code write} would result in an exception.
+     * If an error occurs then either: this method will return {@code true} and an {@link IOException} will be thrown from a
+     * subsequent call to {@code write(...)}; or this method will return {@code false} and subsequently
+     * {@link WriteListener#onError(Throwable)} will be invoked with the error. Once the error has either been thrown or
+     * passed to {@link WriteListener#onError(Throwable)}, then this method will always return {@code true} and all further
+     * {@code write} operations will throw an {@link IOException}.
      *
      * @return {@code true} if data can be written without blocking, otherwise returns {@code false}.
      * @see WriteListener
@@ -356,15 +356,15 @@ public void println(double d) throws IOException {
      * Instructs the <code>ServletOutputStream</code> to invoke the provided {@link WriteListener} when it is possible to
      * write.
      * <p>
-     * Note that after this method has been called methods on this stream that are documented to throw {@link IOException}
-     * will no longer throw these exceptions directly, instead any exception that occurs will be reported via
-     * {@link WriteListener#onError(Throwable)}. Please refer to this method for more information. This only applies to
-     * {@code IOException}, other exception types may still be thrown (e.g. methods can throw {@link IllegalStateException}
-     * if {@link #isReady()} has not returned true).
+     * Note that after this method has been called, methods on this stream that are documented to throw {@link IOException}
+     * might not throw these exceptions directly, instead they may be reported via {@link ReadListener#onError(Throwable)}
+     * after a call to {@link #isReady()} has returned {@code false}. Please refer to {@link #isReady()} method for more
+     * information.
      * <p>
-     * Once this method has been called {@link #flush()} and {@link #close()} become asynchronous operations, they will be
-     * performed in the background and any problems will be reported through the {@link WriteListener#onError(Throwable)}
-     * method.
+     * Once this method has been called {@link #flush()} and {@link #close()} become asynchronous operations, possibly
+     * performed in the background. Thus any problems may be reported through the {@link WriteListener#onError(Throwable)}
+     * method, which may be called at any time after a {@link #close()} or otherwise only after a call to {@link #isReady()}
+     * has returned {@code false}.
      *
      * @param writeListener the {@link WriteListener} that should be notified when it's possible to write
      *

api/src/main/java/jakarta/servlet/WriteListener.java

@@ -40,19 +40,21 @@ public interface WriteListener extends EventListener {
     void onWritePossible() throws IOException;
 
     /**
-     * Invoked when an error occurs writing data using the non-blocking APIs. This listener will be invoked if there is a
-     * problem with the underlying connection while data is being written to the stream. We consider data to be being
-     * written when any of the following conditions are met:
-     *
+     * Invoked when an error occurs writing data after {@link ServletOutputStream#setWriteListener(WriteListener)} has been
+     * called. This method will be invoked if there is a problem while data is being written to the stream and either:
      * <ul>
      * <li>{@link ServletOutputStream#isReady()} has been invoked and returned false</li>
      * <li>{@link ServletOutputStream#close()} has been called, and the failure occurred before the response could be fully
      * written to the client</li>
      * </ul>
      *
-     * If these conditions are not met and the stream is still open then any failure notification will not be delivered
-     * until {@link ServletOutputStream#isReady()} is invoked. {@code isReady} must return false in this situation, and then
-     * the failure will be delivered to the {@link #onError(Throwable)} method.
+     * If these conditions are not met and the stream is still open then any failure notification will be delivered either:
+     * by an exception thrown from a {@code IO} operation after an invocation of {@link ServletOutputStream#isReady()} has
+     * returned {@code true}; or by a call to this method after an invocation of {@link ServletOutputStream#isReady()} has
+     * returned {@code false};
+     * <p>
+     * This method will not be invoked in any circumstances after {@link AsyncListener#onComplete(AsyncEvent)} has been
+     * called.
      *
      * @param t the throwable to indicate why the write operation failed
      */