Package com.linecorp.armeria.common
Interface HttpHeaders
-
- All Superinterfaces:
HttpObject
,Iterable<Map.Entry<AsciiString,String>>
- All Known Subinterfaces:
RequestHeaders
,ResponseHeaders
public interface HttpHeaders extends HttpObject
Immutable HTTP/2 headers.Building a new
HttpHeaders
You can use the
HttpHeaders.of()
factory methods or theHttpHeadersBuilder
to build a newHttpHeaders
from scratch:// Using of() HttpHeaders headersWithOf = HttpHeaders.of(HttpHeaderNames.CONTENT_TYPE, "text/plain; charset=utf-8", HttpHeaderNames.CONTENT_LENGTH, "42"); // Using builder() HttpHeaders headersWithBuilder = HttpHeaders.builder() .add(HttpHeaderNames.CONTENT_TYPE, "text/plain; charset=utf-8") .add(HttpHeaderNames.CONTENT_LENGTH, "42") .build(); assert headersWithOf.equals(headersWithBuilder);
Building a new
HttpHeaders
from an existing oneYou can use
toBuilder()
orwithMutations(Consumer)
to build a newHttpHeaders
derived from an existing one:HttpHeaders headers = HttpHeaders.of("name1", "value0") // Using toBuilder() HttpHeaders headersWithToBuilder = headers.toBuilder() .set("name1", "value1") .add("name2", "value2") .build(); // Using withMutations() HttpHeaders headersWithMutations = headers.withMutations(builder -> { builder.set("name1", "value1"); builder.add("name2", "value2"); }); assert headersWithToBuilder.equals(headersWithMutations); // Note that the original headers remain unmodified. assert !headers.equals(headersWithToBuilder); assert !headers.equals(headersWithMutations);
Specifying a non-
String
header valueCertain header values are better represented as a Java object than as a
String
. For example, it is more convenient to specify"content-length"
,"content-type"
and"date"
header asInteger
,MediaType
andInstant
(orDate
) respectively. Armeria's HTTP header API allows you to specify a Java object of well-known type as a header value by converting it into an HTTP-friendlyString
representation:Number
,CharSequence
andMediaType
- Converted via
toString()
- e.g.
"42"
,"string"
,"text/plain; charset=utf-8"
- Converted via
CacheControl
- Converted via
asHeaderValue()
- e.g.
"no-cache, no-store, must-revalidate"
- Converted via
Instant
,TemporalAccessor
,Date
andCalendar
- Converted into a time and date string as specified in RFC1123
- e.g.
Sun, 27 Nov 2016 19:37:15 UTC
- All other types
- Converted via
toString()
- Converted via
Using
HttpHeaders.of()
factory methodsHttpHeaders headers = HttpHeaders.of(HttpHeaderNames.CONTENT_LENGTH, 42, HttpHeaderNames.CONTENT_TYPE, MediaType.JSON_UTF_8, HttpHeaderNames.DATE, Instant.now());
Using
HttpHeadersBuilder
HttpHeaders headers = HttpHeaders.builder() .setObject(HttpHeaderNames.CONTENT_LENGTH, 42) .setObject(HttpHeaderNames.CONTENT_TYPE, MediaType.JSON_UTF_8) .setObject(HttpHeaderNames.DATE, Instant.now()) .build();
Specifying value type explicitly
You might prefer type-safe setters for more efficiency and less ambiguity:
HttpHeaders headers = HttpHeaders.builder() .setInt(HttpHeaderNames.CONTENT_LENGTH, 42) .set(HttpHeaderNames.CONTENT_TYPE, MediaType.JSON_UTF_8.toString()) .setTimeMillis(HttpHeaderNames.DATE, System.currentTimeMillis()) .build();
- See Also:
RequestHeaders
,ResponseHeaders
-
-
Field Summary
Fields Modifier and Type Field Description static HttpHeaders
EMPTY_HEADERS
Deprecated.Useof()
.
-
Method Summary
Modifier and Type Method Description static HttpHeadersBuilder
builder()
Returns a new empty builder.boolean
contains(CharSequence name)
Returnstrue
if a header with thename
exists,false
otherwise.boolean
contains(CharSequence name, String value)
Returnstrue
if a header with thename
andvalue
exists.boolean
containsDouble(CharSequence name, double value)
Returnstrue
if a header with thename
andvalue
exists.boolean
containsFloat(CharSequence name, float value)
Returnstrue
if a header with thename
andvalue
exists.boolean
containsInt(CharSequence name, int value)
Returnstrue
if a header with thename
andvalue
exists.boolean
containsLong(CharSequence name, long value)
Returnstrue
if a header with thename
andvalue
exists.boolean
containsObject(CharSequence name, Object value)
Returnstrue
if a header with thename
andvalue
exists.boolean
containsTimeMillis(CharSequence name, long value)
Returnstrue
if a header with thename
andvalue
exists.MediaType
contentType()
Returns the parsed"content-type"
header.void
forEach(BiConsumer<AsciiString,String> action)
Invokes the specifiedaction
for all header entries.void
forEachValue(CharSequence name, Consumer<String> action)
Invokes the specifiedaction
for all values of the headers with the specifiedname
.String
get(CharSequence name)
Returns the value of a header with the specifiedname
.String
get(CharSequence name, String defaultValue)
Returns the value of a header with the specifiedname
.List<String>
getAll(CharSequence name)
Returns all values for the header with the specified name.Double
getDouble(CharSequence name)
Returns thedouble
value of a header with the specifiedname
.double
getDouble(CharSequence name, double defaultValue)
Returns thedouble
value of a header with the specifiedname
.Float
getFloat(CharSequence name)
Returns thefloat
value of a header with the specifiedname
.float
getFloat(CharSequence name, float defaultValue)
Returns thefloat
value of a header with the specifiedname
.Integer
getInt(CharSequence name)
Returns theint
value of a header with the specifiedname
.int
getInt(CharSequence name, int defaultValue)
Returns theint
value of a header with the specifiedname
.Long
getLong(CharSequence name)
Returns thelong
value of a header with the specifiedname
.long
getLong(CharSequence name, long defaultValue)
Returns thelong
value of a header with the specifiedname
.Long
getTimeMillis(CharSequence name)
Returns the value of a header with the specifiedname
in milliseconds.long
getTimeMillis(CharSequence name, long defaultValue)
Returns the value of a header with the specifiedname
in milliseconds.boolean
isEmpty()
Returnstrue
if this headers does not contain any entries.boolean
isEndOfStream()
Tells whether the headers correspond to the last frame in an HTTP/2 stream.Iterator<Map.Entry<AsciiString,String>>
iterator()
Returns anIterator
that yields all header entries.Set<AsciiString>
names()
Returns aSet
of all header names.static HttpHeaders
of()
Returns an emptyHttpHeaders
.static HttpHeaders
of(CharSequence name, Object value)
Returns a newHttpHeaders
with the specified header.static HttpHeaders
of(CharSequence name1, Object value1, CharSequence name2, Object value2)
Returns a newHttpHeaders
with the specified headers.static HttpHeaders
of(CharSequence name1, Object value1, CharSequence name2, Object value2, CharSequence name3, Object value3)
Returns a newHttpHeaders
with the specified headers.static HttpHeaders
of(CharSequence name1, Object value1, CharSequence name2, Object value2, CharSequence name3, Object value3, CharSequence name4, Object value4)
Returns a newHttpHeaders
with the specified headers.static HttpHeaders
of(CharSequence name, String value)
Returns a newHttpHeaders
with the specified header.static HttpHeaders
of(CharSequence name1, String value1, CharSequence name2, String value2)
Returns a newHttpHeaders
with the specified headers.static HttpHeaders
of(CharSequence name1, String value1, CharSequence name2, String value2, CharSequence name3, String value3)
Returns a newHttpHeaders
with the specified headers.static HttpHeaders
of(CharSequence name1, String value1, CharSequence name2, String value2, CharSequence name3, String value3, CharSequence name4, String value4)
Returns a newHttpHeaders
with the specified headers.int
size()
Returns the number of headers.default Stream<Map.Entry<AsciiString,String>>
stream()
Returns aStream
that yields all header entries.HttpHeadersBuilder
toBuilder()
Returns a new builder created from the entries of this headers.Iterator<String>
valueIterator(CharSequence name)
Returns anIterator
that yields all values of the headers with the specifiedname
.default Stream<String>
valueStream(CharSequence name)
Returns aStream
that yields all values of the headers with the specifiedname
.default HttpHeaders
withMutations(Consumer<HttpHeadersBuilder> mutator)
Returns a new headers which is the result from the mutation by the specifiedConsumer
.-
Methods inherited from interface com.linecorp.armeria.common.HttpObject
isEndOfStream
-
Methods inherited from interface java.lang.Iterable
forEach, spliterator
-
-
-
-
Field Detail
-
EMPTY_HEADERS
@Deprecated static final HttpHeaders EMPTY_HEADERS
Deprecated.Useof()
.An emptyHttpHeaders
.
-
-
Method Detail
-
builder
static HttpHeadersBuilder builder()
Returns a new empty builder.
-
of
static HttpHeaders of()
Returns an emptyHttpHeaders
.
-
of
static HttpHeaders of(CharSequence name, String value)
Returns a newHttpHeaders
with the specified header.
-
of
static HttpHeaders of(CharSequence name, Object value)
Returns a newHttpHeaders
with the specified header. The value is converted into aString
as explained in Specifying a non-String header value.
-
of
static HttpHeaders of(CharSequence name1, String value1, CharSequence name2, String value2)
Returns a newHttpHeaders
with the specified headers.
-
of
static HttpHeaders of(CharSequence name1, Object value1, CharSequence name2, Object value2)
Returns a newHttpHeaders
with the specified headers. The values are converted intoString
s as explained in Specifying a non-String header value.
-
of
static HttpHeaders of(CharSequence name1, String value1, CharSequence name2, String value2, CharSequence name3, String value3)
Returns a newHttpHeaders
with the specified headers.
-
of
static HttpHeaders of(CharSequence name1, Object value1, CharSequence name2, Object value2, CharSequence name3, Object value3)
Returns a newHttpHeaders
with the specified headers. The values are converted intoString
s as explained in Specifying a non-String header value.
-
of
static HttpHeaders of(CharSequence name1, String value1, CharSequence name2, String value2, CharSequence name3, String value3, CharSequence name4, String value4)
Returns a newHttpHeaders
with the specified headers.
-
of
static HttpHeaders of(CharSequence name1, Object value1, CharSequence name2, Object value2, CharSequence name3, Object value3, CharSequence name4, Object value4)
Returns a newHttpHeaders
with the specified headers. The values are converted intoString
s as explained in Specifying a non-String header value.
-
toBuilder
HttpHeadersBuilder toBuilder()
Returns a new builder created from the entries of this headers.- See Also:
withMutations(Consumer)
-
withMutations
default HttpHeaders withMutations(Consumer<HttpHeadersBuilder> mutator)
Returns a new headers which is the result from the mutation by the specifiedConsumer
. This method is a shortcut of:builder = toBuilder(); mutator.accept(builder); return builder.build();
- See Also:
toBuilder()
-
isEndOfStream
boolean isEndOfStream()
Tells whether the headers correspond to the last frame in an HTTP/2 stream.
-
contentType
@Nullable MediaType contentType()
Returns the parsed"content-type"
header.- Returns:
- the parsed
MediaType
if present and valid.null
otherwise.
-
get
@Nullable String get(CharSequence name)
Returns the value of a header with the specifiedname
. If there are more than one value for the specifiedname
, 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
String get(CharSequence name, String defaultValue)
Returns the value of a header with the specifiedname
. If there are more than one value for the specifiedname
, the first value in insertion order is returned.- Parameters:
name
- the name of the header to retrievedefaultValue
- the default value- Returns:
- the first header value or
defaultValue
if there is no such header
-
getAll
List<String> getAll(CharSequence name)
Returns all values for the header with the specified name. The returnedList
can't be modified.
-
getInt
@Nullable Integer getInt(CharSequence name)
Returns theint
value of a header with the specifiedname
. If there are more than one value for the specifiedname
, the first value in insertion order is returned.- Parameters:
name
- the name of the header to retrieve- Returns:
- the
int
value of the first value in insertion order ornull
if there is no such header or it can't be converted toint
.
-
getInt
int getInt(CharSequence name, int defaultValue)
Returns theint
value of a header with the specifiedname
. If there are more than one value for the specifiedname
, the first value in insertion order is returned.- Parameters:
name
- the name of the header to retrievedefaultValue
- the default value- Returns:
- the
int
value of the first value in insertion order ordefaultValue
if there is no such header or it can't be converted toint
.
-
getLong
@Nullable Long getLong(CharSequence name)
Returns thelong
value of a header with the specifiedname
. If there are more than one value for the specifiedname
, the first value in insertion order is returned.- Parameters:
name
- the name of the header to retrieve- Returns:
- the
long
value of the first value in insertion order ornull
if there is no such header or it can't be converted tolong
.
-
getLong
long getLong(CharSequence name, long defaultValue)
Returns thelong
value of a header with the specifiedname
. If there are more than one value for the specifiedname
, the first value in insertion order is returned.- Parameters:
name
- the name of the header to retrievedefaultValue
- the default value- Returns:
- the
long
value of the first value in insertion order ordefaultValue
if there is no such header or it can't be converted tolong
.
-
getFloat
@Nullable Float getFloat(CharSequence name)
Returns thefloat
value of a header with the specifiedname
. If there are more than one value for the specifiedname
, the first value in insertion order is returned.- Parameters:
name
- the name of the header to retrieve- Returns:
- the
float
value of the first value in insertion order ornull
if there is no such header or it can't be converted tofloat
.
-
getFloat
float getFloat(CharSequence name, float defaultValue)
Returns thefloat
value of a header with the specifiedname
. If there are more than one value for the specifiedname
, the first value in insertion order is returned.- Parameters:
name
- the name of the header to retrievedefaultValue
- the default value- Returns:
- the
float
value of the first value in insertion order ordefaultValue
if there is no such header or it can't be converted tofloat
.
-
getDouble
@Nullable Double getDouble(CharSequence name)
Returns thedouble
value of a header with the specifiedname
. If there are more than one value for the specifiedname
, the first value in insertion order is returned.- Parameters:
name
- the name of the header to retrieve- Returns:
- the
double
value of the first value in insertion order ornull
if there is no such header or it can't be converted todouble
.
-
getDouble
double getDouble(CharSequence name, double defaultValue)
Returns thedouble
value of a header with the specifiedname
. If there are more than one value for the specifiedname
, the first value in insertion order is returned.- Parameters:
name
- the name of the header to retrievedefaultValue
- the default value- Returns:
- the
double
value of the first value in insertion order ordefaultValue
if there is no such header or it can't be converted todouble
.
-
getTimeMillis
@Nullable Long getTimeMillis(CharSequence name)
Returns the value of a header with the specifiedname
in milliseconds. If there are more than one value for the specifiedname
, the first value in insertion order is returned.- Parameters:
name
- the name of the header to retrieve- Returns:
- the milliseconds value of the first value in insertion order or
null
if there is no such header or it can't be converted to milliseconds.
-
getTimeMillis
long getTimeMillis(CharSequence name, long defaultValue)
Returns the value of a header with the specifiedname
in milliseconds. If there are more than one value for the specifiedname
, the first value in insertion order is returned.- Parameters:
name
- the name of the header to retrievedefaultValue
- the default value- Returns:
- the milliseconds value of the first value in insertion order or
defaultValue
if there is no such header or it can't be converted to milliseconds.
-
contains
boolean contains(CharSequence name)
Returnstrue
if a header with thename
exists,false
otherwise.- Parameters:
name
- the header name
-
contains
boolean contains(CharSequence name, String value)
Returnstrue
if a header with thename
andvalue
exists.- Parameters:
name
- the header namevalue
- the header value of the header to find
-
containsObject
boolean containsObject(CharSequence name, Object value)
Returnstrue
if a header with thename
andvalue
exists.- Parameters:
name
- the header namevalue
- the header value- Returns:
true
if the header exists.false
otherwise
-
containsInt
boolean containsInt(CharSequence name, int value)
Returnstrue
if a header with thename
andvalue
exists.- Parameters:
name
- the header namevalue
- the header value- Returns:
true
if the header exists.false
otherwise
-
containsLong
boolean containsLong(CharSequence name, long value)
Returnstrue
if a header with thename
andvalue
exists.- Parameters:
name
- the header namevalue
- the header value- Returns:
true
if the header exists.false
otherwise
-
containsFloat
boolean containsFloat(CharSequence name, float value)
Returnstrue
if a header with thename
andvalue
exists.- Parameters:
name
- the header namevalue
- the header value- Returns:
true
if the header exists.false
otherwise
-
containsDouble
boolean containsDouble(CharSequence name, double value)
Returnstrue
if a header with thename
andvalue
exists.- Parameters:
name
- the header namevalue
- the header value- Returns:
true
if the header exists.false
otherwise
-
containsTimeMillis
boolean containsTimeMillis(CharSequence name, long value)
Returnstrue
if a header with thename
andvalue
exists.- Parameters:
name
- the header namevalue
- the header value- Returns:
true
if the header exists.false
otherwise
-
size
int size()
Returns the number of headers.
-
isEmpty
boolean isEmpty()
Returnstrue
if this headers does not contain any entries.
-
names
Set<AsciiString> names()
-
iterator
Iterator<Map.Entry<AsciiString,String>> iterator()
Returns anIterator
that yields all header entries. The iteration order is as follows:- All pseudo headers (order not specified).
- All non-pseudo headers (in insertion order).
- Specified by:
iterator
in interfaceIterable<Map.Entry<AsciiString,String>>
-
valueIterator
Iterator<String> valueIterator(CharSequence name)
Returns anIterator
that yields all values of the headers with the specifiedname
.
-
forEach
void forEach(BiConsumer<AsciiString,String> action)
Invokes the specifiedaction
for all header entries.
-
forEachValue
void forEachValue(CharSequence name, Consumer<String> action)
Invokes the specifiedaction
for all values of the headers with the specifiedname
.
-
stream
default Stream<Map.Entry<AsciiString,String>> stream()
Returns aStream
that yields all header entries.
-
valueStream
default Stream<String> valueStream(CharSequence name)
Returns aStream
that yields all values of the headers with the specifiedname
.
-
-