freemarker.template
Class FileTemplateCache

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

All Implemented Interfaces:

TemplateCache, Updatable

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 PRELOAD with a long delay value for maximum performance.

For maximum flexibility LOAD_AD_HOC mode exists so that all templates are loaded when startAutoUpdate is called but files are not refreshed periodically. Instead, one can write a client that will ask the FileTemplateCache to update a single template via the Updatable#update(String name) method. Applications with a large number of templates many of which are not frequently updated will work well with LOAD_AD_HOC mode. Since templates are updated 'ad hoc' in this mode rather than periodically calling startAutoUpdate() is not required.

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 the CacheListener interface 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, Updatable.update(String)

Field Summary

protected java.io.File	cacheDir
static int	LOAD_AD_HOC Used with setLoadingPolicy() to indicate that templates are preloaded but there is no automatic updating of them.
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) Registers a CacheListener for this TemplateCache.
long	getDelay() Returns the interval between two cache updates.
java.io.File	getDirectory() Returns the template cache root directory
java.lang.String	getEncoding() Returns the character encoding to be used when reading template files.
java.lang.String	getFilenameSuffix() Returns the template suffix.
int	getLoadingPolicy() Returns the loading policy currently in effect
java.lang.String	getPath() Returns the template cache root directory
Template	getTemplate(java.lang.String name) Gets a template from the cache
java.util.Iterator	listCachedFiles() Returns a list of cached files
void	removeCacheListener(CacheListener listener) Unregisters a CacheListener for this TemplateCache.
void	setDelay(long delay) Sets the interval between two cache updates.
void	setDirectory(java.io.File dir) Sets the template cache root directory
void	setEncoding(java.lang.String encoding) Sets the character encoding to be used when reading template files.
void	setFilenameSuffix(java.lang.String filenameSuffix) Sets the template suffix.
void	setLoadingPolicy(int loadingPolicy) Sets the loading policy for this FileTemplateCache.
void	setPath(java.lang.String path) Sets the template cache root directory
void	startAutoUpdate() Note: startAutoUpdate() is deprecated.
void	stopAutoUpdate() Note: startAutoUpdate() is deprecated.
void	update() Updates the cache.
void	update(java.lang.String name) Update a named template if in the LOAD_AD_HOC mode Do nothing if in other modes

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.

LOAD_AD_HOC

public static final int LOAD_AD_HOC

Used with setLoadingPolicy() to indicate that templates are preloaded but there is no automatic updating of them. Instead, only named templates are updated when the cache is requested to do so.

cacheDir

protected java.io.File cacheDir

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

getLoadingPolicy

public int getLoadingPolicy()

Returns the loading policy currently in effect

Returns:

a loading policy value

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. If LOAD_AD_HOC, all templates in the cache directory and its subdirectories will be loaded when the cache is created and a particular template file's modification date will be checked each time the client requests the update of that and only that template. Defaults to LOAD_ON_DEMAND.

Parameters:

loadingPolicy - cache mode

setPath

public void setPath(java.lang.String path)

Sets the template cache root directory

Parameters:

path - the absolute path of the directory containing templates for this cache.

getPath

public java.lang.String getPath()

Returns the template cache root directory

Returns:

the absolute path of the directory containing templates for this cache.

setDirectory

public void setDirectory(java.io.File dir)

Sets the template cache root directory

Parameters:

dir - the root directory containing templates for this cache

getDirectory

public java.io.File getDirectory()

Returns the template cache root directory

Returns:

the root directory containing templates for this cache

setDelay

public void setDelay(long delay)

Sets the interval between two cache updates. This is meaningful only if the cache policy is set to LOAD_ON_DEMAND or PRELOAD. Defaults to five seconds.

Parameters:

delay - the number of seconds between cache updates

getDelay

public long getDelay()

Returns the interval between two cache updates. This is meaningful only if the cache policy is set to LOAD_ON_DEMAND or PRELOAD.

Returns:

the number of seconds between cache updates

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.

getEncoding

public java.lang.String getEncoding()

Returns the character encoding to be used when reading template files.

Returns:

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)

Sets the template suffix. If set, files that do not have this suffix will be ignored when read into the cache.

Parameters:

filenameSuffix - the optional filename suffix of template files to be read for this cache.

getFilenameSuffix

public java.lang.String getFilenameSuffix()

Returns the template suffix. If set, files that do not have this suffix will be ignored when read into the cache.

Parameters:

the - optional filename suffix of template files to be read for this cache.

addCacheListener

public void addCacheListener(CacheListener listener)

Description copied from interface: TemplateCache

Registers a CacheListener for this TemplateCache.

Specified by:

addCacheListener in interface TemplateCache

Following copied from interface: freemarker.template.TemplateCache

Parameters:

CacheListener - the CacheListener to be registered.

See Also:

CacheListener

removeCacheListener

public void removeCacheListener(CacheListener listener)

Description copied from interface: TemplateCache

Unregisters a CacheListener for this TemplateCache.

Specified by:

removeCacheListener in interface TemplateCache

Following copied from interface: freemarker.template.TemplateCache

Parameters:

CacheListener - the CacheListener to be unregistered.

See Also:

CacheListener

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 or an error has occurred

startAutoUpdate

public void startAutoUpdate()

Description copied from interface: TemplateCache

Note: startAutoUpdate() is deprecated. An implementation will automatically call startAutoUpdate() or its equivalent internally as determined by the caching policy

Begins automatic updates of the cache.

Specified by:

startAutoUpdate in interface TemplateCache

stopAutoUpdate

public void stopAutoUpdate()

Description copied from interface: TemplateCache

Note: startAutoUpdate() is deprecated. An implementation will automatically call startAutoUpdate() or its equivalent internally as determined by the caching policy

Stops automatically updating the cache.

Specified by:

stopAutoUpdate in interface TemplateCache

listCachedFiles

public java.util.Iterator listCachedFiles()

Returns a list of cached files

Specified by:

listCachedFiles in interface TemplateCache

Returns:

a list of cached files

update

public void update(java.lang.String name)

Update a named template if in the LOAD_AD_HOC mode Do nothing if in other modes

Specified by:

update in interface Updatable

Parameters:

name - of template to update

update

public void update()

Updates the cache. In LOAD_AD_HOC mode, this does nothing.

Specified by:

update in interface Updatable