diff --git a/jaxrs-api/src/main/java/jakarta/ws/rs/core/Response.java b/jaxrs-api/src/main/java/jakarta/ws/rs/core/Response.java index 82e85d704..544a48e40 100644 --- a/jaxrs-api/src/main/java/jakarta/ws/rs/core/Response.java +++ b/jaxrs-api/src/main/java/jakarta/ws/rs/core/Response.java @@ -74,16 +74,20 @@ protected Response() { public abstract StatusType getStatusInfo(); /** - * Get the message entity Java instance. Returns {@code null} if the message does not contain an entity body. - *
- * If the entity is represented by an un-consumed {@link InputStream input stream} the method will return the input - * stream. - *
+ * Get the message entity Java instance. Returns {@code null} if the message does not contain an entity body, otherwise + * behaves as follow: + *inputStream.read() != -1
),
+ * then that input stream is returned.
+ * inputStream.read() == -1
), or if the response has been {@link #close() closed}.
*/
public abstract Object getEntity();
@@ -93,26 +97,25 @@ protected Response() {
*
* Method throws an {@link ProcessingException} if the content of the message cannot be mapped to an entity of the
* requested type and {@link IllegalStateException} in case the entity is not backed by an input stream or if the
- * original entity input stream has already been consumed without {@link #bufferEntity() buffering} the entity data
- * prior consuming.
+ * original entity input stream has already been fully consumed (i.e inputStream.read() == -1
) without
+ * being {@link #bufferEntity() buffered} prior consuming.
*
- * A message instance returned from this method will be cached for subsequent retrievals via {@link #getEntity()}. * Unless the supplied entity type is an {@link java.io.InputStream input stream}, this method automatically - * {@link #close() closes} the an unconsumed original response entity data stream if open. In case the entity data has + * {@link InputStream#close() closes} the original message entity input stream if open. In case the entity data has * been buffered, the buffer will be reset prior consuming the buffered data to enable subsequent invocations of * {@code readEntity(...)} methods on this response. *
* * @paraminputStream.read() == -1
)
+ * and has not been buffered prior consuming.
* @see jakarta.ws.rs.ext.MessageBodyReader
* @since 2.0
*/
@@ -124,26 +127,25 @@ protected Response() {
*
* Method throws an {@link ProcessingException} if the content of the message cannot be mapped to an entity of the
* requested type and {@link IllegalStateException} in case the entity is not backed by an input stream or if the
- * original entity input stream has already been consumed without {@link #bufferEntity() buffering} the entity data
- * prior consuming.
+ * original entity input stream has already been fully consumed (i.e inputStream.read() == -1
) without
+ * being {@link #bufferEntity() buffered} prior consuming.
*
- * A message instance returned from this method will be cached for subsequent retrievals via {@link #getEntity()}. * Unless the supplied entity type is an {@link java.io.InputStream input stream}, this method automatically - * {@link #close() closes} the an unconsumed original response entity data stream if open. In case the entity data has + * {@link InputStream#close() closes} the original message entity input stream if open. In case the entity data has * been buffered, the buffer will be reset prior consuming the buffered data to enable subsequent invocations of * {@code readEntity(...)} methods on this response. *
* * @paraminputStream.read() == -1
)
+ * and has not been buffered prior consuming.
* @see jakarta.ws.rs.ext.MessageBodyReader
* @since 2.0
*/
@@ -155,13 +157,12 @@ protected Response() {
*
* Method throws an {@link ProcessingException} if the content of the message cannot be mapped to an entity of the
* requested type and {@link IllegalStateException} in case the entity is not backed by an input stream or if the
- * original entity input stream has already been consumed without {@link #bufferEntity() buffering} the entity data
- * prior consuming.
+ * original entity input stream has already been fully consumed (i.e inputStream.read() == -1
) without
+ * being {@link #bufferEntity() buffered} prior consuming.
*
- * A message instance returned from this method will be cached for subsequent retrievals via {@link #getEntity()}. * Unless the supplied entity type is an {@link java.io.InputStream input stream}, this method automatically - * {@link #close() closes} the an unconsumed original response entity data stream if open. In case the entity data has + * {@link InputStream#close() closes} the original message entity input stream if open. In case the entity data has * been buffered, the buffer will be reset prior consuming the buffered data to enable subsequent invocations of * {@code readEntity(...)} methods on this response. *
@@ -169,13 +170,13 @@ protected Response() { * @paraminputStream.read() == -1
)
+ * and has not been buffered prior consuming.
* @see jakarta.ws.rs.ext.MessageBodyReader
* @since 2.0
*/
@@ -187,13 +188,12 @@ protected Response() {
*
* Method throws an {@link ProcessingException} if the content of the message cannot be mapped to an entity of the
* requested type and {@link IllegalStateException} in case the entity is not backed by an input stream or if the
- * original entity input stream has already been consumed without {@link #bufferEntity() buffering} the entity data
- * prior consuming.
+ * original entity input stream has already been fully consumed (i.e inputStream.read() == -1
) without
+ * being {@link #bufferEntity() buffered} prior consuming.
*
- * A message instance returned from this method will be cached for subsequent retrievals via {@link #getEntity()}. * Unless the supplied entity type is an {@link java.io.InputStream input stream}, this method automatically - * {@link #close() closes} the an unconsumed original response entity data stream if open. In case the entity data has + * {@link InputStream#close() closes} the original message entity input stream if open. In case the entity data has * been buffered, the buffer will be reset prior consuming the buffered data to enable subsequent invocations of * {@code readEntity(...)} methods on this response. *
@@ -201,13 +201,13 @@ protected Response() { * @paraminputStream.read() == -1
)
+ * and has not been buffered prior consuming.
* @see jakarta.ws.rs.ext.MessageBodyReader
* @since 2.0
*/
@@ -232,19 +232,18 @@ protected Response() {
public abstract boolean hasEntity();
/**
- * Buffer the message entity data.
+ * Buffer the message entity input stream.
*
- * In case the message entity is backed by an unconsumed entity input stream, all the bytes of the original entity input
- * stream are read and stored in a local buffer. The original entity input stream is consumed and automatically closed
- * as part of the operation and the method returns {@code true}.
+ * In case the message entity is backed by an input stream not consumed at all, all the bytes of that input
+ * stream are read (i.e until inputStream.read() == -1
) and stored in a local buffer. That input
+ * stream is then automatically {@link InputStream#close() closed} as part of the operation and the method returns {@code true}.
*
- * In case the response entity instance is not backed by an unconsumed input stream an invocation of - * {@code bufferEntity} method is ignored and the method returns {@code false}. + * Otherwise an invocation of {@code bufferEntity} method is ignored and the method returns {@code false}. *
** This operation is idempotent, i.e. it can be invoked multiple times with the same effect which also means that - * calling the {@code bufferEntity()} method on an already buffered (and thus closed) message instance is legal and has + * calling the {@code bufferEntity()} method on an already buffered (and thus closed) input stream instance is legal and has * no further effect. Also, the result returned by the {@code bufferEntity()} method is consistent across all * invocations of the method on the same {@code Response} instance. *
@@ -268,13 +267,13 @@ protected Response() { * associated with the response (e.g. {@link #bufferEntity() buffered message entity data}). ** This operation is idempotent, i.e. it can be invoked multiple times with the same effect which also means that - * calling the {@code close()} method on an already closed message instance is legal and has no further effect. + * calling the {@code close()} method on an already closed message entity input stream is legal and has no further effect. *
*- * The {@code close()} method should be invoked on all instances that contain an un-consumed entity input stream to - * ensure the resources associated with the instance are properly cleaned-up and prevent potential memory leaks. This is - * typical for client-side scenarios where application layer code processes only the response headers and ignores the - * response entity. + * The {@code close()} method should be invoked on all instances that contain an original entity input stream not fully + * consumed (i.e until inputStream.read() != -1) to ensure the resources associated with the instance are properly cleaned-up + * and prevent potential memory leaks. This is typical for client-side scenarios where application layer code processes only + * the response headers and ignores the response entity. *
*
* Any attempts to manipulate (read, get, buffer) a message entity on a closed response will result in an
@@ -471,9 +470,9 @@ public MultivaluedMap
- * Note that if the entity is backed by an un-consumed input stream, the reference to the stream is copied. In such case - * make sure to {@link #bufferEntity() buffer} the entity stream of the original response instance before passing it to - * this method. + * Note that if the entity is backed by the original input stream not consumed at all, the reference to the stream is copied. + * In such case make sure to {@link #bufferEntity() buffer} the entity stream of the original response instance before passing + * it to this method. *
* * @param response a Response from which the status code, entity and {@link #getHeaders() response headers} will be