Package org.springframework.web.servlet.i18n

# Class CookieLocaleResolver

java.lang.Object
org.springframework.web.servlet.i18n.AbstractLocaleResolver
org.springframework.web.servlet.i18n.AbstractLocaleContextResolver
org.springframework.web.servlet.i18n.CookieLocaleResolver

All Implemented Interfaces:
  `LocaleContextResolver`, `LocaleResolver`

public class CookieLocaleResolver extends AbstractLocaleContextResolver
`LocaleResolver` implementation that uses a cookie sent back to the user in case of a custom setting, with a fallback to the configured default locale, the request's `Accept-Language` header, or the default locale for the server.

This is particularly useful for stateless applications without user sessions. The cookie may optionally contain an associated time zone value as well; alternatively, you may specify a default time zone.

Custom controllers can override the user's locale and time zone by calling `#setLocale(Context)` on the resolver, for example, responding to a locale change request. As a more convenient alternative, consider using `RequestContext.changeLocale(java.util.Locale)`.

Since:
  27.02.2003
Author:
  Juergen Hoeller, Jean-Pierre Pawlak, Vedran Pavic, Sam Brannen
See Also:
  - `AbstractLocaleResolver.setDefaultLocale(java.util.Locale)`
  - `AbstractLocaleContextResolver.setDefaultTimeZone(java.util.TimeZone)`

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`DEFAULT_COOKIE_NAME`
The default cookie name used if none is explicitly set.
`static final String`
`LOCALE_REQUEST_ATTRIBUTE_NAME`
The name of the request attribute that holds the `Locale`.
`static final String`
`TIME_ZONE_REQUEST_ATTRIBUTE_NAME`
The name of the request attribute that holds the `TimeZone`.

## Constructor Summary

Constructors
Constructor
Description
`CookieLocaleResolver()`
Constructor with a default cookie name.
`CookieLocaleResolver(String cookieName)`
Constructor with a given cookie name.

## Method Summary

Modifier and Type
Method
Description
`protected Locale`
`determineDefaultLocale(HttpServletRequest request)`
Deprecated.
as of 6.0, in favor of `setDefaultLocaleFunction(Function)`
`protected TimeZone`
`determineDefaultTimeZone(HttpServletRequest request)`
Deprecated.
as of 6.0, in favor of `setDefaultTimeZoneFunction(Function)`
`boolean`
`isLanguageTagCompliant()`
Return whether this resolver's cookies should be compliant with BCP 47 language tags instead of Java's legacy locale specification format.
`boolean`
`isRejectInvalidCookies()`
Return whether to reject cookies with invalid content (for example, invalid format).
`protected Locale`
`parseLocaleValue(String localeValue)`
Parse the given locale value coming from an incoming cookie.
`Locale`
`resolveLocale(HttpServletRequest request)`
Default implementation of `LocaleResolver.resolveLocale(HttpServletRequest)` that delegates to `LocaleContextResolver.resolveLocaleContext(HttpServletRequest)`, falling back to `ServletRequest.getLocale()` if necessary.
`org.springframework.context.i18n.LocaleContext`
`resolveLocaleContext(HttpServletRequest request)`
Resolve the current locale context via the given request.
`void`
`setCookieDomain(String cookieDomain)`
Set the cookie "Domain" attribute.
`void`
`setCookieHttpOnly(boolean cookieHttpOnly)`
Add the "HttpOnly" attribute to the cookie.
`void`
`setCookieMaxAge(Integer cookieMaxAge)`
Deprecated.
as of 6.0 in favor of `setCookieMaxAge(Duration)`
`void`
`setCookieMaxAge(Duration cookieMaxAge)`
Set the cookie "Max-Age" attribute.
`void`
`setCookieName(String cookieName)`
Deprecated.
as of 6.0 in favor of `CookieLocaleResolver(String)`
`void`
`setCookiePath(String cookiePath)`
Set the cookie "Path" attribute.
`void`
`setCookieSameSite(String cookieSameSite)`
Add the "SameSite" attribute to the cookie.
`void`
`setCookieSecure(boolean cookieSecure)`
Add the "Secure" attribute to the cookie.
`void`
`setDefaultLocaleFunction(Function<HttpServletRequest,Locale> defaultLocaleFunction)`
Set the function used to determine the default locale for the given request, called if no locale cookie has been found.
`void`
`setDefaultTimeZoneFunction(Function<HttpServletRequest,TimeZone> defaultTimeZoneFunction)`
Set the function used to determine the default time zone for the given request, called if no locale cookie has been found.
`void`
`setLanguageTagCompliant(boolean languageTagCompliant)`
Specify whether this resolver's cookies should be compliant with BCP 47 language tags instead of Java's legacy locale specification format.
`void`
`setLocaleContext(HttpServletRequest request, HttpServletResponse response, org.springframework.context.i18n.LocaleContext localeContext)`
Set the current locale context to the given one, potentially including a locale with associated time zone information.
`void`
`setRejectInvalidCookies(boolean rejectInvalidCookies)`
Specify whether to reject cookies with invalid content (for example, invalid format).
`protected String`
`toLocaleValue(Locale locale)`
Render the given locale as a text value for inclusion in a cookie.

### Methods inherited from class org.springframework.web.servlet.i18n.AbstractLocaleContextResolver

`getDefaultTimeZone, setDefaultTimeZone`

### Methods inherited from class org.springframework.web.servlet.i18n.AbstractLocaleResolver

`getDefaultLocale, setDefaultLocale`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface org.springframework.web.servlet.LocaleContextResolver

`setLocale`

## Field Details

### LOCALE_REQUEST_ATTRIBUTE_NAME

public static final String LOCALE_REQUEST_ATTRIBUTE_NAME
The name of the request attribute that holds the `Locale`.

Only used for overriding a cookie value if the locale has been changed in the course of the current request!

Use `RequestContext(Utils).getLocale()` to retrieve the current locale in controllers or views.

See Also:
  - `RequestContext.getLocale()`
  - `RequestContextUtils.getLocale(jakarta.servlet.http.HttpServletRequest)`

### TIME_ZONE_REQUEST_ATTRIBUTE_NAME

public static final String TIME_ZONE_REQUEST_ATTRIBUTE_NAME
The name of the request attribute that holds the `TimeZone`.

Only used for overriding a cookie value if the locale has been changed in the course of the current request!

Use `RequestContext(Utils).getTimeZone()` to retrieve the current time zone in controllers or views.

See Also:
  - `RequestContext.getTimeZone()`
  - `RequestContextUtils.getTimeZone(jakarta.servlet.http.HttpServletRequest)`

### DEFAULT_COOKIE_NAME

public static final String DEFAULT_COOKIE_NAME
The default cookie name used if none is explicitly set.

## Constructor Details

### CookieLocaleResolver

public CookieLocaleResolver(String cookieName)
Constructor with a given cookie name.

Since:
  6.0

### CookieLocaleResolver

public CookieLocaleResolver()
Constructor with a default cookie name.

## Method Details

### setCookieName

@Deprecated public void setCookieName(String cookieName)
Deprecated.
as of 6.0 in favor of `CookieLocaleResolver(String)`
Set the name of cookie created by this resolver.

Parameters:
  `cookieName` - the cookie name

### setCookieMaxAge

public void setCookieMaxAge(Duration cookieMaxAge)
Set the cookie "Max-Age" attribute.

By default, this is set to -1 in which case the cookie persists until browser shutdown.

Since:
  6.0
See Also:
  - `ResponseCookie.ResponseCookieBuilder.maxAge(Duration)`

### setCookieMaxAge

@Deprecated public void setCookieMaxAge(@Nullable Integer cookieMaxAge)
Deprecated.
as of 6.0 in favor of `setCookieMaxAge(Duration)`
Variant of `setCookieMaxAge(Duration)` with a value in seconds.

### setCookiePath

public void setCookiePath(@Nullable String cookiePath)
Set the cookie "Path" attribute.

By default, this is set to `"/"`.

See Also:
  - `ResponseCookie.ResponseCookieBuilder.path(String)`

### setCookieDomain

public void setCookieDomain(@Nullable String cookieDomain)
Set the cookie "Domain" attribute.

See Also:
  - `ResponseCookie.ResponseCookieBuilder.domain(String)`

### setCookieSecure

public void setCookieSecure(boolean cookieSecure)
Add the "Secure" attribute to the cookie.

See Also:
  - `ResponseCookie.ResponseCookieBuilder.secure(boolean)`

### setCookieHttpOnly

public void setCookieHttpOnly(boolean cookieHttpOnly)
Add the "HttpOnly" attribute to the cookie.

See Also:
  - `ResponseCookie.ResponseCookieBuilder.httpOnly(boolean)`

### setCookieSameSite

public void setCookieSameSite(String cookieSameSite)
Add the "SameSite" attribute to the cookie.

By default, this is set to `"Lax"`.

Since:
  6.0
See Also:
  - `ResponseCookie.ResponseCookieBuilder.sameSite(String)`

### setLanguageTagCompliant

public void setLanguageTagCompliant(boolean languageTagCompliant)
Specify whether this resolver's cookies should be compliant with BCP 47 language tags instead of Java's legacy locale specification format.

The default is `true`, as of 5.1. Switch this to `false` for rendering Java's legacy locale specification format. For parsing, this resolver leniently accepts the legacy `Locale.toString()` format as well as BCP 47 language tags in any case.

Since:
  4.3
See Also:
  - `parseLocaleValue(String)`
  - `toLocaleValue(Locale)`
  - `Locale.forLanguageTag(String)`
  - `Locale.toLanguageTag()`

### isLanguageTagCompliant

public boolean isLanguageTagCompliant()
Return whether this resolver's cookies should be compliant with BCP 47 language tags instead of Java's legacy locale specification format.

Since:
  4.3

### setRejectInvalidCookies

public void setRejectInvalidCookies(boolean rejectInvalidCookies)
Specify whether to reject cookies with invalid content (for example, invalid format).

The default is `true`. Turn this off for lenient handling of parse failures, falling back to the default locale and time zone in such a case.

Since:
  5.1.7
See Also:
  - `AbstractLocaleResolver.setDefaultLocale(java.util.Locale)`
  - `AbstractLocaleContextResolver.setDefaultTimeZone(java.util.TimeZone)`
  - `setDefaultLocaleFunction(Function)`
  - `setDefaultTimeZoneFunction(Function)`

### isRejectInvalidCookies

public boolean isRejectInvalidCookies()
Return whether to reject cookies with invalid content (for example, invalid format).

Since:
  5.1.7

### setDefaultLocaleFunction

public void setDefaultLocaleFunction(Function<HttpServletRequest,Locale> defaultLocaleFunction)
Set the function used to determine the default locale for the given request, called if no locale cookie has been found.

The default implementation returns the configured default locale, if any, and otherwise falls back to the request's `Accept-Language` header locale or the default locale for the server.

Parameters:
  `defaultLocaleFunction` - the function used to determine the default locale
Since:
  6.0
See Also:
  - `AbstractLocaleResolver.setDefaultLocale(java.util.Locale)`
  - `ServletRequest.getLocale()`

### setDefaultTimeZoneFunction

public void setDefaultTimeZoneFunction(Function<HttpServletRequest,TimeZone> defaultTimeZoneFunction)
Set the function used to determine the default time zone for the given request, called if no locale cookie has been found.

The default implementation returns the configured default time zone, if any, or `null` otherwise.

Parameters:
  `defaultTimeZoneFunction` - the function used to determine the default time zone
Since:
  6.0
See Also:
  - `AbstractLocaleContextResolver.setDefaultTimeZone(java.util.TimeZone)`

### resolveLocale

public Locale resolveLocale(HttpServletRequest request)
Description copied from interface: `LocaleContextResolver`
Default implementation of `LocaleResolver.resolveLocale(HttpServletRequest)` that delegates to `LocaleContextResolver.resolveLocaleContext(HttpServletRequest)`, falling back to `ServletRequest.getLocale()` if necessary.

Parameters:
  `request` - the request to resolve the locale for
Returns:
  the current locale (never `null`)

### resolveLocaleContext

public org.springframework.context.i18n.LocaleContext resolveLocaleContext(HttpServletRequest request)
Description copied from interface: `LocaleContextResolver`
Resolve the current locale context via the given request.

This is primarily intended for framework-level processing; consider using `RequestContextUtils` or `RequestContext` for application-level access to the current locale and/or time zone.

The returned context may be a `TimeZoneAwareLocaleContext`, containing a locale with associated time zone information. Simply apply an `instanceof` check and downcast accordingly.

Custom resolver implementations may also return extra settings in the returned context, which again can be accessed through downcasting.

Parameters:
  `request` - the request to resolve the locale context for
Returns:
  the current locale context (never `null`
See Also:
  - `LocaleContextResolver.resolveLocale(HttpServletRequest)`
  - `RequestContextUtils.getLocale(jakarta.servlet.http.HttpServletRequest)`
  - `RequestContextUtils.getTimeZone(jakarta.servlet.http.HttpServletRequest)`

### setLocaleContext

public void setLocaleContext(HttpServletRequest request, @Nullable HttpServletResponse response, @Nullable org.springframework.context.i18n.LocaleContext localeContext)
Description copied from interface: `LocaleContextResolver`
Set the current locale context to the given one, potentially including a locale with associated time zone information.

Parameters:
  `request` - the request to be used for locale modification
  `response` - the response to be used for locale modification
  `localeContext` - the new locale context, or `null` to clear the locale
See Also:
  - `LocaleContextResolver.setLocale(HttpServletRequest, HttpServletResponse, Locale)`
  - `SimpleLocaleContext`
  - `SimpleTimeZoneAwareLocaleContext`

### parseLocaleValue

@Nullable protected Locale parseLocaleValue(String localeValue)
Parse the given locale value coming from an incoming cookie.

The default implementation calls `StringUtils.parseLocale(String)`, accepting the `Locale.toString()` format as well as BCP 47 language tags.

Parameters:
  `localeValue` - the locale value to parse
Returns:
  the corresponding `Locale` instance
Since:
  4.3
See Also:
  - `StringUtils.parseLocale(String)`

### toLocaleValue

protected String toLocaleValue(Locale locale)
Render the given locale as a text value for inclusion in a cookie.

The default implementation calls `Locale.toString()` or `Locale.toLanguageTag()`, depending on the `"languageTagCompliant"` configuration property.

Parameters:
  `locale` - the locale to convert to a string
Returns:
  a String representation for the given locale
Since:
  4.3
See Also:
  - `isLanguageTagCompliant()`

### determineDefaultLocale

@Deprecated(since="6.0") protected Locale determineDefaultLocale(HttpServletRequest request)
Deprecated.
as of 6.0, in favor of `setDefaultLocaleFunction(Function)`
Determine the default locale for the given request, called if no locale cookie has been found.

The default implementation returns the configured default locale, if any, and otherwise falls back to the request's `Accept-Language` header locale or the default locale for the server.

Parameters:
  `request` - the request to resolve the locale for
Returns:
  the default locale (never `null`)
See Also:
  - `AbstractLocaleResolver.setDefaultLocale(java.util.Locale)`
  - `ServletRequest.getLocale()`

### determineDefaultTimeZone

@Deprecated(since="6.0") @Nullable protected TimeZone determineDefaultTimeZone(HttpServletRequest request)
Deprecated.
as of 6.0, in favor of `setDefaultTimeZoneFunction(Function)`
Determine the default time zone for the given request, called if no locale cookie has been found.

The default implementation returns the configured default time zone, if any, or `null` otherwise.

Parameters:
  `request` - the request to resolve the time zone for
Returns:
  the default time zone (or `null` if none defined)
See Also:
  - `AbstractLocaleContextResolver.setDefaultTimeZone(java.util.TimeZone)`