HttpHeaders (filter-service-metrics 1.13 1.13 API)

All Superinterfaces:: HttpObject

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 the HttpHeadersBuilder to build a new HttpHeaders 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 one

You can use toBuilder() or withMutations(Consumer) to build a new HttpHeaders 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 value

Certain 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 as Integer, MediaType and Instant (or Date) 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-friendly String representation:

Number, CharSequence and MediaType
- Converted via toString()
- e.g. "42", "string", "text/plain; charset=utf-8"
CacheControl
- Converted via asHeaderValue()
- e.g. "no-cache, no-store, must-revalidate"
Instant, TemporalAccessor, Date and Calendar
- 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()

Using `HttpHeaders.of()` factory methods


 HttpHeaders 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 and Description

static HttpHeaders EMPTY_HEADERS
Deprecated.
Use of().

Fields
Modifier and Type	Field and Description
`static HttpHeaders`	`EMPTY_HEADERS` Deprecated. Use `of()`.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`static HttpHeadersBuilder`	`builder()` Returns a new empty builder.
`boolean`	`contains(CharSequence name)` Returns `true` if a header with the `name` exists, `false` otherwise.
`boolean`	`contains(CharSequence name, String value)` Returns `true` if a header with the `name` and `value` exists.
`boolean`	`containsDouble(CharSequence name, double value)` Returns `true` if a header with the `name` and `value` exists.
`boolean`	`containsFloat(CharSequence name, float value)` Returns `true` if a header with the `name` and `value` exists.
`boolean`	`containsInt(CharSequence name, int value)` Returns `true` if a header with the `name` and `value` exists.
`boolean`	`containsLong(CharSequence name, long value)` Returns `true` if a header with the `name` and `value` exists.
`boolean`	`containsObject(CharSequence name, Object value)` Returns `true` if a header with the `name` and `value` exists.
`boolean`	`containsTimeMillis(CharSequence name, long value)` Returns `true` if a header with the `name` and `value` exists.
`MediaType`	`contentType()` Returns the parsed `"content-type"` header.
`void`	`forEach(BiConsumer<io.netty.util.AsciiString,String> action)` Invokes the specified `action` for all header entries.
`void`	`forEachValue(CharSequence name, Consumer<String> action)` Invokes the specified `action` for all values of the headers with the specified `name`.
`String`	`get(CharSequence name)` Returns the value of a header with the specified `name`.
`String`	`get(CharSequence name, String defaultValue)` Returns the value of a header with the specified `name`.
`List<String>`	`getAll(CharSequence name)` Returns all values for the header with the specified name.
`Double`	`getDouble(CharSequence name)` Returns the `double` value of a header with the specified `name`.
`double`	`getDouble(CharSequence name, double defaultValue)` Returns the `double` value of a header with the specified `name`.
`Float`	`getFloat(CharSequence name)` Returns the `float` value of a header with the specified `name`.
`float`	`getFloat(CharSequence name, float defaultValue)` Returns the `float` value of a header with the specified `name`.
`Integer`	`getInt(CharSequence name)` Returns the `int` value of a header with the specified `name`.
`int`	`getInt(CharSequence name, int defaultValue)` Returns the `int` value of a header with the specified `name`.
`Long`	`getLong(CharSequence name)` Returns the `long` value of a header with the specified `name`.
`long`	`getLong(CharSequence name, long defaultValue)` Returns the `long` value of a header with the specified `name`.
`Long`	`getTimeMillis(CharSequence name)` Returns the value of a header with the specified `name` in milliseconds.
`long`	`getTimeMillis(CharSequence name, long defaultValue)` Returns the value of a header with the specified `name` in milliseconds.
`boolean`	`isEmpty()` Returns `true` 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<io.netty.util.AsciiString,String>>`	`iterator()` Returns an `Iterator` that yields all header entries.
`Set<io.netty.util.AsciiString>`	`names()` Returns a `Set` of all header names.
`static HttpHeaders`	`of()` Returns an empty `HttpHeaders`.
`static HttpHeaders`	`of(CharSequence name, Object value)` Returns a new `HttpHeaders` with the specified header.
`static HttpHeaders`	`of(CharSequence name1, Object value1, CharSequence name2, Object value2)` Returns a new `HttpHeaders` with the specified headers.
`static HttpHeaders`	`of(CharSequence name1, Object value1, CharSequence name2, Object value2, CharSequence name3, Object value3)` Returns a new `HttpHeaders` 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 new `HttpHeaders` with the specified headers.
`static HttpHeaders`	`of(CharSequence name, String value)` Returns a new `HttpHeaders` with the specified header.
`static HttpHeaders`	`of(CharSequence name1, String value1, CharSequence name2, String value2)` Returns a new `HttpHeaders` with the specified headers.
`static HttpHeaders`	`of(CharSequence name1, String value1, CharSequence name2, String value2, CharSequence name3, String value3)` Returns a new `HttpHeaders` 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 new `HttpHeaders` with the specified headers.
`int`	`size()` Returns the number of headers.
`default Stream<Map.Entry<io.netty.util.AsciiString,String>>`	`stream()` Returns a `Stream` that yields all header entries.
`HttpHeadersBuilder`	`toBuilder()` Returns a new builder created from the entries of this headers.
`Iterator<String>`	`valueIterator(CharSequence name)` Returns an `Iterator` that yields all values of the headers with the specified `name`.
`default Stream<String>`	`valueStream(CharSequence name)` Returns a `Stream` that yields all values of the headers with the specified `name`.
`default HttpHeaders`	`withMutations(Consumer<HttpHeadersBuilder> mutator)` Returns a new headers which is the result from the mutation by the specified `Consumer`.

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. Use of().
    
    An empty HttpHeaders.
- Method Detail
  - builder
```
static HttpHeadersBuilder builder()
```
    Returns a new empty builder.
  - of
```
static HttpHeaders of()
```
    Returns an empty HttpHeaders.
  - of
```
static HttpHeaders of(CharSequence name,
                      String value)
```
    Returns a new HttpHeaders with the specified header.
  - of
```
static HttpHeaders of(CharSequence name,
                      Object value)
```
    Returns a new HttpHeaders with the specified header. The value is converted into a String as explained in Specifying a non-String header value.
  - of
```
static HttpHeaders of(CharSequence name1,
                      String value1,
                      CharSequence name2,
                      String value2)
```
    Returns a new HttpHeaders with the specified headers.
  - of
```
static HttpHeaders of(CharSequence name1,
                      Object value1,
                      CharSequence name2,
                      Object value2)
```
    Returns a new HttpHeaders with the specified headers. The values are converted into Strings 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 new HttpHeaders with the specified headers.
  - of
```
static HttpHeaders of(CharSequence name1,
                      Object value1,
                      CharSequence name2,
                      Object value2,
                      CharSequence name3,
                      Object value3)
```
    Returns a new HttpHeaders with the specified headers. The values are converted into Strings 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 new HttpHeaders 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 new HttpHeaders with the specified headers. The values are converted into Strings 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 specified Consumer. This method is a shortcut for:
```
 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
```
MediaType contentType()
```
    Returns the parsed "content-type" header.
    
    Returns:
    
    the parsed MediaType if present and valid, or null otherwise.
  - get
```
String get(CharSequence name)
```
    Returns the value of a header with the specified name. If there are 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, or null if there's no such header
  - get
```
String get(CharSequence name,
           String defaultValue)
```
    Returns the value of a header with the specified name. If there are 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
  - getAll
```
List<String> getAll(CharSequence name)
```
    Returns all values for the header with the specified name. The returned List can't be modified.
    
    Parameters:
    
    name - the name of the header to retrieve
    
    Returns:
    
    a List of header values or an empty List if there is no such header.
  - getInt
```
Integer getInt(CharSequence name)
```
    Returns the int value of a header with the specified name. If there are 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 int value of the first value in insertion order or null if there is no such header or it can't be converted to int.
  - getInt
```
int getInt(CharSequence name,
           int defaultValue)
```
    Returns the int value of a header with the specified name. If there are 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 int value of the first value in insertion order or defaultValue if there is no such header or it can't be converted to int.
  - getLong
```
Long getLong(CharSequence name)
```
    Returns the long value of a header with the specified name. If there are 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 long value of the first value in insertion order or null if there is no such header or it can't be converted to long.
  - getLong
```
long getLong(CharSequence name,
             long defaultValue)
```
    Returns the long value of a header with the specified name. If there are 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 long value of the first value in insertion order or defaultValue if there is no such header or it can't be converted to long.
  - getFloat
```
Float getFloat(CharSequence name)
```
    Returns the float value of a header with the specified name. If there are 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 float value of the first value in insertion order or null if there is no such header or it can't be converted to float.
  - getFloat
```
float getFloat(CharSequence name,
               float defaultValue)
```
    Returns the float value of a header with the specified name. If there are 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 float value of the first value in insertion order or defaultValue if there is no such header or it can't be converted to float.
  - getDouble
```
Double getDouble(CharSequence name)
```
    Returns the double value of a header with the specified name. If there are 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 double value of the first value in insertion order or null if there is no such header or it can't be converted to double.
  - getDouble
```
double getDouble(CharSequence name,
                 double defaultValue)
```
    Returns the double value of a header with the specified name. If there are 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 double value of the first value in insertion order or defaultValue if there is no such header or it can't be converted to double.
  - getTimeMillis
```
Long getTimeMillis(CharSequence name)
```
    Returns the value of a header with the specified name in milliseconds. If there are 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 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 specified name in milliseconds. If there are 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 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)
```
    Returns true if a header with the name exists, false otherwise.
    
    Parameters:
    
    name - the header name
  - contains
```
boolean contains(CharSequence name,
                 String value)
```
    Returns true if a header with the name and value exists.
    
    Parameters:
    
    name - the header name
    
    value - the header value of the header to find
  - containsObject
```
boolean containsObject(CharSequence name,
                       Object value)
```
    Returns true if a header with the name and value exists.
    
    Parameters:
    
    name - the header name
    
    value - the header value
    
    Returns:
    
    true if the header exists. false otherwise
  - containsInt
```
boolean containsInt(CharSequence name,
                    int value)
```
    Returns true if a header with the name and value exists.
    
    Parameters:
    
    name - the header name
    
    value - the header value
    
    Returns:
    
    true if the header exists. false otherwise
  - containsLong
```
boolean containsLong(CharSequence name,
                     long value)
```
    Returns true if a header with the name and value exists.
    
    Parameters:
    
    name - the header name
    
    value - the header value
    
    Returns:
    
    true if the header exists. false otherwise
  - containsFloat
```
boolean containsFloat(CharSequence name,
                      float value)
```
    Returns true if a header with the name and value exists.
    
    Parameters:
    
    name - the header name
    
    value - the header value
    
    Returns:
    
    true if the header exists. false otherwise
  - containsDouble
```
boolean containsDouble(CharSequence name,
                       double value)
```
    Returns true if a header with the name and value exists.
    
    Parameters:
    
    name - the header name
    
    value - the header value
    
    Returns:
    
    true if the header exists. false otherwise
  - containsTimeMillis
```
boolean containsTimeMillis(CharSequence name,
                           long value)
```
    Returns true if a header with the name and value exists.
    
    Parameters:
    
    name - the header name
    
    value - the header value
    
    Returns:
    
    true if the header exists. false otherwise
  - size
```
int size()
```
    Returns the number of headers.
  - isEmpty
```
boolean isEmpty()
```
    Returns true if this headers does not contain any entries.
  - names
```
Set<io.netty.util.AsciiString> names()
```
    Returns a Set of all header names. The returned Set cannot be modified.
  - iterator
```
Iterator<Map.Entry<io.netty.util.AsciiString,String>> iterator()
```
    Returns an Iterator that yields all header entries. The iteration order is as follows:
    1. All pseudo headers (order not specified).
    2. All non-pseudo headers (in insertion order).
  - valueIterator
```
Iterator<String> valueIterator(CharSequence name)
```
    Returns an Iterator that yields all values of the headers with the specified name.
  - forEach
```
void forEach(BiConsumer<io.netty.util.AsciiString,String> action)
```
    Invokes the specified action for all header entries.
  - forEachValue
```
void forEachValue(CharSequence name,
                  Consumer<String> action)
```
    Invokes the specified action for all values of the headers with the specified name.
  - stream
```
default Stream<Map.Entry<io.netty.util.AsciiString,String>> stream()
```
    Returns a Stream that yields all header entries.
  - valueStream
```
default Stream<String> valueStream(CharSequence name)
```
    Returns a Stream that yields all values of the headers with the specified name.

Interface HttpHeaders

Building a new HttpHeaders

Building a new HttpHeaders from an existing one

Specifying a non-String header value

Using HttpHeaders.of() factory methods

Using HttpHeadersBuilder

Specifying value type explicitly

Field Summary

Method Summary

Methods inherited from interface com.linecorp.armeria.common.HttpObject

Methods inherited from interface java.lang.Iterable

Field Detail

EMPTY_HEADERS

Method Detail

builder

of

of

of

of

of

of

of

of

of

toBuilder

withMutations

isEndOfStream

contentType

get

get

getAll

getInt

getInt

getLong

getLong

getFloat

getFloat

getDouble

getDouble

getTimeMillis

getTimeMillis

contains

contains

containsObject

containsInt

containsLong

containsFloat

containsDouble

containsTimeMillis

size

isEmpty

names

iterator

valueIterator

forEach

forEachValue

stream

valueStream

Building a new `HttpHeaders`

Building a new `HttpHeaders` from an existing one

Specifying a non-`String` header value

Using `HttpHeaders.of()` factory methods

Using `HttpHeadersBuilder`