Package freemarker.cache

Class TemplateCache

  • public class TemplateCache
extends Object
    A class that performs caching and on-demand loading of the templates. The actual loading is delegated to a TemplateLoader. Also, various constructors provide you with convenient caches with predefined behavior. Typically you don't use this class directly - in normal circumstances it is hidden behind a Configuration.

    • Constructor Detail

      • TemplateCache

        public TemplateCache()
        Returns a template cache that will first try to load a template from the file system relative to the current user directory (i.e. the value of the system property user.dir), then from the classpath. This default template cache suits many applications.

      • TemplateCache

        public TemplateCache​(TemplateLoader loader)
        Creates a new template cache with a custom template loader that is used to load the templates.
        Parameters:
        loader - the template loader to use.

      • TemplateCache

        public TemplateCache​(TemplateLoader loader,
                     CacheStorage storage)
        Creates a new template cache with a custom template loader and cache storage that are used to load and store the templates.
        Parameters:
        loader - the template loader to use.
        storage - the cache storage to use

    • Method Detail

      • setConfiguration

        public void setConfiguration​(Configuration config)
        Sets the configuration object to which this cache belongs. This method is called by the configuration itself to establish the relation, and should not be called by users.
        Parameters:
        config - the configuration that this cache belongs to

      • getTemplateLoader

        public TemplateLoader getTemplateLoader()
        Returns the template loader used by this cache.
        Returns:
        the template loader used by this cache.

      • getCacheStorage

        public CacheStorage getCacheStorage()
        Returns the cache storage used by this cache.
        Returns:
        the cache storage used by this cache.

      • getTemplate

        public Template getTemplate​(String name,
                            Locale locale,
                            String encoding,
                            boolean parse)
                     throws IOException
        Loads a template with the given name, in the specified locale and using the specified character encoding.
        Parameters:
        name - the name of the template. Can't be null. The exact syntax of the name is interpreted by the underlying TemplateLoader, but the cache makes some assumptions. First, the name is expected to be a hierarchical path, with path components separated by a slash character (not with backslash!). The path (the name) must not begin with slash; the path is always relative to the "template root directory". Then, the .. and . path metaelements will be resolved. For example, if the name is a/../b/./c.ftl, then it will be simplified to b/c.ftl. The rules regarding this are same as with conventional UN*X paths. The path must not reach outside the template root directory, that is, it can't be something like "../templates/my.ftl" (not even if the pervious path happens to be equivalent with "/my.ftl"). Further, the path is allowed to contain at most one path element whose name is * (asterisk). This path metaelement triggers the acquisition mechanism. If the template is not found in the location described by the concatenation of the path left to the asterisk (called base path) and the part to the right of the asterisk (called resource path), the cache will attempt to remove the rightmost path component from the base path ("go up one directory") and concatenate that with the resource path. The process is repeated until either a template is found, or the base path is completely exhausted.
        locale - the requested locale of the template. Can't be null. Assuming you have specified en_US as the locale and myTemplate.html as the name of the template, the cache will first try to retrieve myTemplate_en_US.html, then myTemplate_en.html, and finally myTemplate.html.
        encoding - the character encoding used to interpret the template source bytes. Can't be null.
        parse - if true, the loaded template is parsed and interpreted as a regular FreeMarker template. If false, the loaded template is treated as an unparsed block of text.
        Returns:
        the loaded template, or null if the template is not found.
        Throws:
        IOException - if an I/O exception occurs while loading the template

      • getDelay

        public long getDelay()
        Gets the delay in milliseconds between checking for newer versions of a template source.
        Returns:
        the current value of the delay

      • setDelay

        public void setDelay​(long delay)
        Sets the delay in milliseconds between checking for newer versions of a template sources.
        Parameters:
        delay - the new value of the delay

      • getLocalizedLookup

        public boolean getLocalizedLookup()
        Returns if localized template lookup is enabled or not.
        Returns:
        true if localized template lookup is enabled, false otherwise.

      • setLocalizedLookup

        public void setLocalizedLookup​(boolean localizedLookup)
        Sets whether to enable localized template lookup or not.
        Parameters:
        localizedLookup - true to enable localized template lookup, false to disable it.

      • getFullTemplatePath

        public static String getFullTemplatePath​(Environment env,
                                         String parentTemplateDir,
                                         String templateNameString)
        Resolves a relative template path to absolute template path for purposes of an inclusion via the include directive. Can only be invoked during template processing.
        Parameters:
        env - the Environment associated with the current thread.
        parentTemplateDir - the absolute directory path of the template containing the include directive.
        templateNameString - the potentially relative path specified in the include directive.
        Returns:
        the absolute path resolved against the specified parent directory.