Package com.linecorp.armeria.common

Interface HttpHeaders

All Superinterfaces:
HttpObject, Iterable<Map.Entry<io.netty.util.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 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:

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:

  • Method Details

    • 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

      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:

    • isEndOfStream

      boolean isEndOfStream()
      Tells whether the headers correspond to the last frame in an HTTP/2 stream.

    • contentLength

      long contentLength()
      Returns the value of the content-length header, or -1 if this value is not known.

    • isContentLengthUnknown

      @UnstableApi boolean isContentLengthUnknown()
      Returns whether the content length is unknown. If true, content-length header is not automatically updated.

    • contentType

      @Nullable @Nullable MediaType contentType()
      Returns the parsed "content-type" header.
      Returns:
      the parsed MediaType if present and valid, or null otherwise.

    • contentDisposition

      @Nullable @Nullable ContentDisposition contentDisposition()
      Returns the parsed "content-disposition" header.
      Returns:
      the parsed MediaType if present and valid. null if not present or failed to parse "content-disposition" header.

    • get

      @Nullable @Nullable 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

    • getLast

      @Nullable @Nullable String getLast(CharSequence name)
      Returns the value of a header with the specified name. If there are more than one value for the specified name, the last value in insertion order is returned.
      Parameters:
      name - the name of the header to retrieve
      Returns:
      the last header value if the header is found, or null if there's no such header

    • getLast

      String getLast(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 last value in insertion order is returned.
      Parameters:
      name - the name of the header to retrieve
      defaultValue - the default value
      Returns:
      the last 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.

    • getBoolean

      @Nullable @Nullable Boolean getBoolean(CharSequence name)
      Returns the boolean 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:
      true if the first value in insertion order is one of "true", "TRUE", "1". false if the first value in insertion order is one of "false", "FALSE", "0". null if there is no such header or it can't be converted to boolean.

    • getBoolean

      boolean getBoolean(CharSequence name, boolean defaultValue)
      Returns the boolean 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:
      true if the first value in insertion order is one of "true", "TRUE", "1". false if the first value in insertion order is one of "false", "FALSE", "0". defaultValue if there is no such header or it can't be converted to boolean.

    • getLastBoolean

      @Nullable @Nullable Boolean getLastBoolean(CharSequence name)
      Returns the boolean value of a header with the specified name. If there are more than one value for the specified name, the last value in insertion order is returned.
      Parameters:
      name - the name of the header to retrieve
      Returns:
      true if the last value in insertion order is one of "true", "TRUE", "1". false if the last value in insertion order is one of "false", "FALSE", "0". null if there is no such header or it can't be converted to boolean.

    • getLastBoolean

      boolean getLastBoolean(CharSequence name, boolean defaultValue)
      Returns the boolean value of a header with the specified name. If there are more than one value for the specified name, the last value in insertion order is returned.
      Parameters:
      name - the name of the header to retrieve
      defaultValue - the default value
      Returns:
      true if the last value in insertion order is one of "true", "TRUE", "1". false if the last value in insertion order is one of "false", "FALSE", "0". defaultValue if there is no such header or it can't be converted to boolean.

    • getLastInt

      @Nullable @Nullable Integer getLastInt(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 last value in insertion order is returned.
      Parameters:
      name - the name of the header to retrieve
      Returns:
      the int value of the last value in insertion order or null if there is no such header or it can't be converted to int.

    • getLastInt

      int getLastInt(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 last 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 last value in insertion order or defaultValue if there is no such header or it can't be converted to int.

    • getInt

      @Nullable @Nullable 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

      @Nullable @Nullable 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.

    • getLastLong

      @Nullable @Nullable Long getLastLong(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 last value in insertion order is returned.
      Parameters:
      name - the name of the header to retrieve
      Returns:
      the long value of the last value in insertion order or null if there is no such header or it can't be converted to long.

    • getLastLong

      long getLastLong(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 last 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 last value in insertion order or defaultValue if there is no such header or it can't be converted to long.

    • getFloat

      @Nullable @Nullable 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.

    • getLastFloat

      @Nullable @Nullable Float getLastFloat(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 last value in insertion order is returned.
      Parameters:
      name - the name of the header to retrieve
      Returns:
      the float value of the last value in insertion order or null if there is no such header or it can't be converted to float.

    • getLastFloat

      float getLastFloat(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 last 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 last value in insertion order or defaultValue if there is no such header or it can't be converted to float.

    • getDouble

      @Nullable @Nullable 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.

    • getLastDouble

      @Nullable @Nullable Double getLastDouble(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 last value in insertion order is returned.
      Parameters:
      name - the name of the header to retrieve
      Returns:
      the double value of the last value in insertion order or null if there is no such header or it can't be converted to double.

    • getLastDouble

      double getLastDouble(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 last 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 last value in insertion order or defaultValue if there is no such header or it can't be converted to double.

    • getTimeMillis

      @Nullable @Nullable 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.

    • getLastTimeMillis

      @Nullable @Nullable Long getLastTimeMillis(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 last value in insertion order is returned.
      Parameters:
      name - the name of the header to retrieve
      Returns:
      the milliseconds value of the last value in insertion order or null if there is no such header or it can't be converted to milliseconds.

    • getLastTimeMillis

      long getLastTimeMillis(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 last 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 last 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

    • containsBoolean

      boolean containsBoolean(CharSequence name, boolean 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 with the name exist and value is true and header contains value that one of "true", "TRUE", "1" or value is false and header contains value that one of "false", "FALSE", "0". 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).
      Specified by:
      iterator in interface Iterable<Map.Entry<io.netty.util.AsciiString,String>>

    • 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.