Experiment providing random access to fields.

Fix #11811 with javadoc and an optional random access implementation.

jetty-core/jetty-http/src/main/java/org/eclipse/jetty/http/HttpFields.java

@@ -43,9 +43,11 @@
  * and client-side HTTP responses, while {@link HttpFields.Mutable} is mutable and
  * typically used in server-side HTTP responses and client-side HTTP requests.</p>
  *
+ * <p>Access is always more efficient using {@link HttpHeader} keys rather than {@link String} field names.</p>
+ * 
  * <p>The primary implementations of {@code HttpFields} have been optimized assuming few
  * lookup operations, thus typically if many {@link HttpField}s need to looked up, it may be
- * better to use an {@link Iterator} or the {@link #asRandomAccess()} method.</p>
+ * better to use an {@link Iterator} or the {@link #asMappedAccess()} method.</p>
  */
 public interface HttpFields extends Iterable<HttpField>, Supplier<HttpFields>
 {
@@ -202,15 +204,14 @@ default HttpFields asImmutable()
     }
 
     /**
-     * <p>Returns an immutable version of this {@link HttpFields} instance, possibly optimized for random access.</p>
-     * <p>Mutable {@code HttpFields} cannot be optimized for random access, so {@link #asImmutable()} should be called
-     * first if a random access version of mutable Fields are required.</p>
+     * <p>Returns an immutable version of this {@link HttpFields} instance, possibly optimized for random field
+     * access via {@link Map} implementations.</p>
      *
-     * @return an {@link HttpFields} instance, which may be optimized for RandomAccess
+     * @return an {@link HttpFields} instance, which may be optimized for random access.
      */
-    default HttpFields asRandomAccess()
+    default HttpFields asMappedAccess()
     {
-        return this;
+        return asImmutable();
     }
 
     /**
@@ -367,10 +368,12 @@ default boolean contains(EnumSet<HttpHeader> headers)
     /**
      * <p>Returns whether this instance contains the given field name.</p>
      * <p>The comparison of field name is case-insensitive via
-     * {@link HttpField#is(String)}.
+     * {@link HttpField#is(String)}. If possible, it is more efficient to use
+     * {@link #contains(HttpHeader)}.
      *
      * @param name the case-insensitive field name to search for
      * @return whether this instance contains the given field name
+     * @see #contains(HttpHeader) 
      */
     default boolean contains(String name)
     {
@@ -429,14 +432,15 @@ default String getLast(HttpHeader header)
      * <p>Returns the encoded value of the first field with the given field name,
      * or {@code null} if no such field is present.</p>
      * <p>The comparison of field name is case-insensitive via
-     * {@link HttpField#is(String)}.</p>
+     * {@link HttpField#is(String)}. If possible, it is more efficient to use {@link #get(HttpHeader)}.</p>
      * <p>In case of multi-valued fields, the returned value is the encoded
      * value, including commas and quotes, as returned by {@link HttpField#getValue()}.</p>
      *
      * @param name the case-insensitive field name to search for
      * @return the raw value of the first field with the given field name,
      * or {@code null} if no such field is present
      * @see HttpField#getValue()
+     * @see #get(HttpHeader) 
      */
     default String get(String name)
     {

jetty-core/jetty-http/src/main/java/org/eclipse/jetty/http/ImmutableHttpFields.java

@@ -35,7 +35,6 @@ class ImmutableHttpFields implements HttpFields
 {
     final HttpField[] _fields;
     final int _size;
-    RandomAccess _randomAccess;
 
     /**
      * Initialize HttpFields from copy.
@@ -60,11 +59,9 @@ public HttpFields asImmutable()
     }
 
     @Override
-    public HttpFields asRandomAccess()
+    public HttpFields asMappedAccess()
     {
-        if (_randomAccess == null)
-            _randomAccess = new RandomAccess(this);
-        return _randomAccess;
+        return new RandomAccess(this);
     }
 
     @Override
@@ -242,17 +239,18 @@ public void set(HttpField field)
     }
 
     /**
-     * An immutable {@link HttpFields} instance, optimized for random field access.
+     * An immutable {@link HttpFields} instance, optimized for random access to
+     * single valued fields
      */
-    public static class RandomAccess implements HttpFields
+    private static class RandomAccess implements HttpFields
     {
         private final HttpFields _httpFields;
         private final EnumMap<HttpHeader, HttpField> _enumMap = new EnumMap<>(HttpHeader.class);
         private final Map<String, HttpField> _stringMap;
 
         RandomAccess(HttpFields httpFields)
         {
-            _httpFields = Objects.requireNonNull(httpFields.asImmutable());
+            _httpFields = Objects.requireNonNull(httpFields);
             Map<String, HttpField> stringMap = null;
             for (HttpField field : httpFields)
             {

jetty-core/jetty-http/src/test/java/org/eclipse/jetty/http/HttpFieldsTest.java

@@ -1496,7 +1496,7 @@ public HttpField onReplaceField(HttpField oldField, HttpField newField)
     public void testRandomAccess()
     {
         HttpFields.Mutable mutable = HttpFields.build();
-        assertThat(mutable.asRandomAccess(), sameInstance(mutable));
+        assertThat(mutable.asMappedAccess(), sameInstance(mutable));
 
         mutable.add("expect", "100")
             .add("RaNdOm", "value")
@@ -1506,7 +1506,7 @@ public void testRandomAccess()
             .add("Foo-Bar", "two")
             .asImmutable();
 
-        HttpFields header = mutable.asImmutable().asRandomAccess();
+        HttpFields header = mutable.asImmutable().asMappedAccess();
         assertThat(header, not(sameInstance(mutable)));
 
         assertThat(header.get("expect"), is("100"));