Improve documentation regarding encoding in FreeMarker support

This commit also introduces integration tests to test the status quo
regarding encoding.

Closes gh-33071

Author: sbrannen

spring-context-support/src/main/java/org/springframework/ui/freemarker/FreeMarkerConfigurationFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 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.
@@ -41,9 +41,11 @@
 import org.springframework.util.CollectionUtils;
 
 /**
- * Factory that configures a FreeMarker Configuration. Can be used standalone, but
- * typically you will either use FreeMarkerConfigurationFactoryBean for preparing a
- * Configuration as bean reference, or FreeMarkerConfigurer for web views.
+ * Factory that configures a FreeMarker {@link Configuration}.
+ *
+ * <p>Can be used standalone, but typically you will either use
+ * {@link FreeMarkerConfigurationFactoryBean} for preparing a {@code Configuration}
+ * as a bean reference, or {@code FreeMarkerConfigurer} for web views.
  *
  * <p>The optional "configLocation" property sets the location of a FreeMarker
  * properties file, within the current application. FreeMarker properties can be
@@ -52,17 +54,18 @@
  * subject to constraints set by FreeMarker.
  *
  * <p>The "freemarkerVariables" property can be used to specify a Map of
- * shared variables that will be applied to the Configuration via the
+ * shared variables that will be applied to the {@code Configuration} via the
  * {@code setAllSharedVariables()} method. Like {@code setSettings()},
  * these entries are subject to FreeMarker constraints.
  *
  * <p>The simplest way to use this class is to specify a "templateLoaderPath";
  * FreeMarker does not need any further configuration then.
  *
- * <p>Note: Spring's FreeMarker support requires FreeMarker 2.3 or higher.
+ * <p>Note: Spring's FreeMarker support requires FreeMarker 2.3.21 or higher.
  *
  * @author Darren Davison
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 03.03.2004
  * @see #setConfigLocation
  * @see #setFreemarkerSettings
@@ -107,7 +110,7 @@ public class FreeMarkerConfigurationFactory {
 
 	/**
 	 * Set the location of the FreeMarker config file.
-	 * Alternatively, you can specify all setting locally.
+	 * <p>Alternatively, you can specify all settings locally.
 	 * @see #setFreemarkerSettings
 	 * @see #setTemplateLoaderPath
 	 */
@@ -134,25 +137,33 @@ public void setFreemarkerVariables(Map<String, Object> variables) {
 	}
 
 	/**
-	 * Set the default encoding for the FreeMarker configuration.
-	 * If not specified, FreeMarker will use the platform file encoding.
-	 * <p>Used for template rendering unless there is an explicit encoding specified
-	 * for the rendering process (for example, on Spring's FreeMarkerView).
+	 * Set the default encoding for the FreeMarker {@link Configuration}, which
+	 * is used to decode byte sequences to character sequences when reading template
+	 * files.
+	 * <p>If not specified, FreeMarker will read template files using the platform
+	 * file encoding (defined by the JVM system property {@code file.encoding})
+	 * or {@code "utf-8"} if the platform file encoding is undefined.
+	 * <p>Note that the encoding is not used for template rendering. Instead, an
+	 * explicit encoding must be specified for the rendering process &mdash; for
+	 * example, via Spring's {@code FreeMarkerView} or {@code FreeMarkerViewResolver}.
 	 * @see freemarker.template.Configuration#setDefaultEncoding
 	 * @see org.springframework.web.servlet.view.freemarker.FreeMarkerView#setEncoding
+	 * @see org.springframework.web.servlet.view.freemarker.FreeMarkerView#setContentType
+	 * @see org.springframework.web.servlet.view.freemarker.FreeMarkerViewResolver#setContentType
 	 */
 	public void setDefaultEncoding(String defaultEncoding) {
 		this.defaultEncoding = defaultEncoding;
 	}
 
 	/**
-	 * Set a List of {@code TemplateLoader}s that will be used to search
-	 * for templates. For example, one or more custom loaders such as database
-	 * loaders could be configured and injected here.
-	 * <p>The {@link TemplateLoader TemplateLoaders} specified here will be
-	 * registered <i>before</i> the default template loaders that this factory
-	 * registers (such as loaders for specified "templateLoaderPaths" or any
-	 * loaders registered in {@link #postProcessTemplateLoaders}).
+	 * Set a List of {@link TemplateLoader TemplateLoaders} that will be used to
+	 * search for templates.
+	 * <p>For example, one or more custom loaders such as database loaders could
+	 * be configured and injected here.
+	 * <p>The {@code TemplateLoaders} specified here will be registered <i>before</i>
+	 * the default template loaders that this factory registers (such as loaders
+	 * for specified "templateLoaderPaths" or any loaders registered in
+	 * {@link #postProcessTemplateLoaders}).
 	 * @see #setTemplateLoaderPaths
 	 * @see #postProcessTemplateLoaders
 	 */
@@ -161,13 +172,14 @@ public void setPreTemplateLoaders(TemplateLoader... preTemplateLoaders) {
 	}
 
 	/**
-	 * Set a List of {@code TemplateLoader}s that will be used to search
-	 * for templates. For example, one or more custom loaders such as database
-	 * loaders can be configured.
-	 * <p>The {@link TemplateLoader TemplateLoaders} specified here will be
-	 * registered <i>after</i> the default template loaders that this factory
-	 * registers (such as loaders for specified "templateLoaderPaths" or any
-	 * loaders registered in {@link #postProcessTemplateLoaders}).
+	 * Set a List of {@link TemplateLoader TemplateLoaders} that will be used to
+	 * search for templates.
+	 * <p>For example, one or more custom loaders such as database loaders could
+	 * be configured and injected here.
+	 * <p>The {@code TemplateLoaders} specified here will be registered <i>after</i>
+	 * the default template loaders that this factory registers (such as loaders
+	 * for specified "templateLoaderPaths" or any loaders registered in
+	 * {@link #postProcessTemplateLoaders}).
 	 * @see #setTemplateLoaderPaths
 	 * @see #postProcessTemplateLoaders
 	 */
@@ -177,7 +189,7 @@ public void setPostTemplateLoaders(TemplateLoader... postTemplateLoaders) {
 
 	/**
 	 * Set the Freemarker template loader path via a Spring resource location.
-	 * See the "templateLoaderPaths" property for details on path handling.
+	 * <p>See the "templateLoaderPaths" property for details on path handling.
 	 * @see #setTemplateLoaderPaths
 	 */
 	public void setTemplateLoaderPath(String templateLoaderPath) {
@@ -188,48 +200,49 @@ public void setTemplateLoaderPath(String templateLoaderPath) {
 	 * Set multiple Freemarker template loader paths via Spring resource locations.
 	 * <p>When populated via a String, standard URLs like "file:" and "classpath:"
 	 * pseudo URLs are supported, as understood by ResourceEditor. Allows for
-	 * relative paths when running in an ApplicationContext.
-	 * <p>Will define a path for the default FreeMarker template loader.
-	 * If a specified resource cannot be resolved to a {@code java.io.File},
-	 * a generic SpringTemplateLoader will be used, without modification detection.
-	 * <p>To enforce the use of SpringTemplateLoader, i.e. to not resolve a path
-	 * as file system resource in any case, turn off the "preferFileSystemAccess"
+	 * relative paths when running in an {@code ApplicationContext}.
+	 * <p>Will define a path for the default FreeMarker template loader. If a
+	 * specified resource cannot be resolved to a {@code java.io.File}, a generic
+	 * {@link SpringTemplateLoader} will be used, without modification detection.
+	 * <p>To enforce the use of {@code SpringTemplateLoader}, i.e. to not resolve
+	 * a path as file system resource in any case, turn off the "preferFileSystemAccess"
 	 * flag. See the latter's javadoc for details.
 	 * <p>If you wish to specify your own list of TemplateLoaders, do not set this
-	 * property and instead use {@code setTemplateLoaders(List templateLoaders)}
+	 * property and instead use {@link #setPostTemplateLoaders(TemplateLoader...)}.
 	 * @see org.springframework.core.io.ResourceEditor
 	 * @see org.springframework.context.ApplicationContext#getResource
 	 * @see freemarker.template.Configuration#setDirectoryForTemplateLoading
 	 * @see SpringTemplateLoader
+	 * @see #setPreferFileSystemAccess(boolean)
 	 */
 	public void setTemplateLoaderPaths(String... templateLoaderPaths) {
 		this.templateLoaderPaths = templateLoaderPaths;
 	}
 
 	/**
-	 * Set the Spring ResourceLoader to use for loading FreeMarker template files.
-	 * The default is DefaultResourceLoader. Will get overridden by the
-	 * ApplicationContext if running in a context.
+	 * Set the {@link ResourceLoader} to use for loading FreeMarker template files.
+	 * <p>The default is {@link DefaultResourceLoader}. Will get overridden by the
+	 * {@code ApplicationContext} if running in a context.
 	 * @see org.springframework.core.io.DefaultResourceLoader
 	 */
 	public void setResourceLoader(ResourceLoader resourceLoader) {
 		this.resourceLoader = resourceLoader;
 	}
 
 	/**
-	 * Return the Spring ResourceLoader to use for loading FreeMarker template files.
+	 * Return the {@link ResourceLoader} to use for loading FreeMarker template files.
 	 */
 	protected ResourceLoader getResourceLoader() {
 		return this.resourceLoader;
 	}
 
 	/**
 	 * Set whether to prefer file system access for template loading.
-	 * File system access enables hot detection of template changes.
+	 * <p>File system access enables hot detection of template changes.
 	 * <p>If this is enabled, FreeMarkerConfigurationFactory will try to resolve
 	 * the specified "templateLoaderPath" as file system resource (which will work
 	 * for expanded class path resources and ServletContext resources too).
-	 * <p>Default is "true". Turn this off to always load via SpringTemplateLoader
+	 * <p>Default is "true". Turn this off to always load via {@link SpringTemplateLoader}
 	 * (i.e. as stream, without hot detection of template changes), which might
 	 * be necessary if some of your templates reside in an expanded classes
 	 * directory while others reside in jar files.
@@ -248,8 +261,8 @@ protected boolean isPreferFileSystemAccess() {
 
 
 	/**
-	 * Prepare the FreeMarker Configuration and return it.
-	 * @return the FreeMarker Configuration object
+	 * Prepare the FreeMarker {@link Configuration} and return it.
+	 * @return the FreeMarker {@code Configuration} object
 	 * @throws IOException if the config file wasn't found
 	 * @throws TemplateException on FreeMarker initialization failure
 	 */
@@ -314,11 +327,12 @@ public Configuration createConfiguration() throws IOException, TemplateException
 	}
 
 	/**
-	 * Return a new Configuration object. Subclasses can override this for custom
-	 * initialization (e.g. specifying a FreeMarker compatibility level which is a
-	 * new feature in FreeMarker 2.3.21), or for using a mock object for testing.
-	 * <p>Called by {@code createConfiguration()}.
-	 * @return the Configuration object
+	 * Return a new {@link Configuration} object.
+	 * <p>Subclasses can override this for custom initialization &mdash; for example,
+	 * to specify a FreeMarker compatibility level (which is a new feature in
+	 * FreeMarker 2.3.21), or to use a mock object for testing.
+	 * <p>Called by {@link #createConfiguration()}.
+	 * @return the {@code Configuration} object
 	 * @throws IOException if a config file wasn't found
 	 * @throws TemplateException on FreeMarker initialization failure
 	 * @see #createConfiguration()
@@ -328,11 +342,11 @@ protected Configuration newConfiguration() throws IOException, TemplateException
 	}
 
 	/**
-	 * Determine a FreeMarker TemplateLoader for the given path.
-	 * <p>Default implementation creates either a FileTemplateLoader or
-	 * a SpringTemplateLoader.
+	 * Determine a FreeMarker {@link TemplateLoader} for the given path.
+	 * <p>Default implementation creates either a {@link FileTemplateLoader} or
+	 * a {@link SpringTemplateLoader}.
 	 * @param templateLoaderPath the path to load templates from
-	 * @return an appropriate TemplateLoader
+	 * @return an appropriate {@code TemplateLoader}
 	 * @see freemarker.cache.FileTemplateLoader
 	 * @see SpringTemplateLoader
 	 */
@@ -366,9 +380,9 @@ protected TemplateLoader getTemplateLoaderForPath(String templateLoaderPath) {
 
 	/**
 	 * To be overridden by subclasses that want to register custom
-	 * TemplateLoader instances after this factory created its default
+	 * {@link TemplateLoader} instances after this factory created its default
 	 * template loaders.
-	 * <p>Called by {@code createConfiguration()}. Note that specified
+	 * <p>Called by {@link #createConfiguration()}. Note that specified
 	 * "postTemplateLoaders" will be registered <i>after</i> any loaders
 	 * registered by this callback; as a consequence, they are <i>not</i>
 	 * included in the given List.
@@ -381,10 +395,10 @@ protected void postProcessTemplateLoaders(List<TemplateLoader> templateLoaders)
 	}
 
 	/**
-	 * Return a TemplateLoader based on the given TemplateLoader list.
-	 * If more than one TemplateLoader has been registered, a FreeMarker
-	 * MultiTemplateLoader needs to be created.
-	 * @param templateLoaders the final List of TemplateLoader instances
+	 * Return a {@link TemplateLoader} based on the given {@code TemplateLoader} list.
+	 * <p>If more than one TemplateLoader has been registered, a FreeMarker
+	 * {@link MultiTemplateLoader} will be created.
+	 * @param templateLoaders the final List of {@code TemplateLoader} instances
 	 * @return the aggregate TemplateLoader
 	 */
 	@Nullable
@@ -404,10 +418,10 @@ protected TemplateLoader getAggregateTemplateLoader(List<TemplateLoader> templat
 
 	/**
 	 * To be overridden by subclasses that want to perform custom
-	 * post-processing of the Configuration object after this factory
+	 * post-processing of the {@link Configuration} object after this factory
 	 * performed its default initialization.
-	 * <p>Called by {@code createConfiguration()}.
-	 * @param config the current Configuration object
+	 * <p>Called by {@link #createConfiguration()}.
+	 * @param config the current {@code Configuration} object
 	 * @throws IOException if a config file wasn't found
 	 * @throws TemplateException on FreeMarker initialization failure
 	 * @see #createConfiguration()

spring-context-support/src/main/java/org/springframework/ui/freemarker/FreeMarkerConfigurationFactoryBean.java

@@ -27,22 +27,25 @@
 import org.springframework.lang.Nullable;
 
 /**
- * Factory bean that creates a FreeMarker Configuration and provides it as
- * bean reference. This bean is intended for any kind of usage of FreeMarker
- * in application code, e.g. for generating email content. For web views,
- * FreeMarkerConfigurer is used to set up a FreeMarkerConfigurationFactory.
- * <p>
- * The simplest way to use this class is to specify just a "templateLoaderPath";
+ * Factory bean that creates a FreeMarker {@link Configuration} and provides it
+ * as a bean reference.
+ *
+ * <p>This bean is intended for any kind of usage of FreeMarker in application
+ * code &mdash; for example, for generating email content. For web views,
+ * {@code FreeMarkerConfigurer} is used to set up a {@link FreeMarkerConfigurationFactory}.
+ *
+ * <p>The simplest way to use this class is to specify just a "templateLoaderPath";
  * you do not need any further configuration then. For example, in a web
  * application context:
  *
  * <pre class="code"> &lt;bean id="freemarkerConfiguration" class="org.springframework.ui.freemarker.FreeMarkerConfigurationFactoryBean"&gt;
  *   &lt;property name="templateLoaderPath" value="/WEB-INF/freemarker/"/&gt;
  * &lt;/bean&gt;</pre>
-
- * See the base class FreeMarkerConfigurationFactory for configuration details.
  *
- * <p>Note: Spring's FreeMarker support requires FreeMarker 2.3 or higher.
+ * <p>See the {@link FreeMarkerConfigurationFactory} base class for configuration
+ * details.
+ *
+ * <p>Note: Spring's FreeMarker support requires FreeMarker 2.3.21 or higher.
  *
  * @author Darren Davison
  * @since 03.03.2004

spring-context-support/src/main/java/org/springframework/ui/freemarker/FreeMarkerTemplateUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2024 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.
@@ -24,7 +24,8 @@
 
 /**
  * Utility class for working with FreeMarker.
- * Provides convenience methods to process a FreeMarker template with a model.
+ *
+ * <p>Provides convenience methods to process a FreeMarker template with a model.
  *
  * @author Juergen Hoeller
  * @since 14.03.2004
@@ -33,12 +34,12 @@ public abstract class FreeMarkerTemplateUtils {
 
 	/**
 	 * Process the specified FreeMarker template with the given model and write
-	 * the result to the given Writer.
-	 * <p>When using this method to prepare a text for a mail to be sent with Spring's
+	 * the result to a String.
+	 * <p>When using this method to prepare text for a mail to be sent with Spring's
 	 * mail support, consider wrapping IO/TemplateException in MailPreparationException.
 	 * @param model the model object, typically a Map that contains model names
 	 * as keys and model objects as values
-	 * @return the result as String
+	 * @return the result as a String
 	 * @throws IOException if the template wasn't found or couldn't be read
 	 * @throws freemarker.template.TemplateException if rendering failed
 	 * @see org.springframework.mail.MailPreparationException

spring-context-support/src/main/java/org/springframework/ui/freemarker/SpringTemplateLoader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2024 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.
@@ -29,9 +29,11 @@
 import org.springframework.lang.Nullable;
 
 /**
- * FreeMarker {@link TemplateLoader} adapter that loads via a Spring {@link ResourceLoader}.
- * Used by {@link FreeMarkerConfigurationFactory} for any resource loader path that cannot
- * be resolved to a {@link java.io.File}.
+ * FreeMarker {@link TemplateLoader} adapter that loads template files via a
+ * Spring {@link ResourceLoader}.
+ *
+ * <p>Used by {@link FreeMarkerConfigurationFactory} for any resource loader path
+ * that cannot be resolved to a {@link java.io.File}.
  *
  * @author Juergen Hoeller
  * @since 14.03.2004
@@ -48,7 +50,7 @@ public class SpringTemplateLoader implements TemplateLoader {
 
 
 	/**
-	 * Create a new SpringTemplateLoader.
+	 * Create a new {@code SpringTemplateLoader}.
 	 * @param resourceLoader the Spring ResourceLoader to use
 	 * @param templateLoaderPath the template loader path to use
 	 */