+ * 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. + *
+ * 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
* @since Servlet 3.1
@@ -182,7 +191,14 @@ public int readLine(byte[] b, int off, int len) throws IOException {
public abstract boolean isReady();
/**
- * Instructs the ServletInputStream to invoke the provided {@link ReadListener} when it is possible to read
+ * Instructs the ServletInputStream to invoke the provided {@link ReadListener} when it is possible to
+ * read.
+ *
+ * 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. * diff --git a/api/src/main/java/jakarta/servlet/ServletOutputStream.java b/api/src/main/java/jakarta/servlet/ServletOutputStream.java index cec5f001a..96c70aed3 100644 --- a/api/src/main/java/jakarta/servlet/ServletOutputStream.java +++ b/api/src/main/java/jakarta/servlet/ServletOutputStream.java @@ -336,6 +336,15 @@ public void println(double d) throws IOException { * {@link WriteListener#onWritePossible()} once a write operation becomes possible without blocking. Other than the * initial call, {@link WriteListener#onWritePossible()} will only be called if and only if this method is called and * returns false. + *
+ * 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}. + *
+ * 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. + *
+ * 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} if data can be written without blocking, otherwise returns {@code false}.
* @see WriteListener
@@ -345,8 +354,17 @@ public void println(double d) throws IOException {
/**
* Instructs the ServletOutputStream to invoke the provided {@link WriteListener} when it is possible to
- * write
- *
+ * write.
+ *
+ * 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). + *
+ * 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 * diff --git a/api/src/main/java/jakarta/servlet/WriteListener.java b/api/src/main/java/jakarta/servlet/WriteListener.java index 1b2cd33a8..91d768a2e 100644 --- a/api/src/main/java/jakarta/servlet/WriteListener.java +++ b/api/src/main/java/jakarta/servlet/WriteListener.java @@ -40,7 +40,19 @@ public interface WriteListener extends EventListener { 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: + * + *