From 3027d78f404d386ca07c940bed5d473f6d9e7c11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Deleuze?= Date: Tue, 6 Jan 2026 11:03:46 +0100 Subject: [PATCH] Modernize the DispatcherServlet Locale documentation The Java sample for "Locale Interceptor" shows a `urlHandlerMapping.setUrlMap(Map.of("...` line due the inability to disable the code chomping Asciidoctor extension with the code include one. It will be fixed by a subsequent commit or a bug fix in https://github.com/spring-io/asciidoctor-extensions. Closes gh-36099 --- .../webmvc/mvc-servlet/localeresolver.adoc | 67 ++----------------- .../WebConfiguration.java | 38 +++++++++++ .../WebConfiguration.java | 48 +++++++++++++ .../WebConfiguration.kt | 35 ++++++++++ .../WebConfiguration.kt | 44 ++++++++++++ .../WebConfiguration.xml | 19 ++++++ .../WebConfiguration.xml | 30 +++++++++ 7 files changed, 218 insertions(+), 63 deletions(-) create mode 100644 framework-docs/src/main/java/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolvercookie/WebConfiguration.java create mode 100644 framework-docs/src/main/java/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolverinterceptor/WebConfiguration.java create mode 100644 framework-docs/src/main/kotlin/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolvercookie/WebConfiguration.kt create mode 100644 framework-docs/src/main/kotlin/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolverinterceptor/WebConfiguration.kt create mode 100644 framework-docs/src/main/resources/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolvercookie/WebConfiguration.xml create mode 100644 framework-docs/src/main/resources/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolverinterceptor/WebConfiguration.xml diff --git a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/localeresolver.adoc b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/localeresolver.adoc index b489b453149..fca88d44779 100644 --- a/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/localeresolver.adoc +++ b/framework-docs/modules/ROOT/pages/web/webmvc/mvc-servlet/localeresolver.adoc @@ -54,44 +54,9 @@ information. This locale resolver inspects a `Cookie` that might exist on the client to see if a `Locale` or `TimeZone` is specified. If so, it uses the specified details. By using the properties of this locale resolver, you can specify the name of the cookie as well as the -maximum age. The following example defines a `CookieLocaleResolver`: - -[source,xml,indent=0,subs="verbatim,quotes"] ----- - - - - - - - - ----- - -The following table describes the properties `CookieLocaleResolver`: - -[[mvc-cookie-locale-resolver-props-tbl]] -.CookieLocaleResolver properties -[cols="1,1,4"] -|=== -| Property | Default | Description - -| `cookieName` -| class name + LOCALE -| The name of the cookie - -| `cookieMaxAge` -| Servlet container default -| The maximum time a cookie persists on the client. If `-1` is specified, the - cookie will not be persisted. It is available only until the client shuts down - the browser. - -| `cookiePath` -| / -| Limits the visibility of the cookie to a certain part of your site. When `cookiePath` is - specified, the cookie is visible only to that path and the paths below it. -|=== +maximum age. The following example defines a `CookieLocaleResolver` bean: +include-code::./WebConfiguration[tag=snippet,indent=0] [[mvc-localeresolver-session]] == Session Resolver @@ -115,31 +80,7 @@ You can enable changing of locales by adding the `LocaleChangeInterceptor` to on accordingly, calling the `setLocale` method on the `LocaleResolver` in the dispatcher's application context. The next example shows that calls to all `{asterisk}.view` resources that contain a parameter named `siteLanguage` now changes the locale. So, for example, -a request for the URL, `https://www.sf.net/home.view?siteLanguage=nl`, changes the site +a request for the URL `https://domain.com/home.view?siteLanguage=nl` changes the site language to Dutch. The following example shows how to intercept the locale: -[source,xml,indent=0,subs="verbatim"] ----- - - - - - - - - - - - - - - /**/*.view=someController - - ----- - - - +include-code::./WebConfiguration[tag=snippet,indent=0] diff --git a/framework-docs/src/main/java/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolvercookie/WebConfiguration.java b/framework-docs/src/main/java/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolvercookie/WebConfiguration.java new file mode 100644 index 00000000000..7dd17629701 --- /dev/null +++ b/framework-docs/src/main/java/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolvercookie/WebConfiguration.java @@ -0,0 +1,38 @@ +/* + * Copyright 2002-present 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. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.docs.web.webmvc.mvcservlet.mvclocaleresolvercookie; + +import java.time.Duration; + +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import org.springframework.web.servlet.LocaleResolver; +import org.springframework.web.servlet.i18n.CookieLocaleResolver; + +// tag::snippet[] +@Configuration +public class WebConfiguration { + + @Bean + public LocaleResolver localeResolver() { + CookieLocaleResolver localeResolver = new CookieLocaleResolver("clientlanguage"); + localeResolver.setCookieMaxAge(Duration.ofSeconds(100000)); + return localeResolver; + } +} +// end::snippet[] + diff --git a/framework-docs/src/main/java/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolverinterceptor/WebConfiguration.java b/framework-docs/src/main/java/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolverinterceptor/WebConfiguration.java new file mode 100644 index 00000000000..d63f1c7a987 --- /dev/null +++ b/framework-docs/src/main/java/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolverinterceptor/WebConfiguration.java @@ -0,0 +1,48 @@ +/* + * Copyright 2002-present 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. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.docs.web.webmvc.mvcservlet.mvclocaleresolverinterceptor; + +import java.util.Map; + +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import org.springframework.web.servlet.LocaleResolver; +import org.springframework.web.servlet.handler.SimpleUrlHandlerMapping; +import org.springframework.web.servlet.i18n.CookieLocaleResolver; +import org.springframework.web.servlet.i18n.LocaleChangeInterceptor; + +// tag::snippet[] +@Configuration +public class WebConfiguration { + + @Bean + public LocaleResolver localeResolver() { + return new CookieLocaleResolver(); + } + + @Bean + public SimpleUrlHandlerMapping urlMapping() { + SimpleUrlHandlerMapping urlHandlerMapping = new SimpleUrlHandlerMapping(); + LocaleChangeInterceptor interceptor = new LocaleChangeInterceptor(); + interceptor.setParamName("siteLanguage"); + urlHandlerMapping.setInterceptors(interceptor); + urlHandlerMapping.setUrlMap(Map.of("/**/*.view", "someController")); + return urlHandlerMapping; + } +} +// end::snippet[] + diff --git a/framework-docs/src/main/kotlin/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolvercookie/WebConfiguration.kt b/framework-docs/src/main/kotlin/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolvercookie/WebConfiguration.kt new file mode 100644 index 00000000000..3dcb877621c --- /dev/null +++ b/framework-docs/src/main/kotlin/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolvercookie/WebConfiguration.kt @@ -0,0 +1,35 @@ +/* + * Copyright 2002-present 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. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.docs.web.webmvc.mvcservlet.mvclocaleresolvercookie + +import org.springframework.context.annotation.Bean +import org.springframework.context.annotation.Configuration +import org.springframework.web.servlet.LocaleResolver +import org.springframework.web.servlet.i18n.CookieLocaleResolver +import java.time.Duration + +// tag::snippet[] +@Configuration +class WebConfiguration { + + @Bean + fun localeResolver(): LocaleResolver = CookieLocaleResolver("clientlanguage").apply { + setCookieMaxAge(Duration.ofSeconds(100000)) + } +} +// end::snippet[] + diff --git a/framework-docs/src/main/kotlin/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolverinterceptor/WebConfiguration.kt b/framework-docs/src/main/kotlin/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolverinterceptor/WebConfiguration.kt new file mode 100644 index 00000000000..b3f7806e3ce --- /dev/null +++ b/framework-docs/src/main/kotlin/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolverinterceptor/WebConfiguration.kt @@ -0,0 +1,44 @@ +/* + * Copyright 2002-present 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. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.docs.web.webmvc.mvcservlet.mvclocaleresolverinterceptor + +import org.springframework.context.annotation.Bean +import org.springframework.context.annotation.Configuration +import org.springframework.web.servlet.LocaleResolver +import org.springframework.web.servlet.handler.SimpleUrlHandlerMapping +import org.springframework.web.servlet.i18n.CookieLocaleResolver +import org.springframework.web.servlet.i18n.LocaleChangeInterceptor + +// tag::snippet[] +@Configuration +class WebConfiguration { + + @Bean + fun localeResolver(): LocaleResolver { + return CookieLocaleResolver() + } + + @Bean + fun urlMapping() = SimpleUrlHandlerMapping().apply { + setInterceptors(LocaleChangeInterceptor().apply { + paramName = "siteLanguage" + }) + /* @chomp:line urlMap = mapOf("/**/*.view" to "someController") */urlMap = mapOf("/**/*.view" to "someController") + } +} +// end::snippet[] + diff --git a/framework-docs/src/main/resources/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolvercookie/WebConfiguration.xml b/framework-docs/src/main/resources/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolvercookie/WebConfiguration.xml new file mode 100644 index 00000000000..23c624bcfc6 --- /dev/null +++ b/framework-docs/src/main/resources/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolvercookie/WebConfiguration.xml @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + diff --git a/framework-docs/src/main/resources/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolverinterceptor/WebConfiguration.xml b/framework-docs/src/main/resources/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolverinterceptor/WebConfiguration.xml new file mode 100644 index 00000000000..6f659cb0300 --- /dev/null +++ b/framework-docs/src/main/resources/org/springframework/docs/web/webmvc/mvcservlet/mvclocaleresolverinterceptor/WebConfiguration.xml @@ -0,0 +1,30 @@ + + + + + + + + + + + + + + + + + /**/*.view=someController + + + + + +