diff --git a/spring-context/src/main/java/org/springframework/context/i18n/SimpleLocaleContext.java b/spring-context/src/main/java/org/springframework/context/i18n/SimpleLocaleContext.java index aaec7797c58f..0e678f91c858 100644 --- a/spring-context/src/main/java/org/springframework/context/i18n/SimpleLocaleContext.java +++ b/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}. + *

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; diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/LocaleContextResolver.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/LocaleContextResolver.java index a51e6f4255fd..273612ee53b9 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/LocaleContextResolver.java +++ b/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 diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/LocaleResolver.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/LocaleResolver.java index fd0c651f84a5..633ce880c660 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/LocaleResolver.java +++ b/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. + *

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}) */ diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/i18n/AbstractLocaleContextResolver.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/i18n/AbstractLocaleContextResolver.java index 786628f91ac9..270bb6bf567a 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/i18n/AbstractLocaleContextResolver.java +++ b/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. + * + *

Provides support for a {@linkplain #setDefaultLocale(Locale) default locale} + * and a {@linkplain #setDefaultTimeZone(TimeZone) default time zone}. * *

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() { diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/i18n/AbstractLocaleResolver.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/i18n/AbstractLocaleResolver.java index 29dfd52e8056..c851ed18e065 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/i18n/AbstractLocaleResolver.java +++ b/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. + * + *

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() { diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/i18n/AcceptHeaderLocaleResolver.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/i18n/AcceptHeaderLocaleResolver.java index e5c027e96831..ace004d12329 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/i18n/AcceptHeaderLocaleResolver.java +++ b/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). * - *

Note: Does not support {@code setLocale}, since the accept header - * can only be changed through changing the client's locale settings. + *

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 locales) { } /** - * Return the configured list of supported locales. + * Get the configured list of supported locales. * @since 4.3 */ public List 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"); } } diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/i18n/CookieLocaleResolver.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/i18n/CookieLocaleResolver.java index 9d5bf3e6ca8d..1885b2a17849 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/i18n/CookieLocaleResolver.java +++ b/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. * *

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,7 +169,7 @@ 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) { @@ -177,7 +177,7 @@ public void setDefaultTimeZone(@Nullable TimeZone 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. - *

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. + *

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. - *

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. + *

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) diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/i18n/SessionLocaleResolver.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/i18n/SessionLocaleResolver.java index 18572a08135d..4feb1e255ea7 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/i18n/SessionLocaleResolver.java +++ b/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. * *

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. + *

Only used internally by this implementation. *

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. + *

Only used internally by this implementation. *

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. - *

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. + *

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. - *

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. + *

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) diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/support/RequestContextUtils.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/support/RequestContextUtils.java index 05f3e78f2eea..bb6014c48071 100644 --- a/spring-webmvc/src/main/java/org/springframework/web/servlet/support/RequestContextUtils.java +++ b/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. *

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). *

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. *

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