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();