freemarker.template
Class FileTemplateCache

java.lang.Object
  |
  +--freemarker.template.FileTemplateCache

public class FileTemplateCache
extends java.lang.Object
implements TemplateCache, Updatable

A TemplateCache that loads templates from a filesystem. Given a directory path, the cache assumes by default that all files in the directory are templates. It can optionally be given a filename suffix for templates. Before using a FileTemplateCache, you must call its startAutoUpdate() method to begin periodic updates. The default loading policy is LOAD_ON_DEMAND: templates are loaded into the cache only when requested, each template's modification date is checked each time it is requested, and the periodic updates are used only to remove deleted templates from the cache. If the loading policy is set to PRELOAD, all templates are loaded when startAutoUpdate() is called, and all files are checked during each periodic update. If template files will not be changed frequently, use LOAD_ON_DEMAND with a long delay value for maximum performance.

The string argument to the getTemplate() method is interpreted as the template's path relative to the cache's root directory, using a forward slash (/) as a separator (this is to facilitate using URL path info to request templates). For example, if a TemplateCache object was made for the directory templates, which contains a subdirectory foo, in which there is a template file called index.html, you would call getTemplate("foo/index.html") to retrieve that template.

The owner of the cache should implement CacheListener, and register itself using addCacheListener().

If the template cannot read its cache directory, the periodic updates will be cancelled until the next time startAutoUpdate() is called.

See Also:
TemplateCache, CacheListener

Field Summary
static int LOAD_ON_DEMAND
          Used with setLoadingPolicy() to indicate that templates should be loaded as they are requested.
static int PRELOAD
          Used with setLoadingPolicy() to indicate that templates should be preloaded.
 
Constructor Summary
FileTemplateCache()
          Constructs an empty FileTemplateCache.
FileTemplateCache(java.io.File dir)
          Constructs a TemplateCache with a directory in which it will look for template files.
FileTemplateCache(java.io.File dir, long delay)
          Constructs a TemplateCache with a directory in which it will look for template files, and a delay representing the number of seconds between cache updates.
FileTemplateCache(java.lang.String path)
          Constructs a TemplateCache with a directory in which it will look for template files.
FileTemplateCache(java.lang.String path, long delay)
          Constructs a TemplateCache with a directory in which it will look for template files, and a delay representing the number of seconds between cache updates.
 
Method Summary
 void addCacheListener(CacheListener listener)
           
 Template getTemplate(java.lang.String name)
          Gets a template from the cache.
 void removeCacheListener(CacheListener listener)
           
 void setDelay(long delay)
           
 void setDirectory(java.io.File dir)
           
 void setEncoding(java.lang.String encoding)
          Sets the character encoding to be used when reading template files.
 void setFilenameSuffix(java.lang.String filenameSuffix)
           
 void setLoadingPolicy(int loadingPolicy)
          Sets the loading policy for this FileTemplateCache.
 void setPath(java.lang.String path)
           
 void startAutoUpdate()
           
 void stopAutoUpdate()
           
 void update()
          Updates the cache.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

LOAD_ON_DEMAND

public static final int LOAD_ON_DEMAND
Used with setLoadingPolicy() to indicate that templates should be loaded as they are requested.

PRELOAD

public static final int PRELOAD
Used with setLoadingPolicy() to indicate that templates should be preloaded.
Constructor Detail

FileTemplateCache

public FileTemplateCache()
Constructs an empty FileTemplateCache.

FileTemplateCache

public FileTemplateCache(java.lang.String path)
Constructs a TemplateCache with a directory in which it will look for template files.
Parameters:
path - the absolute path of the directory containing templates for this cache.

FileTemplateCache

public FileTemplateCache(java.io.File dir)
Constructs a TemplateCache with a directory in which it will look for template files.
Parameters:
dir - the directory containing templates for this cache.

FileTemplateCache

public FileTemplateCache(java.lang.String path,
                         long delay)
Constructs a TemplateCache with a directory in which it will look for template files, and a delay representing the number of seconds between cache updates.
Parameters:
path - the absolute path of the directory containing templates for this cache.
delay - the number of seconds between cache updates.

FileTemplateCache

public FileTemplateCache(java.io.File dir,
                         long delay)
Constructs a TemplateCache with a directory in which it will look for template files, and a delay representing the number of seconds between cache updates.
Parameters:
dir - the directory containing templates for this cache.
delay - the number of seconds between cache updates.
Method Detail

setLoadingPolicy

public void setLoadingPolicy(int loadingPolicy)
Sets the loading policy for this FileTemplateCache. If LOAD_ON_DEMAND, templates will be loaded as they are requested, and each template's file modification date will be checked each time it is requested. If PRELOAD, all templates in the cache directory and its subdirectories will be loaded when the cache is started, and new templates will be added to the cache each time it is updated. Defaults to LOAD_ON_DEMAND.

setPath

public void setPath(java.lang.String path)
Parameters:
path - the absolute path of the directory containing templates for this cache.

setDirectory

public void setDirectory(java.io.File dir)
Parameters:
dir - the directory containing templates for this cache.

setDelay

public void setDelay(long delay)
Parameters:
delay - the number of seconds between cache updates. Defaults to five seconds.

setEncoding

public void setEncoding(java.lang.String encoding)
Sets the character encoding to be used when reading template files.
Parameters:
encoding - the name of the encoding to be used; this will be passed to the constructor of InputStreamReader.

setFilenameSuffix

public void setFilenameSuffix(java.lang.String filenameSuffix)
Parameters:
filenameSuffix - the optional filename suffix of template files to be read for this cache. If this suffix is set, files that do not have the suffix will be ignored.

addCacheListener

public void addCacheListener(CacheListener listener)
Specified by:
addCacheListener in interface TemplateCache

removeCacheListener

public void removeCacheListener(CacheListener listener)
Specified by:
removeCacheListener in interface TemplateCache

getTemplate

public Template getTemplate(java.lang.String name)
Gets a template from the cache.
Specified by:
getTemplate in interface TemplateCache
Parameters:
name - the template's filename, including its path relative to the cache's root directory.
Returns:
the corresponding Template, or null if not found.

startAutoUpdate

public void startAutoUpdate()
Specified by:
startAutoUpdate in interface TemplateCache

stopAutoUpdate

public void stopAutoUpdate()
Specified by:
stopAutoUpdate in interface TemplateCache

update

public void update()
Updates the cache.
Specified by:
update in interface Updatable