freemarker.cache
Class TemplateCache

java.lang.Object
  freemarker.cache.TemplateCache

public class TemplateCache
extends java.lang.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.

Version:

$Id: TemplateCache.java,v 1.62.2.2 2007/04/03 18:06:07 szegedia Exp $

Author:

Attila Szegedi, szegedia at freemail dot hu

Constructor Summary

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.

TemplateCache(TemplateLoader loader)
Creates a new template cache with a custom template loader that is used to load the templates.

TemplateCache(TemplateLoader loader, CacheStorage storage)
Creates a new template cache with a custom template loader that is used to load the templates.

Method Summary

void	clear() Removes all entries from the cache, forcing reloading of templates on subsequent getTemplate(String, Locale, String, boolean) calls.
CacheStorage	getCacheStorage()
long	getDelay() Gets the delay in milliseconds between checking for newer versions of a template source.
static java.lang.String	getFullTemplatePath(Environment env, java.lang.String parentTemplateDir, java.lang.String templateNameString)
boolean	getLocalizedLookup() Returns if localized template lookup is enabled or not.
Template	getTemplate(java.lang.String name, java.util.Locale locale, java.lang.String encoding, boolean parse) Loads a template with the given name, in the specified locale and using the specified character encoding.
TemplateLoader	getTemplateLoader()
void	setConfiguration(Configuration config) Sets the configuration object to which this cache belongs.
void	setDelay(long delay) Sets the delay in milliseconds between checking for newer versions of a template sources.
void	setLocalizedLookup(boolean localizedLookup) Setis if localized template lookup is enabled or not.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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 that is used to load the templates.

Parameters:

loader - the template loader 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.

getTemplateLoader

public TemplateLoader getTemplateLoader()

getCacheStorage

public CacheStorage getCacheStorage()

getTemplate

public Template getTemplate(java.lang.String name,
                            java.util.Locale locale,
                            java.lang.String encoding,
                            boolean parse)
                     throws java.io.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.html_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:

java.io.IOException

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.

setLocalizedLookup

public void setLocalizedLookup(boolean localizedLookup)

Setis if localized template lookup is enabled or not.

clear

public void clear()

Removes all entries from the cache, forcing reloading of templates on subsequent getTemplate(String, Locale, String, boolean) calls. If the configured template loader is stateful, then its StatefulTemplateLoader.resetState() method is invoked as well.

getFullTemplatePath

public static java.lang.String getFullTemplatePath(Environment env,
                                                   java.lang.String parentTemplateDir,
                                                   java.lang.String templateNameString)