Polish LocaleResolver support

Author: sbrannen

spring-context/src/main/java/org/springframework/context/i18n/SimpleLocaleContext.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -37,9 +37,9 @@ public class SimpleLocaleContext implements LocaleContext {
 
 
 	/**
-	 * Create a new SimpleLocaleContext that exposes the specified Locale.
-	 * Every {@link #getLocale()} call will return this Locale.
-	 * @param locale the Locale to expose, or {@code null} for no specific one
+	 * Create a new {@code SimpleLocaleContext} that exposes the specified {@link Locale}.
+	 * <p>Every {@link #getLocale()} call will return this locale.
+	 * @param locale the {@code Locale} to expose, or {@code null} for no specific one
 	 */
 	public SimpleLocaleContext(@Nullable Locale locale) {
 		this.locale = locale;

spring-webmvc/src/main/java/org/springframework/web/servlet/LocaleContextResolver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -25,7 +25,7 @@
 import org.springframework.lang.Nullable;
 
 /**
- * Extension of {@link LocaleResolver}, adding support for a rich locale context
+ * Extension of {@link LocaleResolver} that adds support for a rich locale context
  * (potentially including locale and time zone information).
  *
  * @author Juergen Hoeller

spring-webmvc/src/main/java/org/springframework/web/servlet/LocaleResolver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -55,7 +55,7 @@ public interface LocaleResolver {
 
 	/**
 	 * Resolve the current locale via the given request.
-	 * Can return a default locale as fallback in any case.
+	 * <p>Can return a default locale as fallback in any case.
 	 * @param request the request to resolve the locale for
 	 * @return the current locale (never {@code null})
 	 */

spring-webmvc/src/main/java/org/springframework/web/servlet/i18n/AbstractLocaleContextResolver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -28,7 +28,9 @@
 
 /**
  * Abstract base class for {@link LocaleContextResolver} implementations.
- * Provides support for a default locale and a default time zone.
+ *
+ * <p>Provides support for a {@linkplain #setDefaultLocale(Locale) default locale}
+ * and a {@linkplain #setDefaultTimeZone(TimeZone) default time zone}.
  *
  * <p>Also provides pre-implemented versions of {@link #resolveLocale} and {@link #setLocale},
  * delegating to {@link #resolveLocaleContext} and {@link #setLocaleContext}.
@@ -45,14 +47,16 @@ public abstract class AbstractLocaleContextResolver extends AbstractLocaleResolv
 
 
 	/**
-	 * Set a default TimeZone that this resolver will return if no other time zone found.
+	 * Set a default {@link TimeZone} that this resolver will return if no other
+	 * time zone is found.
 	 */
 	public void setDefaultTimeZone(@Nullable TimeZone defaultTimeZone) {
 		this.defaultTimeZone = defaultTimeZone;
 	}
 
 	/**
-	 * Return the default TimeZone that this resolver is supposed to fall back to, if any.
+	 * Get the default {@link TimeZone} that this resolver is supposed to fall
+	 * back to, if any.
 	 */
 	@Nullable
 	public TimeZone getDefaultTimeZone() {

spring-webmvc/src/main/java/org/springframework/web/servlet/i18n/AbstractLocaleResolver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,7 +23,8 @@
 
 /**
  * Abstract base class for {@link LocaleResolver} implementations.
- * Provides support for a default locale.
+ *
+ * <p>Provides support for a {@linkplain #setDefaultLocale(Locale) default locale}.
  *
  * @author Juergen Hoeller
  * @since 1.2.9
@@ -36,14 +37,16 @@ public abstract class AbstractLocaleResolver implements LocaleResolver {
 
 
 	/**
-	 * Set a default Locale that this resolver will return if no other locale found.
+	 * Set a default {@link Locale} that this resolver will return if no other
+	 * locale is found.
 	 */
 	public void setDefaultLocale(@Nullable Locale defaultLocale) {
 		this.defaultLocale = defaultLocale;
 	}
 
 	/**
-	 * Return the default Locale that this resolver is supposed to fall back to, if any.
+	 * Get the default {@link Locale} that this resolver is supposed to fall back
+	 * to, if any.
 	 */
 	@Nullable
 	protected Locale getDefaultLocale() {

spring-webmvc/src/main/java/org/springframework/web/servlet/i18n/AcceptHeaderLocaleResolver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -30,11 +30,11 @@
 
 /**
  * {@link LocaleResolver} implementation that simply uses the primary locale
- * specified in the "accept-language" header of the HTTP request (that is,
+ * specified in the {@code Accept-Language} header of the HTTP request (that is,
  * the locale sent by the client browser, normally that of the client's OS).
  *
- * <p>Note: Does not support {@code setLocale}, since the accept header
- * can only be changed through changing the client's locale settings.
+ * <p>Note: Does not support {@link #setLocale} since the {@code Accept-Language}
+ * header can only be changed by changing the client's locale settings.
  *
  * @author Juergen Hoeller
  * @author Rossen Stoyanchev
@@ -62,7 +62,7 @@ public void setSupportedLocales(List<Locale> locales) {
 	}
 
 	/**
-	 * Return the configured list of supported locales.
+	 * Get the configured list of supported locales.
 	 * @since 4.3
 	 */
 	public List<Locale> getSupportedLocales() {
@@ -140,7 +140,7 @@ else if (languageMatch == null) {
 	@Override
 	public void setLocale(HttpServletRequest request, @Nullable HttpServletResponse response, @Nullable Locale locale) {
 		throw new UnsupportedOperationException(
-				"Cannot change HTTP accept header - use a different locale resolution strategy");
+				"Cannot change HTTP Accept-Language header - use a different locale resolution strategy");
 	}
 
 }

spring-webmvc/src/main/java/org/springframework/web/servlet/i18n/CookieLocaleResolver.java

@@ -36,8 +36,8 @@
 
 /**
  * {@link LocaleResolver} implementation that uses a cookie sent back to the user
- * in case of a custom setting, with a fallback to the specified default locale
- * or the request's accept-header locale.
+ * in case of a custom setting, with a fallback to the configured default locale,
+ * the request's {@code Accept-Language} header, or the default locale for the server.
  *
  * <p>This is particularly useful for stateless applications without user sessions.
  * The cookie may optionally contain an associated time zone value as well;
@@ -96,8 +96,8 @@ public class CookieLocaleResolver extends CookieGenerator implements LocaleConte
 
 
 	/**
-	 * Create a new instance of the {@link CookieLocaleResolver} class
-	 * using the {@link #DEFAULT_COOKIE_NAME default cookie name}.
+	 * Create a new instance of {@link CookieLocaleResolver} using the
+	 * {@linkplain #DEFAULT_COOKIE_NAME default cookie name}.
 	 */
 	public CookieLocaleResolver() {
 		setCookieName(DEFAULT_COOKIE_NAME);
@@ -153,14 +153,14 @@ public boolean isRejectInvalidCookies() {
 	}
 
 	/**
-	 * Set a fixed locale that this resolver will return if no cookie found.
+	 * Set a fixed locale that this resolver will return if no cookie is found.
 	 */
 	public void setDefaultLocale(@Nullable Locale defaultLocale) {
 		this.defaultLocale = defaultLocale;
 	}
 
 	/**
-	 * Return the fixed locale that this resolver will return if no cookie found,
+	 * Return the fixed locale that this resolver will return if no cookie is found,
 	 * if any.
 	 */
 	@Nullable
@@ -169,15 +169,15 @@ protected Locale getDefaultLocale() {
 	}
 
 	/**
-	 * Set a fixed time zone that this resolver will return if no cookie found.
+	 * Set a fixed time zone that this resolver will return if no cookie is found.
 	 * @since 4.0
 	 */
 	public void setDefaultTimeZone(@Nullable TimeZone defaultTimeZone) {
 		this.defaultTimeZone = defaultTimeZone;
 	}
 
 	/**
-	 * Return the fixed time zone that this resolver will return if no cookie found,
+	 * Return the fixed time zone that this resolver will return if no cookie is found,
 	 * if any.
 	 * @since 4.0
 	 */
@@ -326,10 +326,11 @@ protected String toLocaleValue(Locale locale) {
 	}
 
 	/**
-	 * Determine the default locale for the given request,
-	 * Called if no locale cookie has been found.
-	 * <p>The default implementation returns the specified default locale,
-	 * if any, else falls back to the request's accept-header locale.
+	 * Determine the default locale for the given request, called if no locale
+	 * cookie has been found.
+	 * <p>The default implementation returns the configured default locale, if any,
+	 * and otherwise falls back to the request's {@code Accept-Language} header
+	 * locale or the default locale for the server.
 	 * @param request the request to resolve the locale for
 	 * @return the default locale (never {@code null})
 	 * @see #setDefaultLocale
@@ -344,9 +345,9 @@ protected Locale determineDefaultLocale(HttpServletRequest request) {
 	}
 
 	/**
-	 * Determine the default time zone for the given request,
-	 * Called if no time zone cookie has been found.
-	 * <p>The default implementation returns the specified default time zone,
+	 * Determine the default time zone for the given request, called if no locale
+	 * cookie has been found.
+	 * <p>The default implementation returns the configured default time zone,
 	 * if any, or {@code null} otherwise.
 	 * @param request the request to resolve the time zone for
 	 * @return the default time zone (or {@code null} if none defined)

spring-webmvc/src/main/java/org/springframework/web/servlet/i18n/SessionLocaleResolver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -30,8 +30,8 @@
 /**
  * {@link org.springframework.web.servlet.LocaleResolver} implementation that
  * uses a locale attribute in the user's session in case of a custom setting,
- * with a fallback to the specified default locale or the request's
- * accept-header locale.
+ * with a fallback to the configured default locale, the request's
+ * {@code Accept-Language} header, or the default locale for the server.
  *
  * <p>This is most appropriate if the application needs user sessions anyway,
  * i.e. when the {@code HttpSession} does not have to be created just for storing
@@ -61,8 +61,8 @@
 public class SessionLocaleResolver extends AbstractLocaleContextResolver {
 
 	/**
-	 * Name of the session attribute that holds the Locale.
-	 * Only used internally by this implementation.
+	 * Default name of the session attribute that holds the Locale.
+	 * <p>Only used internally by this implementation.
 	 * <p>Use {@code RequestContext(Utils).getLocale()}
 	 * to retrieve the current locale in controllers or views.
 	 * @see org.springframework.web.servlet.support.RequestContext#getLocale
@@ -71,8 +71,8 @@ public class SessionLocaleResolver extends AbstractLocaleContextResolver {
 	public static final String LOCALE_SESSION_ATTRIBUTE_NAME = SessionLocaleResolver.class.getName() + ".LOCALE";
 
 	/**
-	 * Name of the session attribute that holds the TimeZone.
-	 * Only used internally by this implementation.
+	 * Default name of the session attribute that holds the TimeZone.
+	 * <p>Only used internally by this implementation.
 	 * <p>Use {@code RequestContext(Utils).getTimeZone()}
 	 * to retrieve the current time zone in controllers or views.
 	 * @see org.springframework.web.servlet.support.RequestContext#getTimeZone
@@ -157,10 +157,12 @@ public void setLocaleContext(HttpServletRequest request, @Nullable HttpServletRe
 
 
 	/**
-	 * Determine the default locale for the given request,
-	 * Called if no Locale session attribute has been found.
-	 * <p>The default implementation returns the specified default locale,
-	 * if any, else falls back to the request's accept-header locale.
+	 * Determine the default locale for the given request, called if no
+	 * {@link Locale} session attribute has been found.
+	 * <p>The default implementation returns the configured
+	 * {@linkplain #setDefaultLocale(Locale) default locale}, if any, and otherwise
+	 * falls back to the request's {@code Accept-Language} header locale or the
+	 * default locale for the server.
 	 * @param request the request to resolve the locale for
 	 * @return the default locale (never {@code null})
 	 * @see #setDefaultLocale
@@ -175,9 +177,9 @@ protected Locale determineDefaultLocale(HttpServletRequest request) {
 	}
 
 	/**
-	 * Determine the default time zone for the given request,
-	 * Called if no TimeZone session attribute has been found.
-	 * <p>The default implementation returns the specified default time zone,
+	 * Determine the default time zone for the given request, called if no
+	 * {@link TimeZone} session attribute has been found.
+	 * <p>The default implementation returns the configured default time zone,
 	 * if any, or {@code null} otherwise.
 	 * @param request the request to resolve the time zone for
 	 * @return the default time zone (or {@code null} if none defined)

spring-webmvc/src/main/java/org/springframework/web/servlet/support/RequestContextUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2022 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -60,7 +60,7 @@
 public abstract class RequestContextUtils {
 
 	/**
-	 * The name of the bean to use to look up in an implementation of
+	 * The name of the bean to use to determine if an implementation of
 	 * {@link RequestDataValueProcessor} has been configured.
 	 * @since 4.2.1
 	 */
@@ -121,10 +121,10 @@ public static WebApplicationContext findWebApplicationContext(HttpServletRequest
 	}
 
 	/**
-	 * Return the LocaleResolver that has been bound to the request by the
-	 * DispatcherServlet.
+	 * Return the {@link LocaleResolver} that has been bound to the request by the
+	 * {@link DispatcherServlet}.
 	 * @param request current HTTP request
-	 * @return the current LocaleResolver, or {@code null} if not found
+	 * @return the current {@code LocaleResolver}, or {@code null} if not found
 	 */
 	@Nullable
 	public static LocaleResolver getLocaleResolver(HttpServletRequest request) {
@@ -133,8 +133,9 @@ public static LocaleResolver getLocaleResolver(HttpServletRequest request) {
 
 	/**
 	 * Retrieve the current locale from the given request, using the
-	 * LocaleResolver bound to the request by the DispatcherServlet
-	 * (if available), falling back to the request's accept-header Locale.
+	 * {@link LocaleResolver} bound to the request by the {@link DispatcherServlet}
+	 * (if available), falling back to the request's locale based on the
+	 * {@code Accept-Language} header or the default locale for the server.
 	 * <p>This method serves as a straightforward alternative to the standard
 	 * Servlet {@link javax.servlet.http.HttpServletRequest#getLocale()} method,
 	 * falling back to the latter if no more specific locale has been found.
@@ -153,18 +154,19 @@ public static Locale getLocale(HttpServletRequest request) {
 
 	/**
 	 * Retrieve the current time zone from the given request, using the
-	 * TimeZoneAwareLocaleResolver bound to the request by the DispatcherServlet
-	 * (if available), falling back to the system's default time zone.
+	 * {@link TimeZoneAwareLocaleContext} in the {@link LocaleResolver} bound to
+	 * the request by the {@link DispatcherServlet} (if available).
 	 * <p>Note: This method returns {@code null} if no specific time zone can be
 	 * resolved for the given request. This is in contrast to {@link #getLocale}
-	 * where there is always the request's accept-header locale to fall back to.
+	 * where it is always possible to fall back to the request's locale based on the
+	 * {@code Accept-Language} header or the default locale for the server.
 	 * <p>Consider using {@link org.springframework.context.i18n.LocaleContextHolder#getTimeZone()}
-	 * which will normally be populated with the same TimeZone: That method only
-	 * differs in terms of its fallback to the system time zone if the LocaleResolver
+	 * which will normally be populated with the same {@code TimeZone}: that method only
+	 * differs in terms of its fallback to the system time zone if the {@code LocaleResolver}
 	 * hasn't provided a specific time zone (instead of this method's {@code null}).
 	 * @param request current HTTP request
 	 * @return the current time zone for the given request, either from the
-	 * TimeZoneAwareLocaleResolver or {@code null} if none associated
+	 * {@code TimeZoneAwareLocaleContext} or {@code null} if none associated
 	 * @see #getLocaleResolver
 	 * @see org.springframework.context.i18n.LocaleContextHolder#getTimeZone()
 	 */
@@ -203,7 +205,7 @@ public static ThemeSource getThemeSource(HttpServletRequest request) {
 	}
 
 	/**
-	 * Retrieves the current theme from the given request, using the ThemeResolver
+	 * Retrieve the current theme from the given request, using the ThemeResolver
 	 * and ThemeSource bound to the request by the DispatcherServlet.
 	 * @param request current HTTP request
 	 * @return the current theme, or {@code null} if not found