freemarker.template.cache
Class FileRetriever

java.lang.Object
  freemarker.template.cache.FileRetriever

All Implemented Interfaces:

CacheRetriever, RegistryAccepter, TextEncoding

public class FileRetriever
extends java.lang.Object
implements CacheRetriever, TextEncoding, RegistryAccepter

Retrieves cacheable objects through the file system. This is the default retriever for FileTemplateCache.

Version:

$Id: FileRetriever.java 1153 2013-04-15 10:59:37Z run2000 $

Field Summary

protected java.io.File	directoryRoot The root directory where the retriever will get files.
protected java.lang.String	encoding The text encoding of the template files.
protected java.lang.String	filenameSuffix The filename suffix required for a file to be retrieved.
protected TemplateRegistry	registry The template registry to use to instantiate objects.

Constructor Summary

FileRetriever()
Creates new FileRetriever.

FileRetriever(java.io.File rootDir)
Creates a new FileRetriever, with a directory root.

FileRetriever(FileRetrieverParameters params)
Creates a new FileRetriever, with the given parameters.

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

Method Summary

boolean	connectionOk() Corresponds to checkCacheDir for file-system implementations.
boolean	equals(java.lang.Object o) Is this file retriever equal to another object?
boolean	exists(java.lang.String location) Tests whether the object still exists in the template repository.
java.lang.String	getConnection() Gets the connection for this retriever.
java.lang.String	getEncoding() Returns the character encoding to be used when reading template files.
java.lang.String	getFilenameSuffix() Returns the file suffix.
java.io.File	getPath() Returns the root directory for this retriever.
java.util.List<java.lang.String>	getPreloadData() Returns a list of objects (Strings) to pre-load the cache with.
TemplateRegistry	getTemplateRegistry() Gets the current template registry implementation in use.
int	hashCode() Retrieve the hash code for this object
protected boolean	isSuffixValid(java.lang.String name) Determine whether the filename ends with the appropriate filename suffix.
long	lastModified(java.lang.String location) Determines when the object in the template repository was last modified.
Cacheable	loadData(java.lang.String location, java.lang.String type, Cache cache) Retrieves the appropriate data to be stored in the cache.
protected java.io.File	nameToFile(java.lang.String name) Converts a cache element name to a File.
protected void	readDirectory(java.io.File dir, java.lang.String relativeDirPath, java.util.List<java.lang.String> visitedFiles) Recursively updates the cache from the files in a (sub)directory and its subdirectories.
void	setTemplateRegistry(TemplateRegistry cRegistry) Deprecated. this is the only mutable state, and should be removed in the next release
java.lang.String	toString() Returns a string representation of the object.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

directoryRoot

protected java.io.File directoryRoot

The root directory where the retriever will get files.

filenameSuffix

protected java.lang.String filenameSuffix

The filename suffix required for a file to be retrieved.

encoding

protected java.lang.String encoding

The text encoding of the template files.

registry

protected TemplateRegistry registry

The template registry to use to instantiate objects.

Constructor Detail

FileRetriever

public FileRetriever()

Creates new FileRetriever.

FileRetriever

public FileRetriever(java.lang.String path)

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

Parameters:

path - the absolute path of the directory containing templates for this retriever

Throws:

java.lang.IllegalArgumentException - the root directory is null

FileRetriever

public FileRetriever(java.io.File rootDir)

Creates a new FileRetriever, with a directory root.

Parameters:

rootDir - the root directory for the file system

Throws:

java.lang.IllegalArgumentException - the root directory is null

FileRetriever

public FileRetriever(FileRetrieverParameters params)

Creates a new FileRetriever, with the given parameters.

Parameters:

params - the parameters for this file retriever

Throws:

java.lang.IllegalArgumentException - the root directory is null

Since:

1.9

Method Detail

connectionOk

public boolean connectionOk()
                     throws TemplateException

Corresponds to checkCacheDir for file-system implementations.

Specified by:

connectionOk in interface CacheRetriever

Returns:

true if the connection is ok, otherwise false

Throws:

TemplateException - the directory no longer exists, or is not a directory

getConnection

public java.lang.String getConnection()

Gets the connection for this retriever. Corresponds to getPath for file-system implementations.

Specified by:

getConnection in interface CacheRetriever

Returns:

the connection string used to connect to this retriever

getPath

public java.io.File getPath()

Returns the root directory for this retriever.

Returns:

the root directory containing files for this retriever

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.

Returns:

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

exists

public boolean exists(java.lang.String location)

Tests whether the object still exists in the template repository. This may be redundant. Instead, lastModified could throw an appropriate exception.

Specified by:

exists in interface CacheRetriever

Parameters:

location - the location of the object to be tested

Returns:

true if the object still exists in the repository, otherwise false

See Also:

lastModified(java.lang.String)

getPreloadData

public java.util.List<java.lang.String> getPreloadData()
                                                throws TemplateException

Returns a list of objects (Strings) to pre-load the cache with.

Specified by:

getPreloadData in interface CacheRetriever

Returns:

a List of Strings to preload the cache with

Throws:

TemplateException

readDirectory

protected void readDirectory(java.io.File dir,
                             java.lang.String relativeDirPath,
                             java.util.List<java.lang.String> visitedFiles)
                      throws java.io.IOException

Recursively updates the cache from the files in a (sub)directory and its subdirectories.

Parameters:

dir - the directory to be read.

relativeDirPath - a string representing the directory's path relative to the root cache directory.

visitedFiles - a List of files that have been visited so far.

Throws:

java.io.IOException

lastModified

public long lastModified(java.lang.String location)
                  throws TemplateException

Determines when the object in the template repository was last modified.

Specified by:

lastModified in interface CacheRetriever

Parameters:

location - the location of the object to be tested

Returns:

milliseconds since 1970 of the time the item was last modified

Throws:

TemplateException - is thrown whenever the item:

• does not exist
• is the wrong type (eg. directory, not file)
• has an invalid file suffix

isSuffixValid

protected boolean isSuffixValid(java.lang.String name)
                         throws TemplateException

Determine whether the filename ends with the appropriate filename suffix.

Parameters:

name - the filename to be checked

Returns:

is the filename suffix ok?

Throws:

TemplateException - the suffix is invalid

nameToFile

protected java.io.File nameToFile(java.lang.String name)
                           throws TemplateException

Converts a cache element name to a File.

Parameters:

name - the filename relative to the directory root of the retriever

Returns:

the fully qualified filename

Throws:

TemplateException

loadData

public Cacheable loadData(java.lang.String location,
                          java.lang.String type,
                          Cache cache)
                   throws TemplateException

Retrieves the appropriate data to be stored in the cache.

Specified by:

loadData in interface CacheRetriever

Parameters:

location - the filename, relative to the root directory, of the template data to load

type - the type of item to be loaded

cache - the cache to which the item will be added

Returns:

the template data

Throws:

TemplateException - the object could not be loaded

getEncoding

public java.lang.String getEncoding()

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

Specified by:

getEncoding in interface TextEncoding

Returns:

the name of the encoding to be used; this will be passed to the constructor of InputStreamReader.

setTemplateRegistry

public void setTemplateRegistry(TemplateRegistry cRegistry)

Deprecated. this is the only mutable state, and should be removed in the next release

Sets a template registry implementation to use when creating new templates.

Specified by:

setTemplateRegistry in interface RegistryAccepter

Parameters:

cRegistry - the registry to be used for creating new objects

getTemplateRegistry

public TemplateRegistry getTemplateRegistry()

Gets the current template registry implementation in use.

Specified by:

getTemplateRegistry in interface RegistryAccepter

Returns:

the registry currently in use when creating new objects

equals

public boolean equals(java.lang.Object o)

Is this file retriever equal to another object?

Overrides:

equals in class java.lang.Object

Parameters:

o - the object to compare this object with

Returns:

true if the objects are equal, otherwise false

hashCode

public int hashCode()

Retrieve the hash code for this object

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code

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