freemarker.template.cache
Class LocalizedFileRetriever

java.lang.Object
  freemarker.template.cache.LocalizedFileRetriever

All Implemented Interfaces:

CacheRetriever, RegistryAccepter, TextEncoding

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

Retrieves cacheable objects through the file system. This version performs locale-based searching for files: first it looks for the most-localized file, then works back to the default (base) filename. Filenames are of the format:

 (filename)_(language)_(country).(file extension)
 

For instance, an HTML file encoded in Australian English would have the filename: helloworld_en_AU.html

Based on code donated to the FreeMarker project by Jonathan Revusky as part of the Niggle web application framework.

Version:

$Id: LocalizedFileRetriever.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 java.util.Locale	locale The localization.
protected java.util.List<freemarker.template.cache.LocalizedFileRetriever.LocaleMap>	localeExtensions
protected TemplateRegistry	registry The template registry to use to instantiate objects.

Constructor Summary

LocalizedFileRetriever()
Creates new FileRetriever.

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

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

LocalizedFileRetriever(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	exists(java.lang.String location) Tests whether the object still exists in the template repository.
static java.lang.String	getCharset(java.util.Locale loc) Gets the preferred charset for the given locale, or null if the locale is not recognized.
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.
protected java.lang.String	getFilenameFromLocale(java.lang.String aFilename, freemarker.template.cache.LocalizedFileRetriever.LocaleMap cLocale) Given a base filename, and a LocaleMap entry, work out what the filename should be.
java.lang.String	getFilenameSuffix() Returns the file suffix.
java.util.Locale	getLocale() Retrieves the locale used when retrieving files.
protected java.util.List<freemarker.template.cache.LocalizedFileRetriever.LocaleMap>	getLocaleExtensions(java.util.Locale locale) Creates a list of locales and associated filenames to use when searching for localized files.
protected freemarker.template.cache.LocalizedFileRetriever.FileLocale	getLocalizedFile(java.lang.String aFilename) Given a base filename, get a localized version, if one is available.
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.
protected java.lang.String	getRootFile(java.lang.String aFilename) Performs a reverse lookup of locale information: given a filename, determine whether a locale has been used, and if so, strips it back to the root filename.
TemplateRegistry	getTemplateRegistry() Retrieves the current TemplateRegistry in use.
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	setLocale(java.util.Locale locale) Sets the locale to use when retrieving files.
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, equals, finalize, getClass, hashCode, 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.

locale

protected java.util.Locale locale

The localization.

localeExtensions

protected java.util.List<freemarker.template.cache.LocalizedFileRetriever.LocaleMap> localeExtensions

Constructor Detail

LocalizedFileRetriever

public LocalizedFileRetriever()

Creates new FileRetriever.

LocalizedFileRetriever

public LocalizedFileRetriever(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

LocalizedFileRetriever

public LocalizedFileRetriever(java.io.File rootDir)

Creates a new FileRetriever, with a directory root.

Parameters:

rootDir - the root directory for the file system

LocalizedFileRetriever

public LocalizedFileRetriever(FileRetrieverParameters params)

Creates a new LocalizedFileRetriever, 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. For localization purposes, determine when we find any localization suffixes, and remove them.

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. a directory, not a 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()

Retrieves the current TemplateRegistry in use.

Specified by:

getTemplateRegistry in interface RegistryAccepter

Returns:

the registry currently in use when creating new objects

setLocale

public void setLocale(java.util.Locale locale)

Sets the locale to use when retrieving files.

getLocale

public java.util.Locale getLocale()

Retrieves the locale used when retrieving files.

getLocaleExtensions

protected java.util.List<freemarker.template.cache.LocalizedFileRetriever.LocaleMap> getLocaleExtensions(java.util.Locale locale)

Creates a list of locales and associated filenames to use when searching for localized files.

getRootFile

protected java.lang.String getRootFile(java.lang.String aFilename)

Performs a reverse lookup of locale information: given a filename, determine whether a locale has been used, and if so, strips it back to the root filename.

getLocalizedFile

protected freemarker.template.cache.LocalizedFileRetriever.FileLocale getLocalizedFile(java.lang.String aFilename)
                                                                                throws TemplateException

Given a base filename, get a localized version, if one is available. Searches for the most specific localized version first, then works back to least specific.

Throws:

TemplateException

getFilenameFromLocale

protected java.lang.String getFilenameFromLocale(java.lang.String aFilename,
                                                 freemarker.template.cache.LocalizedFileRetriever.LocaleMap cLocale)

Given a base filename, and a LocaleMap entry, work out what the filename should be.

getCharset

public static java.lang.String getCharset(java.util.Locale loc)

Gets the preferred charset for the given locale, or null if the locale is not recognized.

Parameters:

loc - the locale

Returns:

the preferred charset

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