Clarify under what circumstances onError is called

Fixes jakartaee#433

Signed-off-by: Stuart Douglas <[email protected]>

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

@@ -48,7 +48,19 @@ public interface ReadListener extends EventListener {
     public void onAllDataRead() throws IOException;
 
     /**
-     * Invoked when an error occurs processing the request.
+     * 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:
+     *
+     * <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>
+     * </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.
      *
      * @param t the throwable to indicate why the read operation failed
      */

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

@@ -101,14 +101,30 @@ public int readLine(byte[] b, int off, int len) throws IOException {
     /**
      * Returns true if data can be read without blocking else returns false.
      *
+     * 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.
+     * <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</code> if data can be obtained without blocking, otherwise returns <code>false</code>.
      *
      * @since Servlet 3.1
      */
     public abstract boolean isReady();
 
     /**
-     * Instructs the <code>ServletInputStream</code> to invoke the provided {@link ReadListener} when it is possible to read
+     * 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).
      *
      * @param readListener the {@link ReadListener} that should be notified when it's possible to read.
      *

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

@@ -273,6 +273,15 @@ public void println(double d) throws IOException {
 
     /**
      * This method can be used to determine if data can be written without blocking.
+     * <p>
+     * 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.
      *
      * @return <code>true</code> if a write to this <code>ServletOutputStream</code> will succeed, otherwise returns
      * <code>false</code>.
@@ -283,8 +292,17 @@ public void println(double d) throws IOException {
 
     /**
      * Instructs the <code>ServletOutputStream</code> to invoke the provided {@link WriteListener} when it is possible to
-     * write
-     *
+     * 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).
+     * <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.
      *
      * @param writeListener the {@link WriteListener} that should be notified when it's possible to write
      *

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

@@ -39,7 +39,19 @@ public interface WriteListener extends EventListener {
     public void onWritePossible() throws IOException;
 
     /**
-     * Invoked when an error occurs writing data using the non-blocking APIs.
+     * 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:
+     *
+     * <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.
      *
      * @param t the throwable to indicate why the write operation failed
      */

spec/src/main/asciidoc/servlet-spec-body.adoc

@@ -8546,6 +8546,9 @@ Jakarta Servlet {spec-version} specification developed under the Jakarta EE Work
 
 === Changes Since Jakarta Servlet 5.0
 
+link:https://github.com/eclipse-ee4j/servlet-api/issues/433[Issue 433]::
+Clarify how IO errors are handled by async streams.
+
 link:https://github.com/eclipse-ee4j/servlet-api/issues/18[Issue 18]::
 Clarify the decoding and normalization of URI paths.