Package org.springframework.ui.freemarker

# Class FreeMarkerConfigurationFactory

java.lang.Object
org.springframework.ui.freemarker.FreeMarkerConfigurationFactory

Direct Known Subclasses:
  `FreeMarkerConfigurationFactoryBean`

public class FreeMarkerConfigurationFactory extends Object
Factory that configures a FreeMarker `Configuration`.

Can be used standalone, but typically you will either use `FreeMarkerConfigurationFactoryBean` for preparing a `Configuration` as a bean reference, or `FreeMarkerConfigurer` for web views.

The optional "configLocation" property sets the location of a FreeMarker properties file, within the current application. FreeMarker properties can be overridden via "freemarkerSettings". All of these properties will be set by calling FreeMarker's `Configuration.setSettings()` method and are subject to constraints set by FreeMarker.

The "freemarkerVariables" property can be used to specify a Map of shared variables that will be applied to the `Configuration` via the `setAllSharedVariables()` method. Like `setSettings()`, these entries are subject to FreeMarker constraints.

The simplest way to use this class is to specify a "templateLoaderPath"; FreeMarker does not need any further configuration then.

Note: Spring's FreeMarker support requires FreeMarker 2.3.33 or higher.

Since:
  03.03.2004
Author:
  Darren Davison, Juergen Hoeller, Sam Brannen
See Also:
  - `setConfigLocation(org.springframework.core.io.Resource)`
  - `setFreemarkerSettings(java.util.Properties)`
  - `setFreemarkerVariables(java.util.Map<java.lang.String, java.lang.Object>)`
  - `setTemplateLoaderPath(java.lang.String)`
  - `createConfiguration()`
  - `FreeMarkerConfigurationFactoryBean`
  - `org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer`
  - `Configuration`

## Field Summary

Fields
Modifier and Type
Field
Description
`protected final org.apache.commons.logging.Log`
`logger`

## Constructor Summary

Constructors
Constructor
Description
`FreeMarkerConfigurationFactory()`

## Method Summary

Modifier and Type
Method
Description
`freemarker.template.Configuration`
`createConfiguration()`
Prepare the FreeMarker `Configuration` and return it.
`protected freemarker.cache.TemplateLoader`
`getAggregateTemplateLoader(List<freemarker.cache.TemplateLoader> templateLoaders)`
Return a `TemplateLoader` based on the given `TemplateLoader` list.
`protected org.springframework.core.io.ResourceLoader`
`getResourceLoader()`
Return the `ResourceLoader` to use for loading FreeMarker template files.
`protected freemarker.cache.TemplateLoader`
`getTemplateLoaderForPath(String templateLoaderPath)`
Determine a FreeMarker `TemplateLoader` for the given path.
`protected boolean`
`isPreferFileSystemAccess()`
Return whether to prefer file system access for template loading.
`protected freemarker.template.Configuration`
`newConfiguration()`
Return a new `Configuration` object.
`protected void`
`postProcessConfiguration(freemarker.template.Configuration config)`
To be overridden by subclasses that want to perform custom post-processing of the `Configuration` object after this factory performed its default initialization.
`protected void`
`postProcessTemplateLoaders(List<freemarker.cache.TemplateLoader> templateLoaders)`
To be overridden by subclasses that want to register custom `TemplateLoader` instances after this factory created its default template loaders.
`void`
`setConfigLocation(org.springframework.core.io.Resource resource)`
Set the location of the FreeMarker config file.
`void`
`setDefaultCharset(Charset defaultCharset)`
Set the `Charset` for the default encoding for the FreeMarker `Configuration`, which is used to decode byte sequences to character sequences when reading template files.
`void`
`setDefaultEncoding(String defaultEncoding)`
Set the default encoding for the FreeMarker `Configuration`, which is used to decode byte sequences to character sequences when reading template files.
`void`
`setFreemarkerSettings(Properties settings)`
Set properties that contain well-known FreeMarker keys which will be passed to FreeMarker's `Configuration.setSettings` method.
`void`
`setFreemarkerVariables(Map<String,Object> variables)`
Set a Map that contains well-known FreeMarker objects which will be passed to FreeMarker's `Configuration.setAllSharedVariables()` method.
`void`
`setPostTemplateLoaders(freemarker.cache.TemplateLoader... postTemplateLoaders)`
Set a list of `TemplateLoaders` that will be used to search for templates.
`void`
`setPreferFileSystemAccess(boolean preferFileSystemAccess)`
Set whether to prefer file system access for template loading.
`void`
`setPreTemplateLoaders(freemarker.cache.TemplateLoader... preTemplateLoaders)`
Set a list of `TemplateLoaders` that will be used to search for templates.
`void`
`setResourceLoader(org.springframework.core.io.ResourceLoader resourceLoader)`
Set the `ResourceLoader` to use for loading FreeMarker template files.
`void`
`setTemplateLoaderPath(String templateLoaderPath)`
Set the Freemarker template loader path via a Spring resource location.
`void`
`setTemplateLoaderPaths(String... templateLoaderPaths)`
Set multiple Freemarker template loader paths via Spring resource locations.

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

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

## Field Details

### logger

protected final org.apache.commons.logging.Log logger

## Constructor Details

### FreeMarkerConfigurationFactory

public FreeMarkerConfigurationFactory()

## Method Details

### setConfigLocation

public void setConfigLocation(org.springframework.core.io.Resource resource)
Set the location of the FreeMarker config file.

Alternatively, you can specify all settings locally.

See Also:
  - `setFreemarkerSettings(java.util.Properties)`
  - `setTemplateLoaderPath(java.lang.String)`

### setFreemarkerSettings

public void setFreemarkerSettings(Properties settings)
Set properties that contain well-known FreeMarker keys which will be passed to FreeMarker's `Configuration.setSettings` method.

See Also:
  - `Configurable.setSettings(java.util.Properties)`

### setFreemarkerVariables

public void setFreemarkerVariables(Map<String,Object> variables)
Set a Map that contains well-known FreeMarker objects which will be passed to FreeMarker's `Configuration.setAllSharedVariables()` method.

See Also:
  - `Configuration.setAllSharedVariables(freemarker.template.TemplateHashModelEx)`

### setDefaultEncoding

public void setDefaultEncoding(String defaultEncoding)
Set the default encoding for the FreeMarker `Configuration`, which is used to decode byte sequences to character sequences when reading template files.

If not specified, FreeMarker will read template files using the platform file encoding (defined by the JVM system property `file.encoding`) or UTF-8 if the platform file encoding is undefined.

Note that the supplied encoding may or may not be used for template rendering. See the documentation for Spring's `FreeMarkerView` and `FreeMarkerViewResolver` implementations for further details.

See Also:
  - `setDefaultCharset(Charset)`
  - `Configuration.setDefaultEncoding(java.lang.String)`
  - `org.springframework.web.servlet.view.freemarker.FreeMarkerView#setEncoding`
  - `org.springframework.web.servlet.view.freemarker.FreeMarkerView#setContentType`
  - `org.springframework.web.servlet.view.freemarker.FreeMarkerViewResolver#setContentType`
  - `org.springframework.web.reactive.result.view.freemarker.FreeMarkerView#setEncoding`
  - `org.springframework.web.reactive.result.view.freemarker.FreeMarkerView#setSupportedMediaTypes`
  - `org.springframework.web.reactive.result.view.freemarker.FreeMarkerViewResolver#setSupportedMediaTypes`

### setDefaultCharset

public void setDefaultCharset(Charset defaultCharset)
Set the `Charset` for the default encoding for the FreeMarker `Configuration`, which is used to decode byte sequences to character sequences when reading template files.

See `setDefaultEncoding(String)` for details.

Since:
  6.2
See Also:
  - `StandardCharsets`

### setPreTemplateLoaders

public void setPreTemplateLoaders(freemarker.cache.TemplateLoader... preTemplateLoaders)
Set a list of `TemplateLoaders` 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.

The `TemplateLoaders` specified here will be registered before the default template loaders that this factory registers (such as loaders for specified "templateLoaderPaths" or any loaders registered in `postProcessTemplateLoaders(java.util.List<freemarker.cache.TemplateLoader>)`).

See Also:
  - `setTemplateLoaderPaths(java.lang.String...)`
  - `postProcessTemplateLoaders(java.util.List<freemarker.cache.TemplateLoader>)`

### setPostTemplateLoaders

public void setPostTemplateLoaders(freemarker.cache.TemplateLoader... postTemplateLoaders)
Set a list of `TemplateLoaders` 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.

The `TemplateLoaders` specified here will be registered after the default template loaders that this factory registers (such as loaders for specified "templateLoaderPaths" or any loaders registered in `postProcessTemplateLoaders(java.util.List<freemarker.cache.TemplateLoader>)`).

See Also:
  - `setTemplateLoaderPaths(java.lang.String...)`
  - `postProcessTemplateLoaders(java.util.List<freemarker.cache.TemplateLoader>)`

### setTemplateLoaderPath

public void setTemplateLoaderPath(String templateLoaderPath)
Set the Freemarker template loader path via a Spring resource location.

See the "templateLoaderPaths" property for details on path handling.

See Also:
  - `setTemplateLoaderPaths(java.lang.String...)`

### setTemplateLoaderPaths

public void setTemplateLoaderPaths(String... templateLoaderPaths)
Set multiple Freemarker template loader paths via Spring resource locations.

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

Will define a path for the default FreeMarker template loader. If a specified resource cannot be resolved to a `java.io.File`, a generic `SpringTemplateLoader` will be used, without modification detection.

To enforce the use of `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.

If you wish to specify your own list of TemplateLoaders, do not set this property and instead use `setPostTemplateLoaders(TemplateLoader...)`.

See Also:
  - `ResourceEditor`
  - `ResourceLoader.getResource(java.lang.String)`
  - `Configuration.setDirectoryForTemplateLoading(java.io.File)`
  - `SpringTemplateLoader`
  - `setPreferFileSystemAccess(boolean)`

### setResourceLoader

public void setResourceLoader(org.springframework.core.io.ResourceLoader resourceLoader)
Set the `ResourceLoader` to use for loading FreeMarker template files.

The default is `DefaultResourceLoader`. Will get overridden by the `ApplicationContext` if running in a context.

See Also:
  - `DefaultResourceLoader`

### getResourceLoader

protected org.springframework.core.io.ResourceLoader getResourceLoader()
Return the `ResourceLoader` to use for loading FreeMarker template files.

### setPreferFileSystemAccess

public void setPreferFileSystemAccess(boolean preferFileSystemAccess)
Set whether to prefer file system access for template loading.

File system access enables hot detection of template changes.

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

Default is "true". Turn this off to always load via `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.

See Also:
  - `setTemplateLoaderPath(java.lang.String)`

### isPreferFileSystemAccess

protected boolean isPreferFileSystemAccess()
Return whether to prefer file system access for template loading.

### createConfiguration

public freemarker.template.Configuration createConfiguration() throws IOException, freemarker.template.TemplateException
Prepare the FreeMarker `Configuration` and return it.

Returns:
  the FreeMarker `Configuration` object
Throws:
  `IOException` - if the config file wasn't found
  `freemarker.template.TemplateException` - on FreeMarker initialization failure

### newConfiguration

protected freemarker.template.Configuration newConfiguration() throws IOException, freemarker.template.TemplateException
Return a new `Configuration` object.

Subclasses can override this for custom initialization — 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.

Called by `createConfiguration()`.

Returns:
  the `Configuration` object
Throws:
  `IOException` - if a config file wasn't found
  `freemarker.template.TemplateException` - on FreeMarker initialization failure
See Also:
  - `createConfiguration()`

### getTemplateLoaderForPath

protected freemarker.cache.TemplateLoader getTemplateLoaderForPath(String templateLoaderPath)
Determine a FreeMarker `TemplateLoader` for the given path.

Default implementation creates either a `FileTemplateLoader` or a `SpringTemplateLoader`.

Parameters:
  `templateLoaderPath` - the path to load templates from
Returns:
  an appropriate `TemplateLoader`
See Also:
  - `FileTemplateLoader`
  - `SpringTemplateLoader`

### postProcessTemplateLoaders

protected void postProcessTemplateLoaders(List<freemarker.cache.TemplateLoader> templateLoaders)
To be overridden by subclasses that want to register custom `TemplateLoader` instances after this factory created its default template loaders.

Called by `createConfiguration()`. Note that specified "postTemplateLoaders" will be registered after any loaders registered by this callback; as a consequence, they are not included in the given List.

Parameters:
  `templateLoaders` - the current List of TemplateLoader instances, to be modified by a subclass
See Also:
  - `createConfiguration()`
  - `setPostTemplateLoaders(freemarker.cache.TemplateLoader...)`

### getAggregateTemplateLoader

@Nullable protected freemarker.cache.TemplateLoader getAggregateTemplateLoader(List<freemarker.cache.TemplateLoader> templateLoaders)
Return a `TemplateLoader` based on the given `TemplateLoader` list.

If more than one TemplateLoader has been registered, a FreeMarker `MultiTemplateLoader` will be created.

Parameters:
  `templateLoaders` - the final List of `TemplateLoader` instances
Returns:
  the aggregate TemplateLoader

### postProcessConfiguration

protected void postProcessConfiguration(freemarker.template.Configuration config) throws IOException, freemarker.template.TemplateException
To be overridden by subclasses that want to perform custom post-processing of the `Configuration` object after this factory performed its default initialization.

Called by `createConfiguration()`.

Parameters:
  `config` - the current `Configuration` object
Throws:
  `IOException` - if a config file wasn't found
  `freemarker.template.TemplateException` - on FreeMarker initialization failure
See Also:
  - `createConfiguration()`