RFR: 8368955: Improve HttpExchange.sendResponseHeaders usability [v2]

[Jaikiran Pai]

On Fri, 3 Oct 2025 05:00:50 GMT, Josiah Noel <duke at openjdk.org> wrote:

>> As specified in [JDK-8368955](https://bugs.openjdk.org/browse/JDK-8368955?jql=project%20in%20(JDK)%20AND%20component%20in%20(core-libs)%20AND%20Subcomponent%20in%20(java.net)), adds some constants to HttpExchange to make `sendResponseHeaders` more usable.
>
> Josiah Noel has updated the pull request incrementally with one additional commit since the last revision:
> 
>   pr comments

src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpExchange.java line 180:

> 178:      * Starts sending the final response back to the client using the current set of
> 179:      * response headers obtained from {@link #getResponseHeaders()} and the numeric
> 180:      * response code as specified in this

I think specifying "response headers obtained from {@link #getResponseHeaders()}" will imply that the implementation of `sendResponseHeaders(int rCode, long responseLength)` is now going to always call `getResponseHeaders()`. That would be a new expectation of this method.

I went through the entire text of this method javadoc and I even spotted a pre-existing typo in the param doc of `@param responseLength` (the getResponseCode() reference in that text should be getResponseBody()).

Would rewording this entire API doc to something like this be better:


/**
 * Starts sending the final response back to the client using the current set of
 * response headers and the numeric response code {@code rCode}.
 * <p>
 * If the given {@code responseLength} is greater than {@code zero}, this
 * specifies an exact number of bytes to send and the application must send
 * that exact amount of data. If {@code responseLength} is
 * {@link #RSPBODY_CHUNKED} then the response body uses
 * chunked transfer encoding and an arbitrary amount of data may be
 * sent. If {@code responseLength} is {@link #RSPBODY_EMPTY} then no
 * response body should be sent.
 * <p>
 * The application terminates the response body by closing the
 * {@link OutputStream}.
 * <p>
 * If the {@code content-length} response header has not already been set then
 * this is set to the appropriate value depending on the {@code responseLength}.
 * <p>
 * This method must be called prior to calling {@link #getResponseBody()}.
 *
 * @implNote This implementation allows the caller to instruct the
 * server to force a connection close after the exchange terminates, by
 * supplying a {@code Connection: close} header through {@linkplain
 * #getResponseHeaders() response headers} before {@code sendResponseHeaders}
 * is called.
 *
 * @param rCode          the response code to send
 * @param responseLength if {@literal > 0}, specifies a fixed response body
 *                       length and that exact number of bytes must be written
 *                       to the stream acquired from {@link #getResponseBody()}
 *                       If equal to {@link #RSPBODY_CHUNKED}, then chunked encoding is used,
 *                       and an arbitrary number of bytes may be written.
 *                       If equal to {@link #RSPBODY_EMPTY}, then the response will not
 *                       have a body and no response body may be written.
 * @throws IOException   if the response headers have already been sent or an I/O error occurs
 * @see   HttpExchange#getResponseBody()
 */

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/27613#discussion_r2400810787