The Spring Framework

## org.springframework.ui.freemarker
Class FreeMarkerConfigurationFactory

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

Direct Known Subclasses:
  FreeMarkerConfigurationFactoryBean, FreeMarkerConfigurer

    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 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)`, `setTemplateLoaderPath(java.lang.String)`, `createConfiguration()`, `FreeMarkerConfigurationFactoryBean`, `FreeMarkerConfigurer`, `Configuration`

Field Summary
`protected Log` `logger`

Constructor Summary
`FreeMarkerConfigurationFactory()`

Method Summary
`Configuration` `createConfiguration()` Prepare the FreeMarker Configuration and return it.
`protected TemplateLoader` `getAggregateTemplateLoader(List 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(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(List 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(String defaultEncoding)` Set the default encoding for the FreeMarker configuration.
`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 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 `TemplateLoader`s 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 `TemplateLoader`s 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(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.
`void` `setTemplateLoaders(TemplateLoader[] templateLoaders)` Deprecated. as of Spring 2.0.1, in favor of the "preTemplateLoaders" and "postTemplateLoaders" properties

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

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(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 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. 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:
    `Configuration.setDefaultEncoding(java.lang.String)`, `FreeMarkerView.setEncoding(java.lang.String)`

### setTemplateLoaders

    public void setTemplateLoaders(TemplateLoader[] templateLoaders)

  Deprecated. as of Spring 2.0.1, in favor of the "preTemplateLoaders" and "postTemplateLoaders" properties

  Set a List of `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.

  ``
  See Also:
    `setPreTemplateLoaders(freemarker.cache.TemplateLoader[])`, `setPostTemplateLoaders(freemarker.cache.TemplateLoader[])`

### setPreTemplateLoaders

    public void setPreTemplateLoaders(TemplateLoader[] preTemplateLoaders)

  Set a List of `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.

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

  ``
  See Also:
    `setTemplateLoaderPaths(java.lang.String[])`, `postProcessTemplateLoaders(java.util.List)`

### setPostTemplateLoaders

    public void setPostTemplateLoaders(TemplateLoader[] postTemplateLoaders)

  Set a List of `TemplateLoader`s 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)`).

  ``
  See Also:
    `setTemplateLoaderPaths(java.lang.String[])`, `postProcessTemplateLoaders(java.util.List)`

### 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 `setTemplateLoaders(List templateLoaders)`

  See Also:
    `ResourceEditor`, `ResourceLoader.getResource(java.lang.String)`, `Configuration.setDirectoryForTemplateLoading(java.io.File)`, `SpringTemplateLoader`, `setTemplateLoaders(freemarker.cache.TemplateLoader[])`

### 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 IOException,
                                             TemplateException

  Prepare the FreeMarker Configuration and return it.

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

### newConfiguration

    protected Configuration newConfiguration()
                                      throws IOException,
                                             TemplateException

  Return a new Configuration object. Subclasses can override this for custom initialization, or for using a mock object for testing.

  Called by `createConfiguration()`.

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

### getTemplateLoaderForPath

    protected 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 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(freemarker.cache.TemplateLoader[])`

### getAggregateTemplateLoader

    protected TemplateLoader getAggregateTemplateLoader(List 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 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:
    `IOException` - if a config file wasn't found
    `TemplateException` - on FreeMarker initialization failure
  See Also:
    `createConfiguration()`

The Spring Framework

Copyright © 2002-2008 The Spring Framework.