Top Description Fields Constructors Methods
org.springframework.ui.freemarker

public Class FreeMarkerConfigurationFactory

extends Object
Class Inheritance
Known Direct Subclasses
org.springframework.ui.freemarker.FreeMarkerConfigurationFactoryBean
Imports
java.io.File, .IOException, java.util.ArrayList, .Arrays, .List, .Map, .Properties, freemarker.cache.FileTemplateLoader, freemarker.cache.MultiTemplateLoader, freemarker.cache.TemplateLoader, freemarker.template.Configuration, freemarker.template.SimpleHash, freemarker.template.TemplateException, org.apache.commons.logging.Log, .LogFactory, org.springframework.core.io.DefaultResourceLoader, .Resource, .ResourceLoader, org.springframework.core.io.support.PropertiesLoaderUtils, org.springframework.lang.Nullable, 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.

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 or higher.

Authors
Darren Davison, Juergen Hoeller
Since
03.03.2004
See Also
setConfigLocation, setFreemarkerSettings, setFreemarkerVariables, setTemplateLoaderPath, createConfiguration, FreeMarkerConfigurationFactoryBean, org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer, freemarker.template.Configuration

Field Summary

Modifier and TypeField and Description
private Resource
configLocation

private String
defaultEncoding

private Properties
freemarkerSettings

private Map<String, Object>
freemarkerVariables

protected final Log
logger

private List<freemarker.cache.TemplateLoader>
postTemplateLoaders

private boolean
preferFileSystemAccess

private List<freemarker.cache.TemplateLoader>
preTemplateLoaders

private ResourceLoader
resourceLoader

private String[]
templateLoaderPaths

private final List<freemarker.cache.TemplateLoader>
templateLoaders

Constructor Summary

AccessConstructor and Description
public
FreeMarkerConfigurationFactory()

Method Summary

Modifier and TypeMethod and Description
public freemarker.template.Configuration

Returns:

the FreeMarker Configuration object
createConfiguration()

Prepare the FreeMarker Configuration and return it.

protected freemarker.cache.TemplateLoader

Returns:

the aggregate TemplateLoader
getAggregateTemplateLoader(List<freemarker.cache.TemplateLoader>
the final List of TemplateLoader instances
templateLoaders)

Return a TemplateLoader based on the given TemplateLoader list.

protected ResourceLoader
getResourceLoader()

Return the Spring ResourceLoader to use for loading FreeMarker template files.

protected freemarker.cache.TemplateLoader

Returns:

an appropriate TemplateLoader
getTemplateLoaderForPath(String
the path to load templates from
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

Returns:

the Configuration object
newConfiguration()

Return a new Configuration object.

protected void
postProcessConfiguration(freemarker.template.Configuration
the current Configuration object
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>
the current List of TemplateLoader instances, to be modified by a subclass
templateLoaders)

To be overridden by subclasses that want to register custom TemplateLoader instances after this factory created its default template loaders.

public void
setConfigLocation(Resource resource)

Set the location of the FreeMarker config file.

public void
setDefaultEncoding(String defaultEncoding)

Set the default encoding for the FreeMarker configuration.

public void
setFreemarkerSettings(Properties settings)

Set properties that contain well-known FreeMarker keys which will be passed to FreeMarker's Configuration.setSettings method.

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.

public void
setPostTemplateLoaders(freemarker.cache.TemplateLoader... postTemplateLoaders)

Set a List of TemplateLoaders that will be used to search for templates.

public void
setPreferFileSystemAccess(boolean preferFileSystemAccess)

Set whether to prefer file system access for template loading.

public void
setPreTemplateLoaders(freemarker.cache.TemplateLoader... preTemplateLoaders)

Set a List of TemplateLoaders that will be used to search for templates.

public void
setResourceLoader(ResourceLoader resourceLoader)

Set the Spring ResourceLoader to use for loading FreeMarker template files.

public void
setTemplateLoaderPath(String templateLoaderPath)

Set the Freemarker template loader path via a Spring resource location.

public void
setTemplateLoaderPaths(String... templateLoaderPaths)

Set multiple Freemarker template loader paths via Spring resource locations.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

configLocationback to summary
private Resource configLocation
Annotations
@Nullable
defaultEncodingback to summary
private String defaultEncoding
Annotations
@Nullable
freemarkerSettingsback to summary
private Properties freemarkerSettings
Annotations
@Nullable
freemarkerVariablesback to summary
private Map<String, Object> freemarkerVariables
Annotations
@Nullable
loggerback to summary
protected final Log logger
postTemplateLoadersback to summary
private List<freemarker.cache.TemplateLoader> postTemplateLoaders
Annotations
@Nullable
preferFileSystemAccessback to summary
private boolean preferFileSystemAccess
preTemplateLoadersback to summary
private List<freemarker.cache.TemplateLoader> preTemplateLoaders
Annotations
@Nullable
resourceLoaderback to summary
private ResourceLoader resourceLoader
templateLoaderPathsback to summary
private String[] templateLoaderPaths
Annotations
@Nullable
templateLoadersback to summary
private final List<freemarker.cache.TemplateLoader> templateLoaders

Constructor Detail

FreeMarkerConfigurationFactoryback to summary
public FreeMarkerConfigurationFactory()

Method Detail

createConfigurationback to summary
public freemarker.template.Configuration createConfiguration() throws IOException, freemarker.template.TemplateException

Prepare the FreeMarker Configuration and return it.

Returns:freemarker.template.Configuration

the FreeMarker Configuration object

Exceptions
IOException:
if the config file wasn't found
TemplateException:
on FreeMarker initialization failure
getAggregateTemplateLoaderback to summary
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 needs to be created.

Parameters
templateLoaders:List<freemarker.cache.TemplateLoader>

the final List of TemplateLoader instances

Returns:freemarker.cache.TemplateLoader

the aggregate TemplateLoader

Annotations
@Nullable
getResourceLoaderback to summary
protected ResourceLoader getResourceLoader()

Return the Spring ResourceLoader to use for loading FreeMarker template files.

getTemplateLoaderForPathback to summary
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:String

the path to load templates from

Returns:freemarker.cache.TemplateLoader

an appropriate TemplateLoader

See Also
freemarker.cache.FileTemplateLoader, SpringTemplateLoader
isPreferFileSystemAccessback to summary
protected boolean isPreferFileSystemAccess()

Return whether to prefer file system access for template loading.

newConfigurationback to summary
protected freemarker.template.Configuration newConfiguration() throws IOException, freemarker.template.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.

Called by createConfiguration().

Returns:freemarker.template.Configuration

the Configuration object

Exceptions
IOException:
if a config file wasn't found
TemplateException:
on FreeMarker initialization failure
See Also
createConfiguration()
postProcessConfigurationback to summary
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:freemarker.template.Configuration

the current Configuration object

Exceptions
IOException:
if a config file wasn't found
TemplateException:
on FreeMarker initialization failure
See Also
createConfiguration()
postProcessTemplateLoadersback to summary
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:List<freemarker.cache.TemplateLoader>

the current List of TemplateLoader instances, to be modified by a subclass

See Also
createConfiguration(), setPostTemplateLoaders
setConfigLocationback to summary
public void setConfigLocation(Resource resource)

Set the location of the FreeMarker config file. Alternatively, you can specify all setting locally.

See Also
setFreemarkerSettings, setTemplateLoaderPath
setDefaultEncodingback to summary
public void setDefaultEncoding(String defaultEncoding)

Set the default encoding for the FreeMarker configuration. If not specified, FreeMarker will use the platform file encoding.

Used for template rendering unless there is an explicit encoding specified for the rendering process (for example, on Spring's FreeMarkerView).

See Also
freemarker.template.Configuration#setDefaultEncoding, org.springframework.web.servlet.view.freemarker.FreeMarkerView#setEncoding
setFreemarkerSettingsback to summary
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
freemarker.template.Configuration#setSettings
setFreemarkerVariablesback to summary
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
freemarker.template.Configuration#setAllSharedVariables
setPostTemplateLoadersback to summary
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 can be configured.

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

See Also
setTemplateLoaderPaths, postProcessTemplateLoaders
setPreferFileSystemAccessback to summary
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
setPreTemplateLoadersback to summary
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).

See Also
setTemplateLoaderPaths, postProcessTemplateLoaders
setResourceLoaderback to summary
public void setResourceLoader(ResourceLoader resourceLoader)

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.

See Also
org.springframework.core.io.DefaultResourceLoader
setTemplateLoaderPathback to summary
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
setTemplateLoaderPathsback to summary
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 setTemplateLoaders(List templateLoaders)

See Also
org.springframework.core.io.ResourceEditor, org.springframework.context.ApplicationContext#getResource, freemarker.template.Configuration#setDirectoryForTemplateLoading, SpringTemplateLoader