Package org.eclipse.jetty.http

Interface HttpFields

All Superinterfaces:
Iterable<HttpField>, Supplier<HttpFields>
All Known Subinterfaces:
HttpFields.Mutable
All Known Implementing Classes:
HttpFields.ImmutableHttpFields, HttpFields.Mutable.Wrapper, HttpFields.MutableHttpFields, HttpTester.Message, HttpTester.Request, HttpTester.Response, ResponseHttpFields, WebSocketHttpFieldsWrapper
public interface HttpFields extends Iterable<HttpField>, Supplier<HttpFields>

An ordered collection of HttpFields that represent the HTTP headers or HTTP trailers of an HTTP request or an HTTP response.

HttpFields is immutable and typically used in server-side HTTP requests and client-side HTTP responses, while HttpFields.Mutable is mutable and typically used in server-side HTTP responses and client-side HTTP requests.

Access is always more efficient using HttpHeader keys rather than String field names.

The primary implementations of HttpFields have been optimized assuming few lookup operations, thus typically if many HttpFields need to looked up, it may be better to use an Iterator to find multiple fields in a single iteration.

  • Field Details

    • EXPIRES_01JAN1970

      static final HttpField EXPIRES_01JAN1970

      A constant HttpField for the HTTP header:

      Expires: Thu, 01 Jan 1970 00:00:00 GMT

    • CONNECTION_CLOSE

      static final HttpField CONNECTION_CLOSE

      A constant HttpField for the HTTP header:

      Connection: close

    • CONNECTION_KEEPALIVE

      static final HttpField CONNECTION_KEEPALIVE

      A constant HttpField for the HTTP header:

      Connection: keep-alive

    • CONTENT_LENGTH_0

      static final HttpField CONTENT_LENGTH_0

      A constant HttpField for the HTTP header:

      Content-Length: 0

    • EMPTY

      static final HttpFields EMPTY

      A constant for an immutable and empty HttpFields.

  • Method Details

    • build

      static HttpFields.Mutable build()

      Returns an empty HttpFields.Mutable instance.

      Returns:
      an empty HttpFields.Mutable instance

    • build

      static HttpFields.Mutable build(int capacity)

      Returns an empty HttpFields.Mutable instance with the given initial capacity.

      The given capacity indicates the initial capacity of the storage for the HttpFields.

      When the capacity is exceeded, the storage is resized to accommodate the additional HttpFields.

      Parameters:
      capacity - the initial capacity of the storage for the HttpFields
      Returns:
      an empty instance with the given initial capacity

    • build

      static HttpFields.Mutable build(HttpFields fields)

      Returns a new HttpFields.Mutable instance containing a copy of all the HttpFields of the given HttpFields parameter.

      Parameters:
      fields - the HttpFields to copy
      Returns:
      a new HttpFields.Mutable instance containing a copy of the given HttpFields

    • build

      static HttpFields.Mutable build(HttpFields fields, HttpField replaceField)

      Returns a new HttpFields.Mutable instance containing a copy of all the HttpFields of the given HttpFields, replacing with the given HttpField all the fields HttpFields with the same name.

      All existing HttpFields with the same name as the replacing HttpField will be replaced by the given HttpField. If there are no fields with that name, the given HttpField is added to the returned HttpFields.Mutable instance.

      Parameters:
      fields - the HttpFields to copy
      replaceField - the HttpField that replaces others with the same name
      Returns:
      a new HttpFields.Mutable instance containing the given HttpFields and the given replacement HttpField

    • build

      static HttpFields.Mutable build(HttpFields fields, EnumSet<HttpHeader> removeFields)

      Returns a new HttpFields.Mutable instance containing a copy of all the HttpFields of the given HttpFields, removing the HttpFields with the given names.

      Parameters:
      fields - the HttpFields to copy
      removeFields - the names of the fields to remove
      Returns:
      a new HttpFields.Mutable instance containing the given HttpFields without the fields with the given names

    • from

      static HttpFields from(HttpField... fields)

      Returns an immutable HttpFields instance containing the given HttpFields.

      Parameters:
      fields - the HttpFields to be contained in the returned instance
      Returns:
      a new immutable HttpFields instance with the given HttpFields

    • get

      default HttpFields get()

      Supplies this instance, typically used to supply HTTP trailers.

      Specified by:
      get in interface Supplier<HttpFields>
      Returns:
      this instance

    • iterator

      default Iterator<HttpField> iterator()
      Specified by:
      iterator in interface Iterable<HttpField>

    • listIterator

      default ListIterator<HttpField> listIterator()
      Returns:
      an iterator over the HttpFields in this HttpFields.
      See Also:

    • listIterator

      ListIterator<HttpField> listIterator(int index)
      Returns:
      an iterator over the HttpFields in this HttpFields starting at the given index.
      See Also:

    • asImmutable

      default HttpFields asImmutable()

      Returns an immutable copy of this HttpFields instance.

      Returns:
      a new immutable copy of this HttpFields instance

    • asString

      default String asString()

      Returns the HTTP/1.1 string representation of the HttpFields of this instance.

      The format of each field is: <name>: <value>\r\n, and there will be an additional \r\n after the last field, for example:

      
 Host: localhost\r\n
 Connection: close\r\n
 \r\n
      Returns:
      an HTTP/1.1 string representation of the HttpFields of this instance

    • contains

      default boolean contains(HttpField field)

      Returns whether this instance contains the given HttpField.

      The comparison of HttpField names is case-insensitive via HttpField.isSameName(HttpField). The comparison of the field value is case-insensitive via HttpField.contains(String).

      Parameters:
      field - the HttpField to search for
      Returns:
      whether this instance contains the given HttpField

    • contains

      default boolean contains(HttpHeader header, String value)

      Returns whether this instance contains the given HttpHeader with the given value.

      The comparison of the field value is case-insensitive via HttpField.contains(String).

      Parameters:
      header - the name of the field to search for
      value - the value to search for
      Returns:
      whether this instance contains the given HttpHeader with the given value

    • containsLast

      default boolean containsLast(HttpHeader header, String value)
      Look for a value as the last value in a possible multivalued field. Parameters and specifically quality parameters are not considered.
      Parameters:
      header - The HttpHeader type to search for.
      value - The value to search for (case-insensitive)
      Returns:
      True iff the value is contained in the field value entirely or as the last element of a quoted comma separated list.
      See Also:

    • contains

      default boolean contains(String name, String value)

      Returns whether this instance contains the given field name with the given value.

      The comparison of field name is case-insensitive via HttpField.is(String). The comparison of the field value is case-insensitive via HttpField.contains(String).

      Parameters:
      name - the case-insensitive field name to search for
      value - the field value to search for
      Returns:
      whether this instance contains the given field name with the given value

    • contains

      default boolean contains(HttpHeader header)

      Returns whether this instance contains the given field name.

      Parameters:
      header - the field name to search for
      Returns:
      whether this instance contains the given field name

    • contains

      default boolean contains(EnumSet<HttpHeader> headers)

      Returns whether this instance contains at least one of the given field names.

      Parameters:
      headers - the field names to search among
      Returns:
      whether this instance contains at least one of the given field names

    • contains

      default boolean contains(String name)

      Returns whether this instance contains the given field name.

      The comparison of field name is case-insensitive via HttpField.is(String). If possible, it is more efficient to use contains(HttpHeader).

      Parameters:
      name - the case-insensitive field name to search for
      Returns:
      whether this instance contains the given field name
      See Also:

    • get

      default String get(HttpHeader header)

      Returns the encoded value of the first field with the given field name, or null if no such header is present.

      In case of multi-valued fields, the returned value is the encoded value, including commas and quotes, as returned by HttpField.getValue().

      Parameters:
      header - the field name to search for
      Returns:
      the raw value of the first field with the given field name, or null if no such header is present
      See Also:

    • getLast

      default String getLast(HttpHeader header)

      Returns the encoded value of the last field with the given field name, or null if no such header is present.

      In case of multi-valued fields, the returned value is the encoded value, including commas and quotes, as returned by HttpField.getValue().

      Parameters:
      header - the field name to search for
      Returns:
      the raw value of the last field with the given field name, or null if no such header is present
      See Also:

    • get

      default String get(String name)

      Returns the encoded value of the first field with the given field name, or null if no such field is present.

      The comparison of field name is case-insensitive via HttpField.is(String). If possible, it is more efficient to use get(HttpHeader).

      In case of multi-valued fields, the returned value is the encoded value, including commas and quotes, as returned by HttpField.getValue().

      Parameters:
      name - the case-insensitive field name to search for
      Returns:
      the raw value of the first field with the given field name, or null if no such field is present
      See Also:

    • getCSV

      default List<String> getCSV(HttpHeader header, boolean keepQuotes)

      Returns all the values of all the fields with the given field name.

      In case of multi-valued fields, the multi-value of the field is split using QuotedCSV, taking into account the given keepQuotes parameter.

      Parameters:
      header - the field name to search for
      keepQuotes - whether the fields values should retain the quotes
      Returns:
      a list of all the values of all the fields with the given name, or an empty list if no such field name is present

    • getCSV

      default List<String> getCSV(String name, boolean keepQuotes)

      Returns all the values of all the fields with the given field name.

      The comparison of field name is case-insensitive via HttpField.is(String).

      In case of multi-valued fields, the multi-value of the field is split using QuotedCSV, taking into account the given keepQuotes parameter.

      Parameters:
      name - the case-insensitive field name to search for
      keepQuotes - whether the fields values should retain the quotes
      Returns:
      a list of all the values of all the fields with the given name, or an empty list if no such field name is present

    • getDateField

      default long getDateField(String name)

      Returns the value of a date field as the number of milliseconds since the Unix Epoch, or -1 if no such field is present.

      The comparison of field name is case-insensitive via HttpField.is(String).

      Parameters:
      name - the case-insensitive field name to search for
      Returns:
      the value of the field as the number of milliseconds since Unix Epoch, or -1 if no such field is present

    • getDateField

      default long getDateField(HttpHeader header)

      Returns the value of a date field as the number of milliseconds since the Unix Epoch, or -1 if no such field is present.

      Parameters:
      header - the field name to search for
      Returns:
      the value of the field as the number of milliseconds since Unix Epoch, or -1 if no such field is present

    • getField

      default HttpField getField(int index)

      Returns the HttpField at the given index, or null if there is no field at the given index.

      Parameters:
      index - the index of the HttpField
      Returns:
      the HttpField at the given index, or null if there is no field at the given index

    • getField

      default HttpField getField(HttpHeader header)

      Returns the first HttpField with the given field name, or null if no such field is present.

      Parameters:
      header - the field name to search for
      Returns:
      the first HttpField with the given field name, or null if no such field is present

    • getField

      default HttpField getField(String name)

      Returns the first HttpField with the given field name, or null if no such field is present.

      The comparison of field name is case-insensitive via HttpField.is(String).

      Parameters:
      name - the case-insensitive field name to search for
      Returns:
      the first HttpField with the given field name, or null if no such field is present

    • getFieldNames

      @Deprecated default Enumeration<String> getFieldNames()
      Deprecated.
      use getFieldNamesCollection()
      Returns:
      an enumeration of field names

    • getFieldNamesCollection

      default Set<String> getFieldNamesCollection()

      Returns a Set of the field names.

      Case-sensitivity of the field names is preserved.

      Returns:
      an immutable Set of the field names. Changes made to the HttpFields after this call are not reflected in the set.

    • getFields

      default List<HttpField> getFields(HttpHeader header)

      Returns all the HttpFields with the given field name.

      Parameters:
      header - the field name to search for
      Returns:
      a list of the HttpFields with the given field name, or an empty list if no such field name is present

    • getFields

      default List<HttpField> getFields(String name)

      Returns all the HttpFields with the given field name.

      The comparison of field name is case-insensitive via HttpField.is(String).

      Parameters:
      name - the case-insensitive field name to search for
      Returns:
      a list of the HttpFields with the given field name, or an empty list if no such field name is present

    • getLongField

      default long getLongField(String name) throws NumberFormatException

      Returns the value of a field as a long value, or -1 if no such field is present.

      The comparison of field name is case-insensitive via HttpField.is(String).

      Parameters:
      name - the case-insensitive field name
      Returns:
      the value of the field as a long, or -1 if no such field is present
      Throws:
      NumberFormatException - if the value of the field cannot be converted to a long

    • getLongField

      default long getLongField(HttpHeader header) throws NumberFormatException

      Returns the value of a field as a long value, or -1 if no such field is present.

      Parameters:
      header - the field name
      Returns:
      the value of the field as a long, or -1 if no such field is present
      Throws:
      NumberFormatException - if the value of the field cannot be converted to a long

    • getQualityCSV

      default List<String> getQualityCSV(HttpHeader header)

      Returns all the values of all the fields with the given name, split and sorted in quality order using QuotedQualityCSV.

      Parameters:
      header - the field name to search for
      Returns:
      a list of all the values of all the fields with the given name, split and sorted in quality order, or an empty list if no such field name is present

    • getQualityCSV

      default List<String> getQualityCSV(HttpHeader header, ToIntFunction<String> secondaryOrdering)

      Returns all the values of all the fields with the given name, split and sorted first in quality order and then optionally further sorted with the given function, using QuotedQualityCSV.

      Parameters:
      header - the field name to search for
      secondaryOrdering - the secondary sort function, or null for no secondary sort
      Returns:
      a list of all the values of all the fields with the given name, split and sorted in quality order and optionally further sorted with the given function, or an empty list if no such field name is present

    • getQualityCSV

      default List<String> getQualityCSV(String name)

      Returns all the values of all the fields with the given name, split and sorted in quality order using QuotedQualityCSV.

      The comparison of field name is case-insensitive via HttpField.is(String).

      Parameters:
      name - the case-insensitive field name to search for
      Returns:
      a list of all the values of all the fields with the given name, split and sorted in quality order, or an empty list if no such field name is present

    • getValues

      default Enumeration<String> getValues(String name)

      Returns an Enumeration of the encoded values of all the fields with the given name.

      The comparison of field name is case-insensitive via HttpField.is(String).

      In case of multi-valued fields, the returned value is the encoded value, including commas and quotes, as returned by HttpField.getValue().

      Parameters:
      name - the case-insensitive field name to search for
      Returns:
      an Enumeration of the encoded values of all the fields with the given name

    • getValuesList

      default List<String> getValuesList(HttpHeader header)

      Returns a list of the encoded values of all the fields with the given name.

      In case of multi-valued fields, the returned value is the encoded value, including commas and quotes, as returned by HttpField.getValue().

      Parameters:
      header - the field name to search for
      Returns:
      a list of the encoded values of all the fields with the given name, or an empty list if no such field name is present

    • getValuesList

      default List<String> getValuesList(String name)

      Returns a list of the encoded values of all the fields with the given name.

      The comparison of field name is case-insensitive via HttpField.is(String).

      In case of multi-valued fields, the returned value is the encoded value, including commas and quotes, as returned by HttpField.getValue().

      Parameters:
      name - the field name to search for
      Returns:
      a list of the encoded values of all the fields with the given name, or an empty list if no such field name is present

    • isEqualTo

      default boolean isEqualTo(HttpFields that)

      Returns whether this instance is equal to the given instance.

      Returns true if and only if the two instances have the same number of fields, in the same order, and each field is equal, but makes no difference between HttpFields.Mutable and non-HttpFields.Mutable instances.

      Parameters:
      that - the HttpFields instance to compare to
      Returns:
      whether the two instances are equal

    • size

      default int size()
      Returns:
      the number of HttpFields in this instance

    • stream

      default Stream<HttpField> stream()
      Returns:
      a sequential stream of the HttpFields in this instance