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

com.sun.net.httpserver.HttpExchange: Improve API doc of getRequestHeaders

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 18
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      API doc only change, minor clarification
    • Interface Kind:
      Java API
    • Scope:
      JDK

      Description

      Summary

      Clarify the behaviour of com.sun.net.httpserver.HttpExchange::getRequestHeaders, specifically how header values are represented in the Headers returned.

      Problem

      The description of how header values are represented in the Headers returned is abstruse, in particular in the case of header fields that appear multiple times.

      Solution

      Improve the description in the method-level API doc. Additionally, use the correct type com.sun.net.httpserver.Headers, which implements java.util.Map.

      Specification

      com/sun/net/httpserver/HttpExchange.java

            /**
       -     * Returns an immutable {@link Map} containing the HTTP headers that were
       -     * included with this request. The keys in this {@code Map} will be the header
       -     * names, while the values will be a {@link java.util.List} of
       +     * Returns an immutable {@link Headers} containing the HTTP headers that
       +     * were included with this request.
       +     *
       +     * <p> The keys in this {@code Headers} are the header names, while the
       +     * values are a {@link java.util.List} of
             * {@linkplain java.lang.String Strings} containing each value that was
       -     * included (either for a header that was listed several times, or one that
       -     * accepts a comma-delimited list of values on a single line). In either of
       -     * these cases, the values for the header name will be presented in the
       -     * order that they were included in the request.
       +     * included in the request, in the order they were included. Header fields
       +     * appearing multiple times are represented as multiple string values.
             *
       -     * <p> The keys in {@code Map} are case-insensitive.
       +     * <p> The keys in {@code Headers} are case-insensitive.
             *
       -     * @return a read-only {@code Map} which can be used to access request headers
       +     * @return a read-only {@code Headers} which can be used to access request
       +     *         headers.
             */
            public abstract Headers getRequestHeaders();

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              jboes Julia Boes
              Reporter:
              jboes Julia Boes
              Reviewed By:
              Chris Hegarty, Daniel Fuchs
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: