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:
      the boolean value of the first value in insertion order or 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:
      the boolean value of the first value in insertion order or 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:
      the boolean value of the last value in insertion order or 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:
      the boolean value of the last value in insertion order or 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 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).
      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.