Module jakarta.ws.rs

Package jakarta.ws.rs.core

Interface HttpHeaders

public interface HttpHeaders

An injectable interface that provides access to HTTP header information. All methods throw IllegalStateException if called outside the scope of a request (e.g. from a provider constructor).

Since:

1.0

Author:

Paul Sandoz, Marc Hadley

See Also:

• Context

Field Summary

Fields

Modifier and Type	Field	Description
static final String	ACCEPT	See HTTP/1.1 documentation.
static final String	ACCEPT_CHARSET	See HTTP/1.1 documentation.
static final String	ACCEPT_ENCODING	See HTTP/1.1 documentation.
static final String	ACCEPT_LANGUAGE	See HTTP/1.1 documentation.
static final String	ALLOW	See HTTP/1.1 documentation.
static final String	AUTHORIZATION	See HTTP/1.1 documentation.
static final String	CACHE_CONTROL	See HTTP/1.1 documentation.
static final String	CONTENT_DISPOSITION	See IETF RFC-2183.
static final String	CONTENT_ENCODING	See HTTP/1.1 documentation.
static final String	CONTENT_ID	See IETF RFC-2392.
static final String	CONTENT_LANGUAGE	See HTTP/1.1 documentation.
static final String	CONTENT_LENGTH	See HTTP/1.1 documentation.
static final String	CONTENT_LOCATION	See HTTP/1.1 documentation.
static final String	CONTENT_TYPE	See HTTP/1.1 documentation.
static final String	COOKIE	See IETF RFC 2109.
static final String	DATE	See HTTP/1.1 documentation.
static final String	ETAG	See HTTP/1.1 documentation.
static final String	EXPECT	See HTTP/1.1 documentation.
static final String	EXPIRES	See HTTP/1.1 documentation.
static final String	HOST	See HTTP/1.1 documentation.
static final String	IF_MATCH	See HTTP/1.1 documentation.
static final String	IF_MODIFIED_SINCE	See HTTP/1.1 documentation.
static final String	IF_NONE_MATCH	See HTTP/1.1 documentation.
static final String	IF_UNMODIFIED_SINCE	See HTTP/1.1 documentation.
static final String	LAST_EVENT_ID_HEADER	"Last-Event-ID" HTTP request header name as defined by SSE specification.
static final String	LAST_MODIFIED	See HTTP/1.1 documentation.
static final String	LINK	See Web Linking (IETF RFC-5988) documentation.
static final String	LOCATION	See HTTP/1.1 documentation.
static final String	RETRY_AFTER	See HTTP/1.1 documentation.
static final String	SET_COOKIE	See IETF RFC 2109.
static final String	USER_AGENT	See HTTP/1.1 documentation.
static final String	VARY	See HTTP/1.1 documentation.
static final String	WWW_AUTHENTICATE	See HTTP/1.1 documentation.

Method Summary

Modifier and Type	Method	Description
boolean	containsHeaderString(String name, String valueSeparatorRegex, Predicate<String> valuePredicate)	Checks whether a header with a specific name and value (or item of the token-separated value list) exists.
default boolean	containsHeaderString(String name, Predicate<String> valuePredicate)	Checks whether a header with a specific name and value (or item of the comma-separated value list) exists.
List<Locale>	getAcceptableLanguages()	Get a list of languages that are acceptable for the response.
List<MediaType>	getAcceptableMediaTypes()	Get a list of media types that are acceptable for the response.
Map<String,Cookie>	getCookies()	Get any cookies that accompanied the request.
Date	getDate()	Get message date.
String	getHeaderString(String name)	Get a HTTP header as a single string value.
Locale	getLanguage()	Get the language of the request entity.
int	getLength()	Get Content-Length value.
MediaType	getMediaType()	Get the media type of the request entity.
List<String>	getRequestHeader(String name)	Get the values of a HTTP request header if the header exists on the current request.
MultivaluedMap<String,String>	getRequestHeaders()	Get the values of HTTP request headers.

Field Details

ACCEPT

static final String ACCEPT

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

ACCEPT_CHARSET

static final String ACCEPT_CHARSET

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

ACCEPT_ENCODING

static final String ACCEPT_ENCODING

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

ACCEPT_LANGUAGE

static final String ACCEPT_LANGUAGE

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

ALLOW

static final String ALLOW

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

AUTHORIZATION

static final String AUTHORIZATION

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

CACHE_CONTROL

static final String CACHE_CONTROL

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

CONTENT_DISPOSITION

static final String CONTENT_DISPOSITION

See IETF RFC-2183.

See Also:

• Constant Field Values

CONTENT_ENCODING

static final String CONTENT_ENCODING

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

CONTENT_ID

static final String CONTENT_ID

See IETF RFC-2392.

See Also:

• Constant Field Values

CONTENT_LANGUAGE

static final String CONTENT_LANGUAGE

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

CONTENT_LENGTH

static final String CONTENT_LENGTH

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

CONTENT_LOCATION

static final String CONTENT_LOCATION

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

CONTENT_TYPE

static final String CONTENT_TYPE

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

DATE

static final String DATE

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

ETAG

static final String ETAG

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

EXPECT

static final String EXPECT

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

EXPIRES

static final String EXPIRES

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

HOST

static final String HOST

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

IF_MATCH

static final String IF_MATCH

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

IF_MODIFIED_SINCE

static final String IF_MODIFIED_SINCE

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

IF_NONE_MATCH

static final String IF_NONE_MATCH

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

IF_UNMODIFIED_SINCE

static final String IF_UNMODIFIED_SINCE

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

LAST_MODIFIED

static final String LAST_MODIFIED

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

LOCATION

static final String LOCATION

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

LINK

static final String LINK

See Web Linking (IETF RFC-5988) documentation.

See Also:

• Constant Field Values

RETRY_AFTER

static final String RETRY_AFTER

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

USER_AGENT

static final String USER_AGENT

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

VARY

static final String VARY

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

WWW_AUTHENTICATE

static final String WWW_AUTHENTICATE

See HTTP/1.1 documentation.

See Also:

• Constant Field Values

COOKIE

static final String COOKIE

See IETF RFC 2109.

See Also:

• Constant Field Values

SET_COOKIE

static final String SET_COOKIE

See IETF RFC 2109.

See Also:

• Constant Field Values

LAST_EVENT_ID_HEADER

static final String LAST_EVENT_ID_HEADER

"Last-Event-ID" HTTP request header name as defined by SSE specification.

Since:

2.1

See Also:

• Constant Field Values

Method Details

getRequestHeader

List<String> getRequestHeader(String name)

Get the values of a HTTP request header if the header exists on the current request. The returned value will be a read-only List if the specified header exists or null if it does not. This is a shortcut for getRequestHeaders().get(name).

Parameters:

name - the header name, case insensitive.

Returns:

a read-only list of header values if the specified header exists, otherwise null.

Throws:

IllegalStateException - if called outside the scope of a request.

getHeaderString

String getHeaderString(String name)

Get a HTTP header as a single string value.

Each single non-string header value is converted to String using a RuntimeDelegate.HeaderDelegate if one is available via RuntimeDelegate.createHeaderDelegate(java.lang.Class) for the header value class or using its toString method if a header delegate is not available.

Parameters:

name - the HTTP header.

Returns:

the HTTP header value. If the HTTP header is not present then null is returned. If the HTTP header is present but has no value then the empty string is returned. If the HTTP header is present more than once then the values of joined together and separated by a ',' character.

Since:

2.0

See Also:

• getRequestHeader(java.lang.String)

containsHeaderString

boolean containsHeaderString(String name,
 String valueSeparatorRegex,
 Predicate<String> valuePredicate)

Checks whether a header with a specific name and value (or item of the token-separated value list) exists. Each single non-string header value is converted to String using a RuntimeDelegate.HeaderDelegate if one is available via RuntimeDelegate.createHeaderDelegate(java.lang.Class) for the header value class or using its toString method if a header delegate is not available.

For example: containsHeaderString("cache-control", ",", "no-store"::equalsIgnoreCase) will return true if a Cache-Control header exists that has the value no-store, the value No-Store or the value Max-Age, NO-STORE, no-transform, but false when it has the value no-store;no-transform (missing comma), or the value no - store (whitespace within value).

Parameters:

name - the message header.

valueSeparatorRegex - Regular expression that separates the header value into single values. null does not split.

valuePredicate - value must fulfil this predicate.

Returns:

true if and only if a header with the given name exists, having either a whitespace-trimmed value matching the predicate, or having at least one whitespace-trimmed single value in a token-separated list of single values.

Since:

4.0

See Also:

• getRequestHeaders()
• getHeaderString(String)

containsHeaderString

default boolean containsHeaderString(String name,
 Predicate<String> valuePredicate)

Checks whether a header with a specific name and value (or item of the comma-separated value list) exists. Each single non-string header value is converted to String using a RuntimeDelegate.HeaderDelegate if one is available via RuntimeDelegate.createHeaderDelegate(java.lang.Class) for the header value class or using its toString method if a header delegate is not available.

For example: containsHeaderString("cache-control", "no-store"::equalsIgnoreCase) will return true if a Cache-Control header exists that has the value no-store, the value No-Store or the value Max-Age, NO-STORE, no-transform, but false when it has the value no-store;no-transform (missing comma), or the value no - store (whitespace within value).

Parameters:

name - the message header.

valuePredicate - value must fulfil this predicate.

Returns:

true if and only if a header with the given name exists, having either a whitespace-trimmed value matching the predicate, or having at least one whitespace-trimmed single value in a comma-separated list of single values.

Since:

4.0

See Also:

• getRequestHeaders()
• getHeaderString(String)

getRequestHeaders

MultivaluedMap<String,String> getRequestHeaders()

Get the values of HTTP request headers. The returned Map is case-insensitive wrt. keys and is read-only. The method never returns null.

Returns:

a read-only map of header names and values.

Throws:

IllegalStateException - if called outside the scope of a request.

getAcceptableMediaTypes

List<MediaType> getAcceptableMediaTypes()

Get a list of media types that are acceptable for the response.

If no acceptable media types are specified, a read-only list containing a single wildcard media type instance is returned.

Returns:

a read-only list of requested response media types sorted according to their q-value, with highest preference first.

Throws:

IllegalStateException - if called outside the scope of a request.

getAcceptableLanguages

List<Locale> getAcceptableLanguages()

Get a list of languages that are acceptable for the response.

If no acceptable languages are specified, a read-only list containing a single wildcard Locale instance (with language field set to "*") is returned.

Returns:

a read-only list of acceptable languages sorted according to their q-value, with highest preference first.

Throws:

IllegalStateException - if called outside the scope of a request.

getMediaType

MediaType getMediaType()

Get the media type of the request entity.

Returns:

the media type or null if there is no request entity.

Throws:

IllegalStateException - if called outside the scope of a request.

getLanguage

Locale getLanguage()

Get the language of the request entity.

Returns:

the language of the entity or null if not specified.

Throws:

IllegalStateException - if called outside the scope of a request.

getCookies

Map<String,Cookie> getCookies()

Get any cookies that accompanied the request.

Returns:

a read-only map of cookie name (String) to Cookie.

Throws:

IllegalStateException - if called outside the scope of a request

getDate

Date getDate()

Get message date.

Returns:

the message date, otherwise null if not present.

Since:

2.0

getLength

int getLength()

Get Content-Length value.

Returns:

Content-Length as integer if present and valid number. In other cases returns -1.

Since:

2.0