Package org.springframework.ui.freemarker

Class FreeMarkerConfigurationFactory

java.lang.Object
org.springframework.ui.freemarker.FreeMarkerConfigurationFactory
Direct Known Subclasses:
FreeMarkerConfigurationFactoryBean, FreeMarkerConfigurer, 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 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:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final 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 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(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(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 Log logger

  • Constructor Details

    • FreeMarkerConfigurationFactory

      public FreeMarkerConfigurationFactory()

  • Method Details

    • setConfigLocation

      public void setConfigLocation(Resource resource)
      Set the location of the FreeMarker config file.

      Alternatively, you can specify all settings locally.

      See Also:

    • 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

      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:

    • 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:

    • 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:

    • 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

      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:

    • setResourceLoader

      public void setResourceLoader(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:

    • getResourceLoader

      protected 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:

    • 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:

    • 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:

    • 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:

    • 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: