org.springframework.ui.freemarker

Class FreeMarkerConfigurationFactory

java.lang.Object

org.springframework.ui.freemarker.FreeMarkerConfigurationFactory

Direct Known Subclasses:

FreeMarkerConfigurationFactoryBean, FreeMarkerConfigurer

public class FreeMarkerConfigurationFactory
extends java.lang.Object

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.

Since:

03.03.2004

Author:

Darren Davison, Juergen Hoeller

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, FreeMarkerConfigurer, freemarker.template.Configuration

Field Summary

Fields

Modifier and Type	Field and Description
private Resource	configLocation
private java.lang.String	defaultEncoding
private java.util.Properties	freemarkerSettings
private java.util.Map<java.lang.String,java.lang.Object>	freemarkerVariables
protected Log	logger
private java.util.List<TemplateLoader>	postTemplateLoaders
private boolean	preferFileSystemAccess
private java.util.List<TemplateLoader>	preTemplateLoaders
private ResourceLoader	resourceLoader
private java.lang.String[]	templateLoaderPaths
private java.util.List<TemplateLoader>	templateLoaders

Constructor Summary

Constructors

Constructor and Description
FreeMarkerConfigurationFactory()

Method Summary

Modifier and Type	Method and Description
Configuration	createConfiguration() Prepare the FreeMarker Configuration and return it.
protected TemplateLoader	getAggregateTemplateLoader(java.util.List<TemplateLoader> 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 TemplateLoader	getTemplateLoaderForPath(java.lang.String templateLoaderPath) Determine a FreeMarker TemplateLoader for the given path.
protected boolean	isPreferFileSystemAccess() Return whether to prefer file system access for template loading.
protected Configuration	newConfiguration() Return a new Configuration object.
protected void	postProcessConfiguration(Configuration config) To be overridden by subclasses that want to to perform custom post-processing of the Configuration object after this factory performed its default initialization.
protected void	postProcessTemplateLoaders(java.util.List<TemplateLoader> templateLoaders) To be overridden by subclasses that want to to register custom TemplateLoader instances after this factory created its default template loaders.
void	setConfigLocation(Resource resource) Set the location of the FreeMarker config file.
void	setDefaultEncoding(java.lang.String defaultEncoding) Set the default encoding for the FreeMarker configuration.
void	setFreemarkerSettings(java.util.Properties settings) Set properties that contain well-known FreeMarker keys which will be passed to FreeMarker's Configuration.setSettings method.
void	setFreemarkerVariables(java.util.Map<java.lang.String,java.lang.Object> variables) Set a Map that contains well-known FreeMarker objects which will be passed to FreeMarker's Configuration.setAllSharedVariables() method.
void	setPostTemplateLoaders(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(TemplateLoader... preTemplateLoaders) Set a List of TemplateLoaders that will be used to search for templates.
void	setResourceLoader(ResourceLoader resourceLoader) Set the Spring ResourceLoader to use for loading FreeMarker template files.
void	setTemplateLoaderPath(java.lang.String templateLoaderPath) Set the Freemarker template loader path via a Spring resource location.
void	setTemplateLoaderPaths(java.lang.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 Detail

logger

protected final Log logger

configLocation

private Resource configLocation

freemarkerSettings

private java.util.Properties freemarkerSettings

freemarkerVariables

private java.util.Map<java.lang.String,java.lang.Object> freemarkerVariables

defaultEncoding

private java.lang.String defaultEncoding

templateLoaders

private final java.util.List<TemplateLoader> templateLoaders

preTemplateLoaders

private java.util.List<TemplateLoader> preTemplateLoaders

postTemplateLoaders

private java.util.List<TemplateLoader> postTemplateLoaders

templateLoaderPaths

private java.lang.String[] templateLoaderPaths

resourceLoader

private ResourceLoader resourceLoader

preferFileSystemAccess

private boolean preferFileSystemAccess

Constructor Detail

FreeMarkerConfigurationFactory

public FreeMarkerConfigurationFactory()

Method Detail

setConfigLocation

public void setConfigLocation(Resource resource)

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

See Also:

setFreemarkerSettings(java.util.Properties), setTemplateLoaderPath(java.lang.String)

setFreemarkerSettings

public void setFreemarkerSettings(java.util.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

setFreemarkerVariables

public void setFreemarkerVariables(java.util.Map<java.lang.String,java.lang.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

setDefaultEncoding

public void setDefaultEncoding(java.lang.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, FreeMarkerView.setEncoding(java.lang.String)

setPreTemplateLoaders

public void setPreTemplateLoaders(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<TemplateLoader>)).

See Also:

setTemplateLoaderPaths(java.lang.String...), postProcessTemplateLoaders(java.util.List<TemplateLoader>)

setPostTemplateLoaders

public void setPostTemplateLoaders(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(java.util.List<TemplateLoader>)).

See Also:

setTemplateLoaderPaths(java.lang.String...), postProcessTemplateLoaders(java.util.List<TemplateLoader>)

setTemplateLoaderPath

public void setTemplateLoaderPath(java.lang.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(java.lang.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:

ResourceEditor, ResourceLoader.getResource(java.lang.String), freemarker.template.Configuration#setDirectoryForTemplateLoading, SpringTemplateLoader

setResourceLoader

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:

DefaultResourceLoader

getResourceLoader

protected ResourceLoader getResourceLoader()

Return the Spring 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 Configuration createConfiguration()
                                  throws java.io.IOException,
                                         TemplateException

Prepare the FreeMarker Configuration and return it.

Returns:

the FreeMarker Configuration object

Throws:

java.io.IOException - if the config file wasn't found

TemplateException - on FreeMarker initialization failure

newConfiguration

protected Configuration newConfiguration()
                                  throws java.io.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.

Called by createConfiguration().

Returns:

the Configuration object

Throws:

java.io.IOException - if a config file wasn't found

TemplateException - on FreeMarker initialization failure

See Also:

createConfiguration()

getTemplateLoaderForPath

protected TemplateLoader getTemplateLoaderForPath(java.lang.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:

freemarker.cache.FileTemplateLoader, SpringTemplateLoader

postProcessTemplateLoaders

protected void postProcessTemplateLoaders(java.util.List<TemplateLoader> templateLoaders)

To be overridden by subclasses that want to 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 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(TemplateLoader...)

getAggregateTemplateLoader

protected TemplateLoader getAggregateTemplateLoader(java.util.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.

Parameters:

templateLoaders - the final List of TemplateLoader instances

Returns:

the aggregate TemplateLoader

postProcessConfiguration

protected void postProcessConfiguration(Configuration config)
                                 throws java.io.IOException,
                                        TemplateException

To be overridden by subclasses that want to 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:

java.io.IOException - if a config file wasn't found

TemplateException - on FreeMarker initialization failure

See Also:

createConfiguration()