freemarker.template
Class FileTemplateCache

java.lang.Object
  freemarker.template.FileTemplateCache

All Implemented Interfaces:

Cache, RegistryAccepter, Updateable, TemplateCache, TextEncoding

public class FileTemplateCache
extends java.lang.Object
implements TemplateCache, TextEncoding, RegistryAccepter

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.

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 the loading policy is set, 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.

A combination of the two above is LOAD_ON_DEMAND_WITH_REFRESH_CACHE. This loads a template on demand the first time it is requested. Subsequently, it will do periodic refreshes on any templates that have been requested from its cache. This saves memory if some templates are unlikely to be needed, since they won't occupy memory until they are requested, while improving performance over LOAD_ON_DEMAND since it doesn't have to check the file system every time a template is requested.

For maximum flexibility LOAD_AD_HOC mode exists so that all templates are loaded when the loading policy is set but files are not refreshed periodically. Instead, one can write a client that will ask the FileTemplateCache to update a single template via the Updateable.update(String) method. Applications with a large number of templates many of which are not frequently updated will work well with LOAD_AD_HOC mode.

The first argument to the getItem() 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 getItem("foo/index.html") to retrieve that template.

If a second argument is specified in a call to getItem(), this will determine the type of object to be retrieved. The types that can be returned depend on the TemplateRegistry. Three types of object are registered with the TemplateRegistry by default:

• template -- returns a Template object. This is the default type to be retrieved by the cache.
• unparsed -- returns an UnparsedTemplate object. This behaves like other Template objects, but its contents wont be parsed by FM-Classic.
• binary -- returns a BinaryData object. This is useful for caching other file types, such as images.

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 a loading policy is set.

See Also:

TemplateCache, CacheEvent, CacheListener, Updateable.update(String)

Field Summary

static int	LOAD_AD_HOC Used with setLoadingPolicy(int) to indicate that templates are preloaded but there is no automatic updating of them.
static int	LOAD_ON_DEMAND Used with setLoadingPolicy(int) to indicate that templates should be loaded as they are requested.
static int	LOAD_ON_DEMAND_WITH_REFRESH_CACHE Used with setLoadingPolicy(int) to indicate that templates should be loaded as they are requested.
static int	NULL_CACHE Used with setLoadingPolicy(int) to indicate that no files are cached.
static int	PRELOAD Used with setLoadingPolicy(int) to indicate that templates should be preloaded.

Constructor Summary

FileTemplateCache()
Constructs an empty FileTemplateCache.

FileTemplateCache(java.io.File dir)
Constructs a FileTemplateCache with a directory in which it will look for template files.

FileTemplateCache(java.io.File dir, long delay)
Constructs a FileTemplateCache 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 FileTemplateCache with a directory in which it will look for template files.

FileTemplateCache(java.lang.String path, long delay)
Constructs a FileTemplateCache 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 Cache.
CacheListener[]	getCacheListeners() Retrieves all the CacheListeners associated with this cache.
java.lang.String	getDefaultTemplate() Retrieves the default template type to be created when retrieving items from the cache.
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.
Cacheable	getItem(java.lang.String name) Gets the specified template from the cache, using the default template type.
Cacheable	getItem(java.lang.String name, java.lang.String type) Gets the specified template type from the cache.
int	getLoadingPolicy() Returns the loading policy currently in effect
int	getMaximumAge() Retrieves the maximum age a cache item can be before it is evicted from the cache.
java.lang.String	getPath() Returns the template cache root directory.
CacheRetriever	getRetriever() Gets the CacheRetriever currently in use.
TemplateRegistry	getTemplateRegistry() Retrieves the current TemplateRegistry in use.
java.util.Iterator	listCachedFiles() Returns a list of cached files.
void	removeCacheListener(CacheListener listener) Unregisters a CacheListener for a Cache.
void	setDefaultTemplate(java.lang.String aTemplateType) Sets the default template type to be created when retrieving items from the cache.
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	setMaximumAge(int age) Sets the maximum age a cache item can be before it is evicted from the cache.
void	setPath(java.lang.String path) Sets the template cache root directory.
void	setRetriever(CacheRetriever cRetriever) Sets the CacheRetriever to be used for the cache.
void	setTemplateRegistry(TemplateRegistry cRegistry) Sets a TemplateRegistry implementation to use when creating new templates.
void	stopAutoUpdate() Stops the updating of the cache.
java.lang.String	toString() Returns a string representation of the object.
void	update() Updates the cache.
void	update(java.lang.String name) Update a named template if in the LOAD_AD_HOC mode .
void	update(java.lang.String name, java.lang.String type) Update a named template if in the LOAD_AD_HOC mode.

Methods inherited from class java.lang.Object

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

Field Detail

LOAD_ON_DEMAND

public static final int LOAD_ON_DEMAND

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

See Also:

Constant Field Values

PRELOAD

public static final int PRELOAD

Used with setLoadingPolicy(int) to indicate that templates should be preloaded.

See Also:

Constant Field Values

LOAD_AD_HOC

public static final int LOAD_AD_HOC

Used with setLoadingPolicy(int) 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.

See Also:

Constant Field Values

NULL_CACHE

public static final int NULL_CACHE

Used with setLoadingPolicy(int) to indicate that no files are cached.

See Also:

Constant Field Values

LOAD_ON_DEMAND_WITH_REFRESH_CACHE

public static final int LOAD_ON_DEMAND_WITH_REFRESH_CACHE

Used with setLoadingPolicy(int) to indicate that templates should be loaded as they are requested. Once loaded, they are periodically refreshed as per the PRELOAD policy, rather than checked at each request.

See Also:

Constant Field Values

Constructor Detail

FileTemplateCache

public FileTemplateCache()

Constructs an empty FileTemplateCache.

FileTemplateCache

public FileTemplateCache(java.lang.String path)

Constructs a FileTemplateCache with a directory in which it will look for template files.

Parameters:

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

Throws:

java.lang.IllegalArgumentException - the root directory is null

FileTemplateCache

public FileTemplateCache(java.io.File dir)

Constructs a FileTemplateCache with a directory in which it will look for template files.

Parameters:

dir - the directory containing templates for this cache.

Throws:

java.lang.IllegalArgumentException - the root directory is null

FileTemplateCache

public FileTemplateCache(java.lang.String path,
                         long delay)

Constructs a FileTemplateCache 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 FileTemplateCache 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

Throws:

java.lang.IllegalArgumentException - the caching policy is invalid

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.

Throws:

java.lang.IllegalArgumentException - the root directory is null

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

Throws:

java.lang.IllegalArgumentException - the root directory is null

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, LOAD_ON_DEMAND_WITH_REFRESH_CACHE 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, LOAD_ON_DEMAND_WITH_REFRESH_CACHE or PRELOAD.

Returns:

the number of seconds between cache updates

setMaximumAge

public void setMaximumAge(int age)

Sets the maximum age a cache item can be before it is evicted from the cache. The age is determined as the number of cache updates since the item was last accessed. This is meaningful only if the cache policy is set to LOAD_ON_DEMAND or LOAD_ON_DEMAND_WITH_REFRESH_CACHE.

Defaults to never expiring.

Parameters:

age - the maximum age before an item is evicted from the cache, or 0 to indicate that items should never be evicted

getMaximumAge

public int getMaximumAge()

Retrieves the maximum age a cache item can be before it is evicted from the cache. The age is determined as the number of cache updates since the item was last accessed. This is meaningful only if the cache policy is set to LOAD_ON_DEMAND or LOAD_ON_DEMAND_WITH_REFRESH_CACHE.

Returns:

the maximum age before an item is evicted from the cache, or 0 to indicate that items are never evicted

setEncoding

public void setEncoding(java.lang.String encoding)

Sets the character encoding to be used when reading template files. If null is specified, the default encoding will be used.

Specified by:

setEncoding in interface TextEncoding

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. If null is returned, the default encoding is used.

Specified by:

getEncoding in interface TextEncoding

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.

Returns:

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

addCacheListener

public void addCacheListener(CacheListener listener)

Registers a CacheListener for this Cache.

Specified by:

addCacheListener in interface Cache

Parameters:

listener - the CacheListener to be registered.

See Also:

CacheListener

removeCacheListener

public void removeCacheListener(CacheListener listener)

Unregisters a CacheListener for a Cache.

Specified by:

removeCacheListener in interface Cache

Parameters:

listener - the CacheListener to be unregistered.

See Also:

CacheListener

getCacheListeners

public CacheListener[] getCacheListeners()

Retrieves all the CacheListeners associated with this cache.

Specified by:

getCacheListeners in interface Cache

Returns:

an array of CacheListeners

stopAutoUpdate

public void stopAutoUpdate()

Stops the updating of the cache. Normally do this immediately prior to cache destruction.

Specified by:

stopAutoUpdate in interface Cache

listCachedFiles

public java.util.Iterator listCachedFiles()

Returns a list of cached files.

Specified by:

listCachedFiles in interface Cache

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 Updateable

Parameters:

name - of template to update

update

public void update(java.lang.String name,
                   java.lang.String type)

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

Specified by:

update in interface Updateable

Parameters:

name - the name of template to update

type - the type of template to update

update

public void update()

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

Specified by:

update in interface Updateable

getItem

public Cacheable getItem(java.lang.String name)

Gets the specified template from the cache, using the default template type.

Specified by:

getItem in interface Cache

Parameters:

name - a string uniquely identifying the template.

Returns:

the template corresponding to the name, or null if not found.

See Also:

setDefaultTemplate(java.lang.String)

getItem

public Cacheable getItem(java.lang.String name,
                         java.lang.String type)

Gets the specified template type from the cache.

Specified by:

getItem in interface Cache

Parameters:

name - a string uniquely identifying the template.

type - the type of template to be retrieved

Returns:

the template corresponding to the name, or null if not found.

See Also:

setDefaultTemplate(java.lang.String)

getRetriever

public CacheRetriever getRetriever()

Gets the CacheRetriever currently in use.

Returns:

the CacheRetriever used for retrieving templates

setRetriever

public void setRetriever(CacheRetriever cRetriever)

Sets the CacheRetriever to be used for the cache.

Parameters:

cRetriever - the CacheRetriever to be used for retrieving templates

getTemplateRegistry

public TemplateRegistry getTemplateRegistry()

Retrieves the current TemplateRegistry in use.

Specified by:

getTemplateRegistry in interface RegistryAccepter

Returns:

the TemplateRegistry to used when retrieving items to be cached

setTemplateRegistry

public void setTemplateRegistry(TemplateRegistry cRegistry)

Sets a TemplateRegistry implementation to use when creating new templates.

Specified by:

setTemplateRegistry in interface RegistryAccepter

Parameters:

cRegistry - the TemplateRegistry to be used when retrieving items to be cached

getDefaultTemplate

public java.lang.String getDefaultTemplate()

Retrieves the default template type to be created when retrieving items from the cache.

Returns:

the type of template cached by default

setDefaultTemplate

public void setDefaultTemplate(java.lang.String aTemplateType)

Sets the default template type to be created when retrieving items from the cache. The types that can be set depend on the TemplateRegistry. Three types of object are registered with the TemplateRegistry by default:

• template -- returns a Template object.
• unparsed -- returns an UnparsedTemplate object. This behaves like other Template objects, but its contents wont be parsed by FM-Classic.
• binary -- returns a BinaryData object. This is useful for caching other file types, such as images.

Parameters:

aTemplateType - the type of template to be cached by default

toString

public java.lang.String toString()

Returns a string representation of the object.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of the object.