Package org.springframework.http

Class HttpHeaders

java.lang.Object
org.springframework.http.HttpHeaders
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
WebSocketHttpHeaders
public class HttpHeaders extends Object implements Serializable
A data structure representing HTTP request or response headers, mapping String header names to a list of String values, also offering accessors for common application-level data types.

In addition to the regular methods defined by Map, this class offers many common convenience methods, for example:

Note that HttpHeaders instances created by the default constructor treat header names in a case-insensitive manner. Instances created with the HttpHeaders(MultiValueMap) constructor like those instantiated internally by the framework to adapt to existing HTTP headers data structures do guarantee per-header get/set/add operations to be case-insensitive as mandated by the HTTP specification. However, it is not necessarily how entries are actually stored, and this can lead to the reported size() being inflated. Prefer using headerSet() or headerNames() to ensure a case-insensitive view.

This class is meant to reference "well-known" headers supported by Spring Framework. If your application or library relies on other headers defined in RFCs, please use methods that accept the header name as a parameter.

Since 7.0, this class no longer implements the MultiValueMap contract.

Since:
3.0
Author:
Arjen Poutsma, Sebastien Deleuze, Brian Clozel, Juergen Hoeller, Josh Long, Sam Brannen, Simon Baslé
See Also:

  • Field Details

  • Constructor Details

    • HttpHeaders

      public HttpHeaders()
      Construct a new, empty instance of the HttpHeaders object using an underlying case-insensitive map.

    • HttpHeaders

      public HttpHeaders(MultiValueMap<String,String> headers)
      Construct a new HttpHeaders instance backed by an existing map.

      This constructor is available as an optimization for adapting to existing headers map structures, primarily for internal use within the framework.

      Parameters:
      headers - the headers map (expected to operate with case-insensitive keys)
      Since:
      5.1

    • HttpHeaders

      public HttpHeaders(HttpHeaders httpHeaders)
      Construct a new HttpHeaders instance by removing any read-only wrapper that may have been previously applied around the given HttpHeaders via readOnlyHttpHeaders(HttpHeaders).

      Once the writable instance is mutated, the read-only instance is likely to be out of sync and should be discarded.

      Parameters:
      httpHeaders - the headers to expose
      Since:
      7.0

  • Method Details

    • getOrEmpty

      public List<String> getOrEmpty(String headerName)
      Get the list of header values for the given header name, if any.
      Parameters:
      headerName - the header name
      Returns:
      the list of header values, or an empty list
      Since:
      7.0

    • getOrDefault

      public List<String> getOrDefault(String headerName, List<String> defaultValue)
      Get the list of header values for the given header name, or the given default list of values if the header is not present.
      Parameters:
      headerName - the header name
      defaultValue - the fallback list if header is not present
      Returns:
      the list of header values, or a default list of values
      Since:
      7.0

    • setAccept

      public void setAccept(List<MediaType> acceptableMediaTypes)
      Set the list of acceptable media types, as specified by the Accept header.

    • getAccept

      public List<MediaType> getAccept()
      Return the list of acceptable media types, as specified by the Accept header.

      Returns an empty list when the acceptable media types are unspecified.

    • setAcceptLanguage

      public void setAcceptLanguage(List<Locale.LanguageRange> languages)
      Set the acceptable language ranges, as specified by the Accept-Language header.
      Since:
      5.0

    • getAcceptLanguage

      public List<Locale.LanguageRange> getAcceptLanguage()
      Return the language ranges from the "Accept-Language" header.

      If you only need sorted, preferred locales only use getAcceptLanguageAsLocales() or if you need to filter based on a list of supported locales you can pass the returned list to Locale.filter(List, Collection).

      Throws:
      IllegalArgumentException - if the value cannot be converted to a language range
      Since:
      5.0

    • setAcceptLanguageAsLocales

      public void setAcceptLanguageAsLocales(List<Locale> locales)
      Variant of setAcceptLanguage(List) using Locale's.
      Since:
      5.0

    • getAcceptLanguageAsLocales

      public List<Locale> getAcceptLanguageAsLocales()
      A variant of getAcceptLanguage() that converts each Locale.LanguageRange to a Locale.
      Returns:
      the locales or an empty list
      Throws:
      IllegalArgumentException - if the value cannot be converted to a locale
      Since:
      5.0

    • setAcceptPatch

      public void setAcceptPatch(List<MediaType> mediaTypes)
      Set the list of acceptable media types for PATCH methods, as specified by the Accept-Patch header.
      Since:
      5.3.6

    • getAcceptPatch

      public List<MediaType> getAcceptPatch()
      Return the list of acceptable media types for PATCH methods, as specified by the Accept-Patch header.

      Returns an empty list when the acceptable media types are unspecified.

      Since:
      5.3.6

    • setAccessControlAllowCredentials

      public void setAccessControlAllowCredentials(boolean allowCredentials)
      Set the (new) value of the Access-Control-Allow-Credentials response header.

    • getAccessControlAllowCredentials

      public boolean getAccessControlAllowCredentials()
      Return the value of the Access-Control-Allow-Credentials response header.

    • setAccessControlAllowHeaders

      public void setAccessControlAllowHeaders(List<String> allowedHeaders)
      Set the (new) value of the Access-Control-Allow-Headers response header.

    • getAccessControlAllowHeaders

      public List<String> getAccessControlAllowHeaders()
      Return the value of the Access-Control-Allow-Headers response header.

    • setAccessControlAllowMethods

      public void setAccessControlAllowMethods(List<HttpMethod> allowedMethods)
      Set the (new) value of the Access-Control-Allow-Methods response header.

    • getAccessControlAllowMethods

      public List<HttpMethod> getAccessControlAllowMethods()
      Return the value of the Access-Control-Allow-Methods response header.

    • setAccessControlAllowOrigin

      public void setAccessControlAllowOrigin(@Nullable String allowedOrigin)
      Set the (new) value of the Access-Control-Allow-Origin response header.

    • getAccessControlAllowOrigin

      public @Nullable String getAccessControlAllowOrigin()
      Return the value of the Access-Control-Allow-Origin response header.

    • setAccessControlExposeHeaders

      public void setAccessControlExposeHeaders(List<String> exposedHeaders)
      Set the (new) value of the Access-Control-Expose-Headers response header.

    • getAccessControlExposeHeaders

      public List<String> getAccessControlExposeHeaders()
      Return the value of the Access-Control-Expose-Headers response header.

    • setAccessControlMaxAge

      public void setAccessControlMaxAge(Duration maxAge)
      Set the (new) value of the Access-Control-Max-Age response header.
      Since:
      5.2

    • setAccessControlMaxAge

      public void setAccessControlMaxAge(long maxAge)
      Set the (new) value of the Access-Control-Max-Age response header.

    • getAccessControlMaxAge

      public long getAccessControlMaxAge()
      Return the value of the Access-Control-Max-Age response header.

      Returns -1 when the max age is unknown.

    • setAccessControlRequestHeaders

      public void setAccessControlRequestHeaders(List<String> requestHeaders)
      Set the (new) value of the Access-Control-Request-Headers request header.

    • getAccessControlRequestHeaders

      public List<String> getAccessControlRequestHeaders()
      Return the value of the Access-Control-Request-Headers request header.

    • setAccessControlRequestMethod

      public void setAccessControlRequestMethod(@Nullable HttpMethod requestMethod)
      Set the (new) value of the Access-Control-Request-Method request header.

    • getAccessControlRequestMethod

      public @Nullable HttpMethod getAccessControlRequestMethod()
      Return the value of the Access-Control-Request-Method request header.

    • setAcceptCharset

      public void setAcceptCharset(List<Charset> acceptableCharsets)
      Set the list of acceptable charsets, as specified by the Accept-Charset header.

    • getAcceptCharset

      public List<Charset> getAcceptCharset()
      Return the list of acceptable charsets, as specified by the Accept-Charset header.

    • setAllow

      public void setAllow(Set<HttpMethod> allowedMethods)
      Set the set of allowed HTTP methods, as specified by the Allow header.

    • getAllow

      public Set<HttpMethod> getAllow()
      Return the set of allowed HTTP methods, as specified by the Allow header.

      Returns an empty set when the allowed methods are unspecified.

    • setBasicAuth

      public void setBasicAuth(String username, String password)
      Set the value of the Authorization header to Basic Authentication based on the given username and password.

      Note that this method only supports characters in the ISO-8859-1 character set.

      Parameters:
      username - the username
      password - the password
      Throws:
      IllegalArgumentException - if either user or password contain characters that cannot be encoded to ISO-8859-1
      Since:
      5.1
      See Also:

    • setBasicAuth

      public void setBasicAuth(String username, String password, @Nullable Charset charset)
      Set the value of the Authorization header to Basic Authentication based on the given username and password.
      Parameters:
      username - the username
      password - the password
      charset - the charset to use to convert the credentials into an octet sequence. Defaults to ISO-8859-1.
      Throws:
      IllegalArgumentException - if username or password contains characters that cannot be encoded to the given charset
      Since:
      5.1
      See Also:

    • setBasicAuth

      public void setBasicAuth(String encodedCredentials)
      Set the value of the Authorization header to Basic Authentication based on the given encoded credentials.

      Favor this method over setBasicAuth(String, String) and setBasicAuth(String, String, Charset) if you wish to cache the encoded credentials.

      Parameters:
      encodedCredentials - the encoded credentials
      Throws:
      IllegalArgumentException - if supplied credentials string is null or blank
      Since:
      5.2
      See Also:

    • setBearerAuth

      public void setBearerAuth(String token)
      Set the value of the Authorization header to the given Bearer token.
      Parameters:
      token - the Base64 encoded token
      Since:
      5.1
      See Also:

    • setCacheControl

      public void setCacheControl(CacheControl cacheControl)
      Set a configured CacheControl instance as the new value of the Cache-Control header.
      Since:
      5.0.5

    • setCacheControl

      public void setCacheControl(@Nullable String cacheControl)
      Set the (new) value of the Cache-Control header.

    • getCacheControl

      public @Nullable String getCacheControl()
      Return the value of the Cache-Control header.

    • setConnection

      public void setConnection(String connection)
      Set the (new) value of the Connection header.

    • setConnection

      public void setConnection(List<String> connection)
      Set the (new) value of the Connection header.

    • getConnection

      public List<String> getConnection()
      Return the value of the Connection header.

    • setContentDispositionFormData

      public void setContentDispositionFormData(String name, @Nullable String filename)
      Set the Content-Disposition header when creating a "multipart/form-data" request.

      Applications typically would not set this header directly but rather prepare a MultiValueMap<String, Object>, containing an Object or a Resource for each part, and then pass that to the RestTemplate or WebClient.

      Parameters:
      name - the control name
      filename - the filename (may be null)
      See Also:

    • setContentDisposition

      public void setContentDisposition(ContentDisposition contentDisposition)
      Set the Content-Disposition header.

      This could be used on a response to indicate if the content is expected to be displayed inline in the browser or as an attachment to be saved locally.

      It can also be used for a "multipart/form-data" request. For more details see notes on setContentDispositionFormData(java.lang.String, java.lang.String).

      Since:
      5.0
      See Also:

    • getContentDisposition

      public ContentDisposition getContentDisposition()
      Return a parsed representation of the Content-Disposition header.
      Since:
      5.0
      See Also:

    • setContentLanguage

      public void setContentLanguage(@Nullable Locale locale)
      Set the Locale of the content language, as specified by the Content-Language header.

      Use put(CONTENT_LANGUAGE, list) if you need to set multiple content languages.

      Since:
      5.0

    • getContentLanguage

      public @Nullable Locale getContentLanguage()
      Get the first Locale of the content languages, as specified by the Content-Language header.

      Use getValuesAsList(String) if you need to get multiple content languages.

      Returns:
      the first Locale of the content languages, or null if unknown
      Since:
      5.0

    • setContentLength

      public void setContentLength(long contentLength)
      Set the length of the body in bytes, as specified by the Content-Length header.
      Parameters:
      contentLength - content length (greater than or equal to zero)
      Throws:
      IllegalArgumentException - if the content length is negative

    • getContentLength

      public long getContentLength()
      Return the length of the body in bytes, as specified by the Content-Length header.

      Returns -1 when the content-length is unknown.

    • setContentType

      public void setContentType(@Nullable MediaType mediaType)
      Set the media type of the body, as specified by the Content-Type header.

    • getContentType

      public @Nullable MediaType getContentType()
      Return the media type of the body, as specified by the Content-Type header.

      Returns null when the Content-Type header is not set.

      Throws:
      InvalidMediaTypeException - if the media type value cannot be parsed

    • setDate

      public void setDate(ZonedDateTime date)
      Set the date and time at which the message was created, as specified by the Date header.
      Since:
      5.2

    • setDate

      public void setDate(Instant date)
      Set the date and time at which the message was created, as specified by the Date header.
      Since:
      5.2

    • setDate

      public void setDate(long date)
      Set the date and time at which the message was created, as specified by the Date header.

      The date should be specified as the number of milliseconds since January 1, 1970 GMT.

    • getDate

      public long getDate()
      Return the date and time at which the message was created, as specified by the Date header.

      The date is returned as the number of milliseconds since January 1, 1970 GMT. Returns -1 when the date is unknown.

      Throws:
      IllegalArgumentException - if the value cannot be converted to a date

    • setETag

      public void setETag(@Nullable String tag)
      Set the (new) entity tag of the body, as specified by the ETag header.

    • getETag

      public @Nullable String getETag()
      Return the entity tag of the body, as specified by the ETag header.

    • setExpires

      public void setExpires(ZonedDateTime expires)
      Set the duration after which the message is no longer valid, as specified by the Expires header.
      Since:
      5.0.5

    • setExpires

      public void setExpires(Instant expires)
      Set the date and time at which the message is no longer valid, as specified by the Expires header.
      Since:
      5.2

    • setExpires

      public void setExpires(long expires)
      Set the date and time at which the message is no longer valid, as specified by the Expires header.

      The date should be specified as the number of milliseconds since January 1, 1970 GMT.

    • getExpires

      public long getExpires()
      Return the date and time at which the message is no longer valid, as specified by the Expires header.

      The date is returned as the number of milliseconds since January 1, 1970 GMT. Returns -1 when the date is unknown.

      See Also:

    • setHost

      public void setHost(@Nullable InetSocketAddress host)
      Set the (new) value of the Host header.

      If the given port is 0, the host header will only contain the host name.

      Since:
      5.0

    • getHost

      public @Nullable InetSocketAddress getHost()
      Return the value of the Host header, if available.

      If the header value does not contain a port, the port in the returned address will be 0.

      Since:
      5.0

    • setIfMatch

      public void setIfMatch(String ifMatch)
      Set the (new) value of the If-Match header.
      Since:
      4.3

    • setIfMatch

      public void setIfMatch(List<String> ifMatchList)
      Set the (new) value of the If-Match header.
      Since:
      4.3

    • getIfMatch

      public List<String> getIfMatch()
      Return the value of the If-Match header.
      Throws:
      IllegalArgumentException - if parsing fails
      Since:
      4.3

    • setIfModifiedSince

      public void setIfModifiedSince(ZonedDateTime ifModifiedSince)
      Set the time the resource was last changed, as specified by the Last-Modified header.
      Since:
      5.1.4

    • setIfModifiedSince

      public void setIfModifiedSince(Instant ifModifiedSince)
      Set the time the resource was last changed, as specified by the Last-Modified header.
      Since:
      5.1.4

    • setIfModifiedSince

      public void setIfModifiedSince(long ifModifiedSince)
      Set the (new) value of the If-Modified-Since header.

      The date should be specified as the number of milliseconds since January 1, 1970 GMT.

    • getIfModifiedSince

      public long getIfModifiedSince()
      Return the value of the If-Modified-Since header.

      The date is returned as the number of milliseconds since January 1, 1970 GMT. Returns -1 when the date is unknown.

      See Also:

    • setIfNoneMatch

      public void setIfNoneMatch(String ifNoneMatch)
      Set the (new) value of the If-None-Match header.

    • setIfNoneMatch

      public void setIfNoneMatch(List<String> ifNoneMatchList)
      Set the (new) values of the If-None-Match header.

    • getIfNoneMatch

      public List<String> getIfNoneMatch()
      Return the value of the If-None-Match header.
      Throws:
      IllegalArgumentException - if parsing fails

    • setIfUnmodifiedSince

      public void setIfUnmodifiedSince(ZonedDateTime ifUnmodifiedSince)
      Set the time the resource was last changed, as specified by the Last-Modified header.
      Since:
      5.1.4

    • setIfUnmodifiedSince

      public void setIfUnmodifiedSince(Instant ifUnmodifiedSince)
      Set the time the resource was last changed, as specified by the Last-Modified header.
      Since:
      5.1.4

    • setIfUnmodifiedSince

      public void setIfUnmodifiedSince(long ifUnmodifiedSince)
      Set the (new) value of the If-Unmodified-Since header.

      The date should be specified as the number of milliseconds since January 1, 1970 GMT.

      Since:
      4.3

    • getIfUnmodifiedSince

      public long getIfUnmodifiedSince()
      Return the value of the If-Unmodified-Since header.

      The date is returned as the number of milliseconds since January 1, 1970 GMT. Returns -1 when the date is unknown.

      Since:
      4.3
      See Also:

    • setLastModified

      public void setLastModified(ZonedDateTime lastModified)
      Set the time the resource was last changed, as specified by the Last-Modified header.
      Since:
      5.1.4

    • setLastModified

      public void setLastModified(Instant lastModified)
      Set the time the resource was last changed, as specified by the Last-Modified header.
      Since:
      5.1.4

    • setLastModified

      public void setLastModified(long lastModified)
      Set the time the resource was last changed, as specified by the Last-Modified header.

      The date should be specified as the number of milliseconds since January 1, 1970 GMT.

    • getLastModified

      public long getLastModified()
      Return the time the resource was last changed, as specified by the Last-Modified header.

      The date is returned as the number of milliseconds since January 1, 1970 GMT. Returns -1 when the date is unknown.

      See Also:

    • setLocation

      public void setLocation(@Nullable URI location)
      Set the (new) location of a resource, as specified by the Location header.

    • getLocation

      public @Nullable URI getLocation()
      Return the (new) location of a resource as specified by the Location header.

      Returns null when the location is unknown.

    • setOrigin

      public void setOrigin(@Nullable String origin)
      Set the (new) value of the Origin header.

    • getOrigin

      public @Nullable String getOrigin()
      Return the value of the Origin header.

    • setPragma

      public void setPragma(@Nullable String pragma)
      Set the (new) value of the Pragma header.

    • getPragma

      public @Nullable String getPragma()
      Return the value of the Pragma header.

    • setRange

      public void setRange(List<HttpRange> ranges)
      Sets the (new) value of the Range header.

    • getRange

      public List<HttpRange> getRange()
      Return the value of the Range header.

      Returns an empty list when the range is unknown.

    • setUpgrade

      public void setUpgrade(@Nullable String upgrade)
      Set the (new) value of the Upgrade header.

    • getUpgrade

      public @Nullable String getUpgrade()
      Return the value of the Upgrade header.

    • setVary

      public void setVary(List<String> requestHeaders)
      Set the request header names (for example, "Accept-Language") for which the response is subject to content negotiation and variances based on the value of those request headers.
      Parameters:
      requestHeaders - the request header names
      Since:
      4.3

    • getVary

      public List<String> getVary()
      Return the request header names subject to content negotiation.
      Since:
      4.3

    • setZonedDateTime

      public void setZonedDateTime(String headerName, ZonedDateTime date)
      Set the given date under the given header name after formatting it as a string using the RFC-1123 date-time formatter. The equivalent of set(String, String) but for date headers.
      Since:
      5.0

    • setInstant

      public void setInstant(String headerName, Instant date)
      Set the given date under the given header name after formatting it as a string using the RFC-1123 date-time formatter. The equivalent of set(String, String) but for date headers.
      Since:
      5.1.4

    • setDate

      public void setDate(String headerName, long date)
      Set the given date under the given header name after formatting it as a string using the RFC-1123 date-time formatter. The equivalent of set(String, String) but for date headers.
      Since:
      3.2.4
      See Also:

    • getFirstDate

      public long getFirstDate(String headerName)
      Parse the first header value for the given header name as a date, return -1 if there is no value, or raise IllegalArgumentException if the value cannot be parsed as a date.
      Parameters:
      headerName - the header name
      Returns:
      the parsed date header, or -1 if none
      Since:
      3.2.4
      See Also:

    • getFirstZonedDateTime

      public @Nullable ZonedDateTime getFirstZonedDateTime(String headerName)
      Parse the first header value for the given header name as a date, return null if there is no value, or raise IllegalArgumentException if the value cannot be parsed as a date.
      Parameters:
      headerName - the header name
      Returns:
      the parsed date header, or null if none
      Since:
      5.0

    • getValuesAsList

      public List<String> getValuesAsList(String headerName)
      Return all values of a given header name, even if this header is set multiple times.

      This method supports double-quoted values, as described in RFC 9110, section 5.5.

      Parameters:
      headerName - the header name
      Returns:
      all associated values
      Since:
      4.3

    • clearContentHeaders

      public void clearContentHeaders()
      Remove the well-known "Content-*" HTTP headers.

      Such headers should be cleared from the response if the intended body can't be written due to errors.

      Since:
      5.2.3

    • getETagValuesAsList

      protected List<String> getETagValuesAsList(String name)
      Retrieve a combined result from the field values of the ETag header.
      Parameters:
      name - the header name
      Returns:
      the combined result
      Throws:
      IllegalArgumentException - if parsing fails
      Since:
      4.3

    • getFieldValues

      protected @Nullable String getFieldValues(String headerName)
      Retrieve a combined result from the field values of multivalued headers.
      Parameters:
      headerName - the header name
      Returns:
      the combined result
      Since:
      4.3

    • toCommaDelimitedString

      protected String toCommaDelimitedString(List<String> headerValues)
      Turn the given list of header values into a comma-delimited result.
      Parameters:
      headerValues - the list of header values
      Returns:
      a combined result with comma delimitation

    • getFirst

      public @Nullable String getFirst(String headerName)
      Return the first header value for the given header name, if any.
      Parameters:
      headerName - the header name
      Returns:
      the first header value, or null if none

    • add

      public void add(String headerName, @Nullable String headerValue)
      Add the given, single header value under the given name.
      Parameters:
      headerName - the header name
      headerValue - the header value
      Throws:
      UnsupportedOperationException - if adding headers is not supported
      See Also:

    • addAll

      public void addAll(String headerName, List<? extends String> headerValues)
      Add all the given values under the given name.

      As values are represented as a List, duplicate values can be introduced. See put(String, List) to replace the list of values instead.

      Parameters:
      headerName - the header name
      headerValues - the values to add
      See Also:

    • addAll

      public void addAll(HttpHeaders headers)
      Add all the values of the given HttpHeaders to the current header.

      As values are represented as a List, duplicate values can be introduced. See putAll(HttpHeaders) to replace the list of values of each individual header name instead.

      Parameters:
      headers - the headers to add
      Since:
      7.0
      See Also:

    • set

      public void set(String headerName, @Nullable String headerValue)
      Set the given, single header value under the given name.
      Parameters:
      headerName - the header name
      headerValue - the header value
      Throws:
      UnsupportedOperationException - if adding headers is not supported
      See Also:

    • setAll

      public void setAll(Map<String,String> values)
      Set all single header value from the given Map under each of their corresponding name.
      Parameters:
      values - the name-single-value pairs
      See Also:

    • toSingleValueMap

      public Map<String,String> toSingleValueMap()
      Return this HttpHeaders as a Map with the first values for each header name.

      The difference between this method and asSingleValueMap() is that this method returns a copy of the headers, whereas the latter returns a view. This copy also ensures that collection-iterating methods like entrySet() are case-insensitive.

      Returns:
      a single value representation of these headers

    • asSingleValueMap

      @Deprecated(since="7.0", forRemoval=true) public Map<String,String> asSingleValueMap()
      Deprecated, for removal: This API element is subject to removal in a future version.
      in favor of toSingleValueMap() which performs a copy but ensures that collection-iterating methods like entrySet() are case-insensitive
      Return this HttpHeaders as a Map with the first values for each header name.

      The difference between this method and toSingleValueMap() is that this method returns a view of the headers, whereas the latter returns a copy. This method is also susceptible to include multiple casing variants of a given header name, see asMultiValueMap() javadoc.

      Returns:
      a single value representation of these headers

    • asMultiValueMap

      @Deprecated(since="7.0", forRemoval=true) public MultiValueMap<String,String> asMultiValueMap()
      Deprecated, for removal: This API element is subject to removal in a future version.
      This method is provided for backward compatibility with APIs that would only accept maps. Generally avoid using HttpHeaders as a Map or MultiValueMap.
      Return this HttpHeaders as a MultiValueMap with the full list of values for each header name.

      Note that some backing server headers implementations can store header names in a case-sensitive manner, which will lead to duplicates during iteration in methods like entrySet(), where multiple occurrences of a header name can surface depending on letter casing but each such entry has the full List of values.

      Returns:
      a MultiValueMap representation of these headers
      Since:
      7.0

    • isEmpty

      public boolean isEmpty()
      Returns true if this HttpHeaders contains no header entry.

    • containsHeader

      public boolean containsHeader(String headerName)
      Returns true if this HttpHeaders contains an entry for the given header name.
      Parameters:
      headerName - the header name
      Since:
      7.0

    • hasHeaderValues

      public boolean hasHeaderValues(String headerName, List<String> values)
      Returns true if this HttpHeaders contains exactly the given list of values for the given header name.
      Parameters:
      headerName - the header name
      values - the expected list of values
      Since:
      7.0

    • containsHeaderValue

      public boolean containsHeaderValue(String headerName, String value)
      Returns true if this HttpHeaders contains the given header and its list of values contains the given value.
      Parameters:
      headerName - the header name
      value - the value expected to be in the list of values
      Since:
      7.0

    • get

      public @Nullable List<String> get(String headerName)
      Get the list of values associated with the given header name, or null.

      To ensure support for double-quoted values, see also getValuesAsList(String).

      Parameters:
      headerName - the header name
      Since:
      7.0
      See Also:

    • put

      public @Nullable List<String> put(String headerName, List<String> headerValues)
      Set the list of values associated with the given header name. Returns the previous list of values, or null if the header was not present.
      Parameters:
      headerName - the header name
      headerValues - the new values
      Returns:
      the old values for the given header name

    • putIfAbsent

      public @Nullable List<String> putIfAbsent(String headerName, List<String> headerValues)
      Set header values for the given header name if that header name isn't already present in this HttpHeaders and return null. If the header is already present, returns the associated value list instead.
      Parameters:
      headerName - the header name
      headerValues - the header values to set if header is not present
      Returns:
      the previous value or null

    • putAll

      public void putAll(HttpHeaders headers)
      Put all the entries from the given HttpHeaders into this HttpHeaders.
      Parameters:
      headers - the given headers
      Since:
      7.0
      See Also:

    • putAll

      public void putAll(Map<? extends String,? extends List<String>> headers)
      Put all the entries from the given MultiValueMap into this HttpHeaders.
      Parameters:
      headers - the given headers
      See Also:

    • remove

      public @Nullable List<String> remove(String key)
      Remove a header from this HttpHeaders instance, and return the associated value list or null if that header wasn't present.
      Parameters:
      key - the name of the header to remove
      Returns:
      the value list associated with the removed header name
      Since:
      7.0

    • clear

      public void clear()
      Remove all headers from this HttpHeaders instance.

    • size

      public int size()
      Return the number of headers in the collection. This can be inflated, see class level javadoc.

    • forEach

      public void forEach(BiConsumer<? super String,? super List<String>> action)
      Perform an action over each header, as when iterated via headerSet().
      Parameters:
      action - the action to be performed for each entry

    • headerSet

      public Set<Map.Entry<String,List<String>>> headerSet()
      Return a view of the headers as an entry Set of key-list pairs. Both Iterator.remove() and Map.Entry.setValue(V) are supported and mutate the headers.

      This collection is guaranteed to contain one entry per header name even if the backing structure stores multiple casing variants of names, at the cost of first copying the names into a case-insensitive set for filtering the iteration.

      Returns:
      a Set view that iterates over all headers in a case-insensitive manner
      Since:
      6.1.15

    • headerNames

      public Set<String> headerNames()
      Return the set of header names. Both Set.remove(Object) and Set.clear() operations are supported and mutate the headers.

      This collection is guaranteed to contain only one casing variant of each header name even if the backing structure stores multiple casing variants of names. The first encountered variant is the one that is retained.

      Returns:
      a Set of all the headers names
      Since:
      7.0

    • equals

      public boolean equals(@Nullable Object other)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • readOnlyHttpHeaders

      public static HttpHeaders readOnlyHttpHeaders(MultiValueMap<String,String> headers)
      Apply a read-only HttpHeaders wrapper around the given headers, if necessary.

      Also caches the parsed representations of the "Accept" and "Content-Type" headers.

      Parameters:
      headers - the headers to expose
      Returns:
      a read-only variant of the headers, or the original headers as-is (in case it happens to be a read-only HttpHeaders instance already)
      Since:
      5.3

    • readOnlyHttpHeaders

      public static HttpHeaders readOnlyHttpHeaders(HttpHeaders headers)
      Apply a read-only HttpHeaders wrapper around the given headers, if necessary.

      Also caches the parsed representations of the "Accept" and "Content-Type" headers.

      Parameters:
      headers - the headers to expose
      Returns:
      a read-only variant of the headers, or the original headers as-is if already read-only

    • formatHeaders

      public static String formatHeaders(MultiValueMap<String,String> headers)
      Helps to format HTTP header values, as HTTP header values themselves can contain comma-separated values, can become confusing with regular Map formatting that also uses commas between entries.

      Additionally, this method displays the native list of header names with the mention with native header names if the underlying implementation stores multiple casing variants of header names (see class level javadoc).

      Parameters:
      headers - the headers to format
      Returns:
      the headers to a String
      Since:
      5.1.4

    • encodeBasicAuth

      public static String encodeBasicAuth(String username, String password, @Nullable Charset charset)
      Encode the given username and password into Basic Authentication credentials.

      The encoded credentials returned by this method can be supplied to setBasicAuth(String) to set the Basic Authentication header.

      Parameters:
      username - the username
      password - the password
      charset - the charset to use to convert the credentials into an octet sequence. Defaults to ISO-8859-1.
      Throws:
      IllegalArgumentException - if username or password contains characters that cannot be encoded to the given charset
      Since:
      5.2
      See Also: