freemarker.template
Class FileTemplateCache

java.lang.Object
  |
  +--freemarker.template.FileTemplateCache
All Implemented Interfaces:
TemplateCache

public class FileTemplateCache
extends java.lang.Object
implements TemplateCache

A Cache that loads templates from the filesystem or via the Class.getResource() mechanism.

Templates are loaded into the cache only when requested. The cache maintains a table of when each file was last read from disk. If more than a certain period of time has elapsed since the last disk read, the cache will check for a newer version. If the file has been deleted, it is removed from the cache and the getTemplate() method will return null. How much time has to elapse before the cache looks for a newer version on disk can be set via the setDelay() method. By default, it is 5 seconds.

If a cache is created with the constructor with no arguments, it is assumed that you wish to load templates relative to the classloader classpath. If you create a cache with a java.io.File as a parameter, this must be an existing directory on the file system on which this code has read permission. If you use the constructor that takes a Class as an argument, this is assumed to be the class that you will use for the Class.getResource() call. You can also a set a path relative to the ClassLoader loading mechanism.

You can set a default encoding. Also, there is a version of the getTemplate() method that specifies encoding. The method that takes a Locale as an argument deduces the desired encoding from the locale. Note that this method will look for localized versions of the file in question. For example, myFile_fr_CA.html for a file localized to Canadian French. If that file is not found, it looks for myFile_fr.html, which would be a file localized to French, without specifying a country, and then, if that file is not found, myFile.html is used.

Version:
$Id: FileTemplateCache.java,v 1.50 2002/04/30 23:18:20 revusky Exp $

Constructor Summary
FileTemplateCache()
          This will create an instance that simply attempts to load files via the classloader of this class
FileTemplateCache(java.lang.Class clase)
          This will create an instance that simply attempts to load files via the classloader mechanism of the specified class loader.
FileTemplateCache(java.lang.Class clase, java.lang.String path)
          Constructs a cache which loads template files relative to the classloader of a given class.
FileTemplateCache(java.io.File explicitDirectory)
          Constructs a cache which loads template files from an explicit directory on the file system.
 
Method Summary
 void clear()
          Clears the cache.
 Template getTemplate(java.lang.String name)
          Retrieves a template from the cache.
 Template getTemplate(java.lang.String name, java.util.Locale locale)
          Will attempt to find a an appropriately named file given the name and the locale.
 Template getTemplate(java.lang.String name, java.util.Locale locale, java.lang.String encoding)
          Will attempt to find a an appropriately named file given the name and the locale.
 Template getTemplate(java.lang.String name, java.lang.String encoding)
          retrieves a file of the given name with the given encoding.
protected  void logFileUpdate(java.lang.String name)
          This method does nothing.
 void outputRawFile(java.lang.String filename, java.lang.String encoding, java.io.Writer out)
          Simply outputs the given file from the cache without any template processing.
 void setDefaultEncoding(java.lang.String encoding)
           
 void setDelay(int delay)
          Sets the delay in seconds between checking for newer versions of a file.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FileTemplateCache

public FileTemplateCache()
This will create an instance that simply attempts to load files via the classloader of this class

FileTemplateCache

public FileTemplateCache(java.lang.Class clase)
This will create an instance that simply attempts to load files via the classloader mechanism of the specified class loader. Typical usage would be to call this in the init() method of a servlet and the Class passed in would be that servlet class.
Parameters:
clase - the class whose classloader is used for loading the templates

FileTemplateCache

public FileTemplateCache(java.lang.Class clase,
                         java.lang.String path)
                  throws java.io.IOException
Constructs a cache which loads template files relative to the classloader of a given class. This is very useful for servlet deployment, since the servlet class can be passed in as an argument. If the path is specified, it represents a path relative to the Class.getResource() mechanism.

FileTemplateCache

public FileTemplateCache(java.io.File explicitDirectory)
                  throws java.io.IOException
Constructs a cache which loads template files from an explicit directory on the file system.
Method Detail

setDelay

public void setDelay(int delay)
Sets the delay in seconds between checking for newer versions of a file.
Parameters:
delay - how long since the last access before checking for a newer version of the file.

setDefaultEncoding

public void setDefaultEncoding(java.lang.String encoding)

getTemplate

public Template getTemplate(java.lang.String name,
                            java.lang.String encoding)
                     throws java.io.IOException
Description copied from interface: TemplateCache
retrieves a file of the given name with the given encoding.
Specified by:
getTemplate in interface TemplateCache

getTemplate

public Template getTemplate(java.lang.String name,
                            java.util.Locale locale)
                     throws java.io.IOException
Will attempt to find a an appropriately named file given the name and the locale. This uses the standard convention of myfile_en_US.html for example, for a file in US English. Since the encoding is not specified, we deduce/guess it from the locale.
Specified by:
getTemplate in interface TemplateCache

getTemplate

public Template getTemplate(java.lang.String name,
                            java.util.Locale locale,
                            java.lang.String encoding)
                     throws java.io.IOException
Will attempt to find a an appropriately named file given the name and the locale. This uses the standard convention of myfile_en_US.html for example, for a file in US English.
Specified by:
getTemplate in interface TemplateCache

getTemplate

public Template getTemplate(java.lang.String name)
                     throws java.io.IOException
Description copied from interface: TemplateCache
Retrieves a template from the cache. This method assumes defaults for the locale and character encoding.
Specified by:
getTemplate in interface TemplateCache
Following copied from interface: freemarker.template.TemplateCache
Parameters:
name - a string uniquely identifying the template.
Returns:
the template, or null if not found.

outputRawFile

public void outputRawFile(java.lang.String filename,
                          java.lang.String encoding,
                          java.io.Writer out)
                   throws java.io.IOException
Description copied from interface: TemplateCache
Simply outputs the given file from the cache without any template processing. If the encoding is null, it uses a default encoding.
Specified by:
outputRawFile in interface TemplateCache

logFileUpdate

protected void logFileUpdate(java.lang.String name)
This method does nothing. You can override it in a subclass in order to log when a template cache reloads a file due to it having been modified.

clear

public void clear()
Description copied from interface: TemplateCache
Clears the cache.
Specified by:
clear in interface TemplateCache