Summary

A spec clarification is required for java.net.URLConnection so that the specification of getHeaderFieldKey() and getHeaderField() is made compatible with how the methods are implemented (and specified) in the HttpURLConnection sub-class.

Problem

URLConnection.getHeaderField(n) is specified to return null if there are fewer than n+1 headers and this fact can be used to iterate over the headers. However, getHeaderField(0) returns null for HttpURLConnection making that assumption invalid.

Solution

The spec for URLConnection.getHeaderFieldKey needs to include similar wording as in HttpURLConnection.getHeaderFieldKey to account for the fact that header field key zero can be null.

Specification

diff -r dd65d923d6fd src/java.base/share/classes/java/net/URLConnection.java
--- a/src/java.base/share/classes/java/net/URLConnection.java   Thu May 21 09:56:19 2020 +0530
+++ b/src/java.base/share/classes/java/net/URLConnection.java   Thu May 21 18:59:34 2020 +0100
@@ -667,12 +667,15 @@

     /**
      * Returns the key for the {@code n}<sup>th</sup> header field.
-     * It returns {@code null} if there are fewer than {@code n+1} fields.
+     * Some implementations may treat the {@code 0}<sup>th</sup>
+     * header field as special, in which case, {@link #getHeaderField(int) getHeaderField(0)}
+     * may return some value, but {@code getHeaderFieldKey(0)} returns {@code null}.
+     * For {@code n > 0 } it returns {@code null} if there are fewer than {@code n+1} fields.
      *
      * @param   n   an index, where {@code n>=0}
      * @return  the key for the {@code n}<sup>th</sup> header field,
      *          or {@code null} if there are fewer than {@code n+1}
-     *          fields.
+     *          fields when {@code n > 0}.
      */
     public String getHeaderFieldKey(int n) {
         return null;