freemarker.template
Class FileTemplateCache

java.lang.Object
  |
  +--freemarker.template.FileTemplateCache
All Implemented Interfaces:
Cache, RegistryAccepter, TemplateCache, TextEncoding, Updateable

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:

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.

Version:
$Id: FileTemplateCache.java,v 1.30 2003/11/27 08:03:43 run2000 Exp $
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.

PRELOAD

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

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.

NULL_CACHE

public static final int NULL_CACHE
Used with setLoadingPolicy(int) to indicate that no files are cached.

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.
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
Following copied from interface: freemarker.template.cache.Updateable
Throws:
java.lang.InterruptedException - The current thread was interrupted during the update. Callers should either throw the exception back up the call stack, or set the interrupted status by using the Thread.currentThread().interrupt() method.

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:
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.