OpenJDK 1.23 · java.net.http.HttpHeaders · APIdia, the JavaDoc alternative

A read-only view of a set of HTTP headers.

An HttpHeaders is not typically created directly, but rather returned from an HttpRequest or an HttpResponse. Specific HTTP headers can be set for a request through one of the request builder's headers methods.

The methods of this class ( that accept a String header name ), and the Map returned by the map method, operate without regard to case when retrieving the header value(s).

An HTTP header name may appear more than once in the HTTP protocol. As such, headers are represented as a name and a list of values. Each occurrence of a header value is added verbatim, to the appropriate header name list, without interpreting its value. In particular, HttpHeaders does not perform any splitting or joining of comma separated header value strings. The order of elements in a header value list is preserved when building a request. For responses, the order of elements in a header value list is the order in which they were received. The Map returned by the map method, however, does not provide any guarantee with regard to the ordering of its entries.

HttpHeaders instances are immutable.

Field Summary

Modifier and Type	Field and Description
private final Map<String, List<String>>	headers
private static final HttpHeaders	NO_HEADERS

Constructor Summary

Access	Constructor and Description
private	HttpHeaders(Map<String, List<String>> headers)

Method Summary

Modifier and Type	Method and Description
public List<String>	Returns: a List of headers string values allValues(String the header name name) Returns an unmodifiable List of all of the header string values of the given named header.
private static final int	entryHash(Map.Entry<String, List<String>> e)
public final boolean	Returns: `true` if, and only if, the given object is an `HttpHeaders` that is equal to this HTTP headers equals(Object the object to which this object is to be compared obj) Overrides java.lang.Object.equals. Tests this HTTP headers instance for equality with the given object.
public Optional<String>	Returns: an `Optional<String>` containing the first named header string value, if present firstValue(String the header name name) Returns an `Optional` containing the first header string value of the given named (and possibly multi-valued) header.
public OptionalLong	Returns: an `OptionalLong` firstValueAsLong(String the header name name) Returns an `OptionalLong` containing the first header string value of the named header field.
public final int	Returns: the hash-code value for this HTTP headers hashCode() Overrides java.lang.Object.hashCode. Computes a hash code for this HTTP headers instance.
private static HttpHeaders	headersOf(Map<String, List<String>> map, BiPredicate<String, String> filter)
public Map<String, List<String>>	Returns: the Map map() Returns an unmodifiable multi Map view of this HttpHeaders.
public static HttpHeaders	Returns: an HTTP headers instance containing the given headers of(Map<String, List<String>> the map containing the header names and values headerMap, BiPredicate<String, String> a filter that can be used to inspect each header-name-and-value pair in the given map to determine if it should, or should not, be added to the to the HTTP headers filter) Returns an HTTP headers from the given map.
public String	Returns: a string describing the HTTP headers toString() Overrides java.lang.Object.toString. Returns this HTTP headers as a string.

Inherited from java.lang.Object:: clone finalize getClass notify notifyAll wait wait wait

Field Detail

headers	back to summary
private final Map<String, List<String>> headers

NO_HEADERS	back to summary
private static final HttpHeaders NO_HEADERS

Constructor Detail

HttpHeaders	back to summary
private HttpHeaders(Map<String, List<String>> headers)

Method Detail

allValues	back to summary
public List<String> allValues(String name) Returns an unmodifiable List of all of the header string values of the given named header. Always returns a List, which may be empty if the header is not present. Parameters name:String the header name Returns:List<String> a List of headers string values

allValues

back to summary

public List<String> allValues(String name)

Returns an unmodifiable List of all of the header string values of the given named header. Always returns a List, which may be empty if the header is not present.

Parameters

name:String: the header name

Returns:List<String>

a List of headers string values

entryHash	back to summary
private static final int entryHash(Map.Entry<String, List<String>> e)

equals back to summary

equals	back to summary
public final boolean equals(Object obj) Overrides java.lang.Object.equals. Tests this HTTP headers instance for equality with the given object. If the given object is not an `HttpHeaders` then this method returns `false`. Two HTTP headers are equal if each of their corresponding maps are equal. This method satisfies the general contract of the `Object.equals` method. Parameters obj:Object the object to which this object is to be compared Returns:boolean `true` if, and only if, the given object is an `HttpHeaders` that is equal to this HTTP headers

public final boolean equals(Object obj)

Overrides java.lang.Object.equals.

Tests this HTTP headers instance for equality with the given object.

If the given object is not an HttpHeaders then this method returns false. Two HTTP headers are equal if each of their corresponding maps are equal.

This method satisfies the general contract of the Object.equals method.

Parameters

obj:Object: the object to which this object is to be compared

Returns:boolean

true if, and only if, the given object is an HttpHeaders that is equal to this HTTP headers

firstValue back to summary

firstValue	back to summary
public Optional<String> firstValue(String name) Returns an `Optional` containing the first header string value of the given named (and possibly multi-valued) header. If the header is not present, then the returned `Optional` is empty. Parameters name:String the header name Returns:Optional<String> an `Optional<String>` containing the first named header string value, if present

public Optional<String> firstValue(String name)

Returns an Optional containing the first header string value of the given named (and possibly multi-valued) header. If the header is not present, then the returned Optional is empty.

Parameters

name:String: the header name

Returns:Optional<String>

an Optional<String> containing the first named header string value, if present

firstValueAsLong back to summary

firstValueAsLong	back to summary
public OptionalLong firstValueAsLong(String name) Returns an `OptionalLong` containing the first header string value of the named header field. If the header is not present, then the Optional is empty. If the header is present but contains a value that does not parse as a `Long` value, then an exception is thrown. Parameters name:String the header name Returns:OptionalLong an `OptionalLong` Exceptions NumberFormatException: if a value is found, but does not parse as a Long

public OptionalLong firstValueAsLong(String name)

Returns an OptionalLong containing the first header string value of the named header field. If the header is not present, then the Optional is empty. If the header is present but contains a value that does not parse as a Long value, then an exception is thrown.

Parameters

name:String: the header name

Returns:OptionalLong

an OptionalLong

Exceptions

NumberFormatException:: if a value is found, but does not parse as a Long

hashCode back to summary

hashCode	back to summary
public final int hashCode() Overrides java.lang.Object.hashCode. Computes a hash code for this HTTP headers instance. The hash code is based upon the components of the HTTP headers `map`, and satisfies the general contract of the `Object.hashCode` method. Returns:int the hash-code value for this HTTP headers

public final int hashCode()

Overrides java.lang.Object.hashCode.

Computes a hash code for this HTTP headers instance.

The hash code is based upon the components of the HTTP headers map, and satisfies the general contract of the Object.hashCode method.

Returns:int: the hash-code value for this HTTP headers

headersOf	back to summary
private static HttpHeaders headersOf(Map<String, List<String>> map, BiPredicate<String, String> filter)

map	back to summary
public Map<String, List<String>> map() Returns an unmodifiable multi Map view of this HttpHeaders. Returns:Map<String, List<String>> the Map

map

back to summary

public Map<String, List<String>> map()

Returns an unmodifiable multi Map view of this HttpHeaders.

Returns:Map<String, List<String>>: the Map

of back to summary

of	back to summary
public static HttpHeaders of(Map<String, List<String>> headerMap, BiPredicate<String, String> filter) Returns an HTTP headers from the given map. The given map's key represents the header name, and its value the list of string header values for that header name. An HTTP header name may appear more than once in the HTTP protocol. Such, multi-valued, headers must be represented by a single entry in the given map, whose entry value is a list that represents the multiple header string values. Leading and trailing whitespaces are removed from all string values retrieved from the given map and its lists before processing. Only headers that, after filtering, contain at least one, possibly empty string, value will be added to the HTTP headers. API Note The primary purpose of this method is for testing frameworks. Per-request headers can be set through one of the `HttpRequest` `headers` methods. Parameters headerMap:Map<String, List<String>> the map containing the header names and values filter:BiPredicate<String, String> a filter that can be used to inspect each header-name-and-value pair in the given map to determine if it should, or should not, be added to the to the HTTP headers Returns:HttpHeaders an HTTP headers instance containing the given headers Exceptions NullPointerException: if any of: `headerMap`, a key or value in the given map, or an entry in the map's value list, or `filter`, is `null` IllegalArgumentException: if the given `headerMap` contains any two keys that are equal ( without regard to case ); or if the given map contains any key whose length, after trimming whitespaces, is `0`

public static HttpHeaders of(Map<String, List<String>> headerMap, BiPredicate<String, String> filter)

Returns an HTTP headers from the given map. The given map's key represents the header name, and its value the list of string header values for that header name.

An HTTP header name may appear more than once in the HTTP protocol. Such, multi-valued, headers must be represented by a single entry in the given map, whose entry value is a list that represents the multiple header string values. Leading and trailing whitespaces are removed from all string values retrieved from the given map and its lists before processing. Only headers that, after filtering, contain at least one, possibly empty string, value will be added to the HTTP headers.

API Note

The primary purpose of this method is for testing frameworks. Per-request headers can be set through one of the HttpRequest headers methods.

Parameters

headerMap:Map<String, List<String>>: the map containing the header names and values
filter:BiPredicate<String, String>: a filter that can be used to inspect each header-name-and-value pair in the given map to determine if it should, or should not, be added to the to the HTTP headers

Returns:HttpHeaders

an HTTP headers instance containing the given headers

Exceptions

NullPointerException:: if any of: headerMap, a key or value in the given map, or an entry in the map's value list, or filter, is null
IllegalArgumentException:: if the given headerMap contains any two keys that are equal ( without regard to case ); or if the given map contains any key whose length, after trimming whitespaces, is 0

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Returns this HTTP headers as a string. Returns:String a string describing the HTTP headers Annotations @Override

toString

back to summary

public String toString()

Overrides java.lang.Object.toString.

Returns this HTTP headers as a string.

Returns:String

a string describing the HTTP headers

Annotations

@Override

public final Class HttpHeaders

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail