freemarker.template
Class FileBinaryCache

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

All Implemented Interfaces:

BinaryCache, Updatable

public class FileBinaryCache

extends java.lang.Object

implements BinaryCache, Updatable

A BinaryCache that loads binary files from a filesystem. Given a directory path, the cache assumes by default that all files in the directory are binary. It can optionally be given a filename suffix to select specific binary file types such as images.

Before using a FileBinaryCache, you must call its startAutoUpdate() method to begin periodic updates. The default loading policy is LOAD_ON_DEMAND: files are loaded into the cache only when requested, each file's modification date is checked each time it is requested, and the periodic updates are used only to remove deleted files from the cache. If the loading policy is set to PRELOAD, all files are loaded when startAutoUpdate() is called, and all files are checked during each periodic update. If binary 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 files are loaded when startAutoUpdate is called but they are not refreshed periodically. Instead, one can write a client that will ask the FileBinaryCache to update a single binary object via the Updatable#update(String name) method. Applications with a large number of files in cache many of which are not frequently updated will work well with LOAD_AD_HOC mode. Since files are updated 'ad hoc' in this mode rather than periodically calling startAutoUpdate() is not required.

The string argument to the getBinaryData() method is interpreted as the file'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 file). For example, if a BinaryCache object was made for the directory images, which contains a subdirectory foo, in which there is an image called site.jpg, you would call getBinaryData("foo/site.jpg") to retrieve that file.

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

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

See Also:

BinaryCache, CacheListener, Updatable.update(String)

Field Summary

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

Constructor Summary

FileBinaryCache()
Constructs an empty FileBinaryCache.

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

FileBinaryCache(java.io.File dir, long delay)
Constructs a BinaryCache with a directory in which it will look for files, and a delay representing the number of seconds between cache updates.

FileBinaryCache(java.lang.String path)
Constructs a BinaryCache with a directory in which it will look for files.

FileBinaryCache(java.lang.String path, long delay)
Constructs a BinaryCache with a directory in which it will look for files, and a delay representing the number of seconds between cache updates.

Method Summary

void	addCacheListener(CacheListener listener) Registers a CacheListener for this BinaryCache.
BinaryData	getBinaryData(java.lang.String name) Gets a binary object from the cache
long	getDelay() Returns the interval between two cache updates.
java.io.File	getDirectory() Returns the binary cache root directory
java.lang.String	getFilenameSuffix() Returns the file suffix.
int	getLoadingPolicy() Returns the loading policy currently in effect
java.lang.String	getPath() Returns the binary cache root directory
java.util.Iterator	listCachedFiles() Returns a list of cached files
void	removeCacheListener(CacheListener listener) Unregisters a CacheListener for this BinaryCache.
void	setDelay(long delay) Sets the interval between two cache updates.
void	setDirectory(java.io.File dir) Sets the binary cache root directory
void	setFilenameSuffix(java.lang.String filenameSuffix) Sets the file suffix.
void	setLoadingPolicy(int loadingPolicy) Sets the loading policy for this FileBinaryCache.
void	setPath(java.lang.String path) Sets the binary 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 binary object 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 files should be loaded as they are requested.

PRELOAD

public static final int PRELOAD

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

LOAD_AD_HOC

public static final int LOAD_AD_HOC

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

Constructor Detail

FileBinaryCache

public FileBinaryCache()

Constructs an empty FileBinaryCache.

FileBinaryCache

public FileBinaryCache(java.lang.String path)

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

Parameters:

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

FileBinaryCache

public FileBinaryCache(java.io.File dir)

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

Parameters:

dir - the directory containing files for this cache.

FileBinaryCache

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

Constructs a BinaryCache with a directory in which it will look for files, and a delay representing the number of seconds between cache updates.

Parameters:

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

delay - the number of seconds between cache updates.

FileBinaryCache

public FileBinaryCache(java.io.File dir,
                       long delay)

Constructs a BinaryCache with a directory in which it will look for files, and a delay representing the number of seconds between cache updates.

Parameters:

dir - the directory containing files 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 FileBinaryCache. If LOAD_ON_DEMAND, files will be loaded as they are requested, and each file's modification date will be checked each time it is requested. If PRELOAD, all files in the cache directory and its subdirectories will be loaded when the cache is started, and new files will be added to the cache each time it is updated. If LOAD_AD_HOC, all files in the cache directory and its subdirectories will be loaded when the cache is created and a particular file's modification date will be checked each time the client requests the update of that and only that file. Defaults to LOAD_ON_DEMAND.

Parameters:

loadingPolicy - cache mode

setPath

public void setPath(java.lang.String path)

Sets the binary cache root directory

Parameters:

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

getPath

public java.lang.String getPath()

Returns the binary cache root directory

Returns:

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

setDirectory

public void setDirectory(java.io.File dir)

Sets the binary cache root directory

Parameters:

dir - the root directory containing files for this cache

getDirectory

public java.io.File getDirectory()

Returns the binary cache root directory

Returns:

the root directory containing files 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

setFilenameSuffix

public void setFilenameSuffix(java.lang.String filenameSuffix)

Sets the file 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 files to be read for this cache.

getFilenameSuffix

public java.lang.String getFilenameSuffix()

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

Parameters:

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

addCacheListener

public void addCacheListener(CacheListener listener)

Description copied from interface: BinaryCache

Registers a CacheListener for this BinaryCache.

Specified by:

addCacheListener in interface BinaryCache

Following copied from interface: freemarker.template.BinaryCache

Parameters:

CacheListener - the CacheListener to be registered.

See Also:

CacheListener

removeCacheListener

public void removeCacheListener(CacheListener listener)

Description copied from interface: BinaryCache

Unregisters a CacheListener for this BinaryCache.

Specified by:

removeCacheListener in interface BinaryCache

Following copied from interface: freemarker.template.BinaryCache

Parameters:

CacheListener - the CacheListener to be unregistered.

See Also:

CacheListener

getBinaryData

public BinaryData getBinaryData(java.lang.String name)

Gets a binary object from the cache

Specified by:

getBinaryData in interface BinaryCache

Parameters:

name - binary object's filename, including its path relative to the cache's root directory.

Returns:

the corresponding BinaryData, or null if not found or an error has occurred

startAutoUpdate

public void startAutoUpdate()

Description copied from interface: BinaryCache

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 BinaryCache

stopAutoUpdate

public void stopAutoUpdate()

Description copied from interface: BinaryCache

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 BinaryCache

listCachedFiles

public java.util.Iterator listCachedFiles()

Returns a list of cached files

Specified by:

listCachedFiles in interface BinaryCache

Returns:

a list of cached files

update

public void update(java.lang.String name)

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

Specified by:

update in interface Updatable

Parameters:

name - of the binary object to update

update

public void update()

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

Specified by:

update in interface Updatable