Module org.eclipse.jetty.http

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

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.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	HttpFields.ImmutableHttpFields	Deprecated, for removal: This API element is subject to removal in a future version.
static interface	HttpFields.Mutable	A mutable version of HttpFields.
static class	HttpFields.MutableHttpFields	Deprecated, for removal: This API element is subject to removal in a future version.

Field Summary

Fields

Modifier and Type	Field	Description
static final HttpField	CONNECTION_CLOSE	A constant HttpField for the HTTP header:
static final HttpField	CONNECTION_KEEPALIVE	A constant HttpField for the HTTP header:
static final HttpField	CONTENT_LENGTH_0	A constant HttpField for the HTTP header:
static final HttpFields	EMPTY	A constant for an immutable and empty HttpFields.
static final HttpField	EXPIRES_01JAN1970	A constant HttpField for the HTTP header:

Method Summary

Modifier and Type	Method	Description
default HttpFields	asImmutable()	Returns an immutable copy of this HttpFields instance.
static Map<String,List<String>>	asMap(HttpFields fields)	Wraps an instance of HttpFields as a Map.
default String	asString()	Returns the HTTP/1.1 string representation of the HttpFields of this instance.
static HttpFields.Mutable	build()	Returns an empty HttpFields.Mutable instance.
static HttpFields.Mutable	build(int capacity)	Returns an empty HttpFields.Mutable instance with the given initial capacity.
static HttpFields.Mutable	build(HttpFields fields)	Returns a new HttpFields.Mutable instance containing a copy of all the HttpFields of the given HttpFields parameter.
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.
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.
default boolean	contains(String name)	Returns whether this instance contains the given field name.
default boolean	contains(String name, String value)	Returns whether this instance contains the given field name with the given value.
default boolean	contains(EnumSet<HttpHeader> headers)	Returns whether this instance contains at least one of the given field names.
default boolean	contains(HttpField field)	Returns whether this instance contains the given HttpField.
default boolean	contains(HttpHeader header)	Returns whether this instance contains the given field name.
default boolean	contains(HttpHeader header, String value)	Returns whether this instance contains the given HttpHeader with the given value.
default boolean	containsLast(HttpHeader header, String value)	Look for a value as the last value in a possible multivalued field.
static HttpFields	from(HttpField... fields)	Returns an immutable HttpFields instance containing the given HttpFields.
default HttpFields	get()	Supplies this instance, typically used to supply HTTP trailers.
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.
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.
default List<String>	getCSV(String name, boolean keepQuotes)	Returns all the values of all the fields with the given field name.
default List<String>	getCSV(HttpHeader header, boolean keepQuotes)	Returns all the values of all the fields with the given field name.
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.
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.
default HttpField	getField(int index)	Returns the HttpField at the given index, or null if there is no field at the given index.
default HttpField	getField(String name)	Returns the first HttpField with the given field name, or null if no such field is present.
default HttpField	getField(HttpHeader header)	Returns the first HttpField with the given field name, or null if no such field is present.
default Enumeration<String>	getFieldNames()	Deprecated. use getFieldNamesCollection()
default Set<String>	getFieldNamesCollection()	Returns a Set of the field names.
default List<HttpField>	getFields(String name)	Returns all the HttpFields with the given field name.
default List<HttpField>	getFields(HttpHeader header)	Returns all the HttpFields with the given field name.
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.
default long	getLongField(String name)	Returns the value of a field as a long value, or -1 if no such field is present.
default long	getLongField(HttpHeader header)	Returns the value of a field as a long value, or -1 if no such field is present.
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.
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.
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.
default Enumeration<String>	getValues(String name)	Returns an Enumeration of the encoded values of all the fields with the given name.
default List<String>	getValuesList(String name)	Returns a list of the encoded values of all the fields with the given name.
default List<String>	getValuesList(HttpHeader header)	Returns a list of the encoded values of all the fields with the given name.
default boolean	isEqualTo(HttpFields that)	Returns whether this instance is equal to the given instance.
default Iterator<HttpField>	iterator()
default ListIterator<HttpField>	listIterator()
ListIterator<HttpField>	listIterator(int index)
default int	size()
default Stream<HttpField>	stream()

Methods inherited from interface java.lang.Iterable

forEach, spliterator

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

listIterator

ListIterator<HttpField> listIterator(int index)

Returns:

an iterator over the HttpFields in this HttpFields starting at the given index.

See Also:

• listIterator()

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:

• HttpField.containsLast(String)

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:

• contains(HttpHeader)

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:

• HttpField.getValue()

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:

• HttpField.getValue()

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:

• HttpField.getValue()
• get(HttpHeader)

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

asMap

static Map<String,List<String>> asMap(HttpFields fields)

Wraps an instance of HttpFields as a Map.

If the provided HttpFields is an instance of HttpFields.Mutable then changes to the Map will be reflected in the underlying HttpFields. Otherwise, any modification to the Map will throw UnsupportedOperationException.

Parameters:

fields - the HttpFields to convert to a Map.

Returns:

an Map representing the contents of the HttpFields.

stream

default Stream<HttpField> stream()

Returns:

a sequential stream of the HttpFields in this instance