Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8255778

Add `@throws IOException` in javadoc for `HttpEchange.sendResponseHeaders`

    XMLWordPrintable

Details

    • CSR
    • Resolution: Approved
    • P4
    • 16
    • core-libs
    • None
    • behavioral
    • minimal
    • Documentation updated to inform user of the pre-existing behavior of method within class.
    • Java API
    • JDK

    Description

      Summary

      The @throws IOException tag is missing from the specification for the method HttpEchange.sendResponseHeaders. The tag needs to be added to inform the user of the conditions when the exception may be thrown.

      Problem

      The method HttpEchange.sendResponseHeaders throws an IOException but this facet of the method is not mentioned in its javadoc.

      Solution

      Add an @throws IOException to the method's specification and a description of the conditions under which the exception is thrown.

      Specification

        /**
         * 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
         * 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.
         *
         * <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()}.
         *
         * @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,
         *                       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.
      +  * @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;

      Attachments

        Issue Links

          Activity

            People

              pconcannon Patrick Concannon (Inactive)
              pconcannon Patrick Concannon (Inactive)
              Daniel Fuchs, Roger Riggs
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: