io.servicetalk.http.api

Interface HttpHeaders

All Superinterfaces:

Iterable<Map.Entry<CharSequence,CharSequence>>

All Known Implementing Classes:

EmptyHttpHeaders

public interface HttpHeaders
extends Iterable<Map.Entry<CharSequence,CharSequence>>

HTTP Header Fields.

All header field names are compared in a case-insensitive manner.

Method Summary

Modifier and Type	Method and Description
HttpHeaders	add(CharSequence name, CharSequence... values) Adds new headers with the specified name and values.
HttpHeaders	add(CharSequence name, CharSequence value) Adds a new header with the specified name and value.
HttpHeaders	add(CharSequence name, Iterable<? extends CharSequence> values) Adds new headers with the specified name and values.
default HttpHeaders	add(CharSequence name, Iterator<? extends CharSequence> valuesItr) Adds new headers with the specified name and values.
HttpHeaders	add(HttpHeaders headers) Adds all header names and values of headers to this object.
default HttpHeaders	addCookie(CharSequence name, CharSequence value) Adds a cookie with the specified name and value.
HttpHeaders	addCookie(HttpCookiePair cookie) Adds a cookie.
default HttpHeaders	addSetCookie(CharSequence name, CharSequence value) Adds a set-cookie with the specified name and value.
HttpHeaders	addSetCookie(HttpSetCookie cookie) Adds a set-cookie.
HttpHeaders	clear() Removes all headers.
default boolean	contains(CharSequence name) Returns true if a header with the name exists, false otherwise.
boolean	contains(CharSequence name, CharSequence value) Returns true if a header with the name and value exists, false otherwise.
boolean	containsIgnoreCase(CharSequence name, CharSequence value) Returns true if a header with the name and value exists, false otherwise.
CharSequence	get(CharSequence name) Returns the value of a header with the specified name.
default CharSequence	get(CharSequence name, CharSequence defaultValue) Returns the value of a header with the specified name.
CharSequence	getAndRemove(CharSequence name) Returns the value of a header with the specified name and removes it from this object.
default CharSequence	getAndRemove(CharSequence name, CharSequence defaultValue) Returns the value of a header with the specified name and removes it from this object.
HttpCookiePair	getCookie(CharSequence name) Gets a cookie identified by name.
default Iterable<? extends HttpCookiePair>	getCookies() Gets all the cookies.
default Iterable<? extends HttpCookiePair>	getCookies(CharSequence name) Gets the cookies with the same name.
Iterator<? extends HttpCookiePair>	getCookiesIterator() Gets all the cookies.
Iterator<? extends HttpCookiePair>	getCookiesIterator(CharSequence name) Gets the cookies with the same name.
HttpSetCookie	getSetCookie(CharSequence name) Gets a set-cookie identified by name.
default Iterable<? extends HttpSetCookie>	getSetCookies() Gets all the set-cookies.
default Iterable<? extends HttpSetCookie>	getSetCookies(CharSequence name) Gets the set-cookies with the same name.
default Iterable<? extends HttpSetCookie>	getSetCookies(CharSequence name, CharSequence domain, CharSequence path) Gets the set-cookies with the same name.
Iterator<? extends HttpSetCookie>	getSetCookiesIterator() Gets all the set-cookies.
Iterator<? extends HttpSetCookie>	getSetCookiesIterator(CharSequence name) Gets the set-cookies with the same name.
Iterator<? extends HttpSetCookie>	getSetCookiesIterator(CharSequence name, CharSequence domain, CharSequence path) Gets the set-cookies with the same name.
boolean	isEmpty() Returns true if size() equals 0.
Iterator<Map.Entry<CharSequence,CharSequence>>	iterator()
Set<? extends CharSequence>	names() Returns a Set of all header names in this object.
boolean	remove(CharSequence name) Removes all headers with the specified name.
boolean	remove(CharSequence name, CharSequence value) Removes specific value(s) from the specified header name.
boolean	removeCookies(CharSequence name) Removes all cookie identified by name.
boolean	removeIgnoreCase(CharSequence name, CharSequence value) Removes specific value(s) from the specified header name.
boolean	removeSetCookies(CharSequence name) Removes all set-cookie identified by name.
boolean	removeSetCookies(CharSequence name, CharSequence domain, CharSequence path) Removes all set-cookie identified by name.
default HttpHeaders	replace(HttpHeaders headers) Removes all header names contained in headers from this object, and then adds all headers contained in headers.
HttpHeaders	set(CharSequence name, CharSequence... values) Sets a header with the specified name and values.
HttpHeaders	set(CharSequence name, CharSequence value) Sets a header with the specified name and value.
HttpHeaders	set(CharSequence name, Iterable<? extends CharSequence> values) Sets a new header with the specified name and values.
default HttpHeaders	set(CharSequence name, Iterator<? extends CharSequence> valueItr) Sets a new header with the specified name and values.
default HttpHeaders	set(HttpHeaders headers) Clears the current header entries and copies all header entries of the specified headers object.
int	size() Returns the number of headers in this object.
default Spliterator<Map.Entry<CharSequence,CharSequence>>	spliterator()
String	toString() Returns a String representation of this HttpHeaders.
default String	toString(BiFunction<? super CharSequence,? super CharSequence,CharSequence> filter) Builds a string which represents all the content in this HttpHeaders in which sensitive headers can be filtered via filter.
default Iterable<? extends CharSequence>	values(CharSequence name) Returns all values for the header with the specified name.
Iterator<? extends CharSequence>	valuesIterator(CharSequence name) Returns all values for the header with the specified name.

Methods inherited from interface Iterable

forEach

Method Detail

get

@Nullable
CharSequence get(CharSequence name)

Returns the value of a header with the specified name. If there is more than one value for the specified name, the first value in insertion order is returned.

Parameters:

name - the name of the header to retrieve.

Returns:

the first header value if the header is found. null if there's no such header.

get

default CharSequence get(CharSequence name,
                         CharSequence defaultValue)

Returns the value of a header with the specified name. If there is more than one value for the specified name, the first value in insertion order is returned.

Parameters:

name - the name of the header to retrieve.

defaultValue - the default value.

Returns:

the first header value or defaultValue if there is no such header.

getAndRemove

@Nullable
CharSequence getAndRemove(CharSequence name)

Returns the value of a header with the specified name and removes it from this object. If there is more than one value for the specified name, the first value in insertion order is returned.

Parameters:

name - the name of the header to retrieve.

Returns:

the first header value or null if there is no such header.

getAndRemove

default CharSequence getAndRemove(CharSequence name,
                                  CharSequence defaultValue)

Returns the value of a header with the specified name and removes it from this object. If there is more than one value for the specified name, the first value in insertion order is returned.

Parameters:

name - the name of the header to retrieve.

defaultValue - the default value.

Returns:

the first header value or defaultValue if there is no such header.

values

default Iterable<? extends CharSequence> values(CharSequence name)

Returns all values for the header with the specified name.

Parameters:

name - the name of the header to retrieve.

Returns:

a Iterable of header values or an empty Iterable if no values are found.

See Also:

if minimal object allocation is required.

valuesIterator

Iterator<? extends CharSequence> valuesIterator(CharSequence name)

Returns all values for the header with the specified name.

Parameters:

name - the name of the header to retrieve.

Returns:

a Iterator of header values or an empty Iterator if no values are found.

See Also:

if Iterable is preferred, at the expense of more object allocation.

contains

default boolean contains(CharSequence name)

Returns true if a header with the name exists, false otherwise.

Parameters:

name - the header name.

Returns:

true if name exists.

contains

boolean contains(CharSequence name,
                 CharSequence value)

Returns true if a header with the name and value exists, false otherwise.

Parameters:

name - the header name.

value - the header value of the header to find.

Returns:

true if a name, value pair exists.

containsIgnoreCase

boolean containsIgnoreCase(CharSequence name,
                           CharSequence value)

Returns true if a header with the name and value exists, false otherwise.

Case insensitive compare is done on the value.

Parameters:

name - the name of the header to find.

value - the value of the header to find.

Returns:

true if found.

size

int size()

Returns the number of headers in this object.

Returns:

the number of headers in this object.

isEmpty

boolean isEmpty()

Returns true if size() equals 0.

Returns:

true if size() equals 0.

names

Set<? extends CharSequence> names()

Returns a Set of all header names in this object. The returned Set cannot be modified.

Returns:

a Set of all header names in this object. The returned Set cannot be modified.

add

HttpHeaders add(CharSequence name,
                CharSequence value)

Adds a new header with the specified name and value.

Parameters:

name - the name of the header.

value - the value of the header.

Returns:

this.

add

HttpHeaders add(CharSequence name,
                Iterable<? extends CharSequence> values)

Adds new headers with the specified name and values. This method is semantically equivalent to:

 for (T value : values) {
     headers.add(name, value);
 }
 

Parameters:

name - the name of the header.

values - the values of the header.

Returns:

this.

add

default HttpHeaders add(CharSequence name,
                        Iterator<? extends CharSequence> valuesItr)

Adds new headers with the specified name and values. This method is semantically equivalent to:

 while (valueItr.hasNext()) {
     headers.add(name, valueItr.next());
 }
 

Parameters:

name - the name of the header.

valuesItr - the values of the header.

Returns:

this.

add

HttpHeaders add(CharSequence name,
                CharSequence... values)

Adds new headers with the specified name and values. This method is semantically equivalent to:

 for (T value : values) {
     headers.add(name, value);
 }
 

Parameters:

name - the name of the header.

values - the values of the header.

Returns:

this.

add

HttpHeaders add(HttpHeaders headers)

Adds all header names and values of headers to this object.

Parameters:

headers - the headers to add.

Returns:

this.

set

HttpHeaders set(CharSequence name,
                CharSequence value)

Sets a header with the specified name and value. Any existing headers with the same name are overwritten.

Parameters:

name - the name of the header.

value - the value of the header.

Returns:

this.

set

HttpHeaders set(CharSequence name,
                Iterable<? extends CharSequence> values)

Sets a new header with the specified name and values. This method is equivalent to:

 headers.remove(name);
 for (T value : values) {
     headers.add(name, value);
 }
 

Parameters:

name - the name of the header.

values - the values of the header.

Returns:

this.

set

default HttpHeaders set(CharSequence name,
                        Iterator<? extends CharSequence> valueItr)

Sets a new header with the specified name and values. This method is equivalent to:

 headers.remove(name);
 while (valueItr.hasNext()) {
     headers.add(name, valueItr.next());
 }
 

Parameters:

name - the name of the header.

valueItr - the values of the header.

Returns:

this.

set

HttpHeaders set(CharSequence name,
                CharSequence... values)

Sets a header with the specified name and values. Any existing headers with this name are removed. This method is equivalent to:

 headers.remove(name);
 for (T value : values) {
     headers.add(name, value);
 }
 

Parameters:

name - the name of the header.

values - the values of the header.

Returns:

this.

set

default HttpHeaders set(HttpHeaders headers)

Clears the current header entries and copies all header entries of the specified headers object.

Parameters:

headers - the headers object which contains new values.

Returns:

this.

replace

default HttpHeaders replace(HttpHeaders headers)

Removes all header names contained in headers from this object, and then adds all headers contained in headers.

Parameters:

headers - the headers used to remove names and then add new entries.

Returns:

this.

remove

boolean remove(CharSequence name)

Removes all headers with the specified name.

Parameters:

name - the name of the header.

Returns:

true if at least one entry has been removed.

remove

boolean remove(CharSequence name,
               CharSequence value)

Removes specific value(s) from the specified header name. If the header has more than one identical values, all of them will be removed.

Parameters:

name - the name of the header.

value - the value of the header to remove.

Returns:

true if at least one value has been removed.

removeIgnoreCase

boolean removeIgnoreCase(CharSequence name,
                         CharSequence value)

Removes specific value(s) from the specified header name. If the header has more than one identical values, all of them will be removed.

Case insensitive compare is done on the value.

Parameters:

name - the name of the header.

value - the value of the header to remove.

Returns:

true if at least one value has been removed.

clear

HttpHeaders clear()

Removes all headers.

Returns:

this.

iterator

Iterator<Map.Entry<CharSequence,CharSequence>> iterator()

Specified by:

iterator in interface Iterable<Map.Entry<CharSequence,CharSequence>>

spliterator

default Spliterator<Map.Entry<CharSequence,CharSequence>> spliterator()

Specified by:

spliterator in interface Iterable<Map.Entry<CharSequence,CharSequence>>

toString

String toString()

Returns a String representation of this HttpHeaders. To avoid accidentally logging sensitive information, implementations should be cautious about logging header content and consider using toString(BiFunction).

Overrides:

toString in class Object

Returns:

a simple String representation of this HttpHeaders.

toString

default String toString(BiFunction<? super CharSequence,? super CharSequence,CharSequence> filter)

Builds a string which represents all the content in this HttpHeaders in which sensitive headers can be filtered via filter.

Parameters:

filter - a function that accepts the header name and value and returns the filtered value.

Returns:

string representation of this HttpHeaders.

getCookie

@Nullable
HttpCookiePair getCookie(CharSequence name)

Gets a cookie identified by name. If there is more than one HttpSetCookie for the specified name, the first HttpSetCookie in insertion order is returned.

Parameters:

name - the cookie-name to look for.

Returns:

a HttpSetCookie identified by name.

getSetCookie

@Nullable
HttpSetCookie getSetCookie(CharSequence name)

Gets a set-cookie identified by name. If there is more than one HttpSetCookie for the specified name, the first HttpSetCookie in insertion order is returned.

Parameters:

name - the cookie-name to look for.

Returns:

a HttpSetCookie identified by name.

getCookies

default Iterable<? extends HttpCookiePair> getCookies()

Gets all the cookies.

Returns:

An Iterable with all the cookies.

See Also:

if minimal object allocation is required.

getCookiesIterator

Iterator<? extends HttpCookiePair> getCookiesIterator()

Gets all the cookies.

Returns:

An Iterator with all the cookies.

See Also:

if Iterable is preferred, at the expense of more object allocation.

getCookies

default Iterable<? extends HttpCookiePair> getCookies(CharSequence name)

Gets the cookies with the same name.

Parameters:

name - the cookie-name of the HttpSetCookies to get.

Returns:

An Iterable where all the HttpSetCookies have the same name.

See Also:

if minimal object allocation is required.

getCookiesIterator

Iterator<? extends HttpCookiePair> getCookiesIterator(CharSequence name)

Gets the cookies with the same name.

Parameters:

name - the cookie-name of the HttpSetCookies to get.

Returns:

An Iterator where all the HttpSetCookies have the same name.

See Also:

if Iterable is preferred, at the expense of more object allocation.

getSetCookies

default Iterable<? extends HttpSetCookie> getSetCookies()

Gets all the set-cookies.

Returns:

An Iterable with all the set-cookies.

See Also:

if minimal object allocation is required.

getSetCookiesIterator

Iterator<? extends HttpSetCookie> getSetCookiesIterator()

Gets all the set-cookies.

Returns:

An Iterator with all the set-cookies.

See Also:

if Iterable is preferred, at the expense of more object allocation.

getSetCookies

default Iterable<? extends HttpSetCookie> getSetCookies(CharSequence name)

Gets the set-cookies with the same name.

Parameters:

name - the cookie-name of the HttpSetCookies to get.

Returns:

An Iterable where all the HttpSetCookies have the same name.

See Also:

if minimal object allocation is required.

getSetCookiesIterator

Iterator<? extends HttpSetCookie> getSetCookiesIterator(CharSequence name)

Gets the set-cookies with the same name.

Parameters:

name - the cookie-name of the HttpSetCookies to get.

Returns:

An Iterator where all the HttpSetCookies have the same name.

See Also:

if Iterable is preferred, at the expense of more object allocation.

getSetCookies

default Iterable<? extends HttpSetCookie> getSetCookies(CharSequence name,
                                                        CharSequence domain,
                                                        CharSequence path)

Gets the set-cookies with the same name.

Parameters:

name - the cookie-name of the HttpSetCookies to get.

domain - the domain-value of the HttpSetCookies to get. This value may be matched according to the Domain Matching algorithm.

path - the path-av of the HttpSetCookies to get. This value may be matched according to the Path Matching algorithm.

Returns:

An Iterable where all the HttpSetCookies match the parameter values.

See Also:

if minimal object allocation is required.

getSetCookiesIterator

Iterator<? extends HttpSetCookie> getSetCookiesIterator(CharSequence name,
                                                        CharSequence domain,
                                                        CharSequence path)

Gets the set-cookies with the same name.

Parameters:

name - the cookie-name of the HttpSetCookies to get.

domain - the domain-value of the HttpSetCookies to get. This value may be matched according to the Domain Matching algorithm.

path - the path-av of the HttpSetCookies to get. This value may be matched according to the Path Matching algorithm.

Returns:

An Iterator where all the HttpSetCookies match the parameter values.

See Also:

if Iterable is preferred, at the expense of more object allocation.

addCookie

HttpHeaders addCookie(HttpCookiePair cookie)

Adds a cookie.

This may result in multiple HttpCookiePairs with same name.

Parameters:

cookie - the cookie to add.

Returns:

this.

addCookie

default HttpHeaders addCookie(CharSequence name,
                              CharSequence value)

Adds a cookie with the specified name and value.

This may result in multiple HttpSetCookies with same name. Added cookie will not be wrapped, not secure, and not HTTP-only, with no path, domain, expire date and maximum age.

Parameters:

name - the name of the cookie.

value - the value of the cookie.

Returns:

this.

addSetCookie

HttpHeaders addSetCookie(HttpSetCookie cookie)

Adds a set-cookie.

This may result in multiple HttpSetCookies with same name.

Parameters:

cookie - the cookie to add.

Returns:

this.

addSetCookie

default HttpHeaders addSetCookie(CharSequence name,
                                 CharSequence value)

Adds a set-cookie with the specified name and value.

This may result in multiple HttpSetCookies with same name. Added cookie will not be wrapped, not secure, and not HTTP-only, with no path, domain, expire date and maximum age.

Parameters:

name - the name of the cookie.

value - the value of the cookie.

Returns:

this.

removeCookies

boolean removeCookies(CharSequence name)

Removes all cookie identified by name.

Parameters:

name - the cookie-name of the HttpSetCookies to remove.

Returns:

true if at least one entry has been removed.

removeSetCookies

boolean removeSetCookies(CharSequence name)

Removes all set-cookie identified by name.

Parameters:

name - the cookie-name of the HttpSetCookies to remove.

Returns:

true if at least one entry has been removed.

removeSetCookies

boolean removeSetCookies(CharSequence name,
                         CharSequence domain,
                         CharSequence path)

Removes all set-cookie identified by name.

Parameters:

name - the cookie-name of the HttpSetCookies to remove.

domain - the domain-value of the HttpSetCookies to remove. This value may be matched according to the Domain Matching algorithm.

path - the path-av of the HttpSetCookies to remove. This value may be matched according to the Path Matching algorithm.

Returns:

true if at least one entry has been removed.