RFR 8213912: Semantic typo in HttpExchange.java

[Daniel Fuchs]

Hi Chris,

Thanks for fixing this, it is an important distinction!
(and I like John's description of the issue :-))

I am wondering though - whether there's a relationship with
this bug, and JDK-8180754 [1].

best regards,

-- daniel

[1] https://bugs.openjdk.java.net/browse/JDK-8180754

On 14/03/2019 09:43, Chris Hegarty wrote:
> In the class-level description for com.sun.net.httpserver.HttpExchange
> there is a typo related to the request body input stream, that may cause
> confusion. It should be fixed.
> 
> The typical life-cycle of an exchange, as described, should advise the
> reader that the request body input stream *SHOULD* be closed explicitly.
> There is some additional auto-magic that may close the stream when
> the exchange or its response body output stream is closed, but the
> advise to the reader should be to close the stream explicitly ( as any
> other action is more error-prone and adds additional cognitive load on
> the reader ).
> 
> 
> diff --git a/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpExchange.java b/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpExchange.java
> --- a/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpExchange.java
> +++ b/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpExchange.java
> @@ -41,11 +41,11 @@
>    * The typical life-cycle of a HttpExchange is shown in the sequence
>    * below.
>    * <ol><li>{@link #getRequestMethod()} to determine the command
>    * <li>{@link #getRequestHeaders()} to examine the request headers (if needed)
>    * <li>{@link #getRequestBody()} returns a {@link java.io.InputStream} for reading the request body.
> - *     After reading the request body, the stream is close.
> + *     After reading the request body, the stream should be closed.
>    * <li>{@link #getResponseHeaders()} to set any response headers, except content-length
>    * <li>{@link #sendResponseHeaders(int,long)} to send the response headers. Must be called before
>    * next step.
>    * <li>{@link #getResponseBody()} to get a {@link java.io.OutputStream} to send the response body.
>    *      When the response body has been written, the stream must be closed to terminate the exchange.
> 
> Bug:
>    https://bugs.openjdk.java.net/browse/JDK-8213912
>    
> -Chris.
>