Summary

Add symbolic constants for response length values in HttpExchange.sendResponseHeaders

Problem

The responseLength parameter to sendResponseHeaders can take a positive value to specify a fixed response content length. It takes the value zero to mean indefinite length/chunked encoding and the value <= -1 to mean no response body. The latter two values are counter-intuitive and probably should have been defined the other way round. That cannot be changed but a small doc update can make it less error prone

Solution

Define two new numeric constants denoting an empty body and chunked encoding. Then the textual apidoc description can reference these values without mentioning their counter-intuitive values.

Specification

Two new constants added to HttpExchange:

    /**
     * No response body is being sent with this response
     *
     * @see #sendResponseHeaders(int, long)
     * @since 26
     */
    public static final long RSPBODY_EMPTY = -1l;

    /**
     * The response body length is unspecified and will be chunk encoded
     *
     * @see #sendResponseHeaders(int, long)
     * @since 26
     */
    public static final long RSPBODY_CHUNKED = 0;

The apidoc for sendResponseHeaders updated as follows:

     /**
      * Starts sending the response back to the client using the current set of
      * response headers and the numeric response code as specified in this
      * method. The response body length is also specified as follows. If the
      * response length parameter 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 the response length parameter is {@code zero}, then
-     * chunked transfer encoding is used and an arbitrary amount of data may be
+     * amount of data. If the response length parameter has the value
+     * {@link #RSPBODY_CHUNKED} (zero) then the response body uses
+     * chunked transfer encoding and an arbitrary amount of data may be
      * sent. The application terminates the response body by closing the
      * {@link OutputStream}.
-     * If response length has the value {@code -1} then no response body is
-     * being sent.
+     * If response length has the value {@link #RSPBODY_EMPTY} then no
+     * response body is being sent.
      *
      * <p> If the content-length response header has not already been set then
      * this is set to the appropriate value depending on the response length
      * parameter.
      *
      * <p> This method must be called prior to calling {@link #getResponseBody()}.
      *
+     * @apiNote If a response body is to be sent from a byte array and the
+     * length of the array is used as the responseLength parameter, then note
+     * the behavior in the case when the array is empty. In that case, the
+     * responseLength will be zero which is the value of {@link #RSPBODY_CHUNKED}
+     * resulting in a zero length, but chunked encoded response body. While this
+     * is not incorrect, it may be preferable to check for an empty array and set
+     * responseLength to {@link #RSPBODY_EMPTY} instead. Also, when sending a
+     * chunked encoded response body, whatever length, the output stream must
+     * be explicitly closed by the handler.
+     *
      * @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 to the {@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 #getResponseCode()}
-     *                       If {@literal == 0}, then chunked encoding is used,
+     *                       If equal to {@link #RSPBODY_CHUNKED}, then chunked encoding is used,
      *                       and an arbitrary number of bytes may be written.
-     *                       If {@literal <= -1}, then no response body length is
-     *                       specified and no response body may be written.
+     *                       If equal to {@link #RSPBODY_EMPTY}, then no response body length is
+     *                       specified and no response body may be written. Any value {@literal <= -1}
+     *                       is treated the same as {@link #RSPBODY_EMPTY}.
      * @throws IOException   if the response headers have already been sent or an I/O error occurs
      * @see   HttpExchange#getResponseBody()
      */
     public abstract void sendResponseHeaders(int rCode, long responseLength) throws IOException;