freemarker.template

Class Configuration

Implemented Interfaces:
Cloneable

public class Configuration
extends Configurable
implements Cloneable

Main entry point into the FreeMarker API, this class encapsulates the various configuration parameters with which FreeMarker is run, as well as serves as a central template loading and caching point. Note that this class uses a default strategy for loading and caching templates. You can plug in a replacement template loading mechanism by using the setTemplateLoader(TemplateLoader) method. This object is not synchronized. Thus, the settings must not be changed after you have started to access the object from multiple threads. If you use multiple threads, set everything directly after you have instantiated the Configuration object, and don't change the settings anymore.
Version:
$Id: Configuration.java,v 1.122.2.5 2006/04/26 21:25:19 ddekany Exp $
Authors:
Jonathan Revusky
Attila Szegedi

Nested Class Summary

Nested classes/interfaces inherited from class freemarker.core.Configurable

Configurable.UnknownSettingException

Field Summary

static int
ANGLE_BRACKET_TAG_SYNTAX
static int
AUTO_DETECT_TAG_SYNTAX
static String
AUTO_IMPORT_KEY
static String
AUTO_INCLUDE_KEY
static String
CACHE_STORAGE_KEY
static String
DEFAULT_ENCODING_KEY
static String
LOCALIZED_LOOKUP_KEY
static int
SQUARE_BRACKET_TAG_SYNTAX
static String
STRICT_SYNTAX_KEY
static String
TAG_SYNTAX_KEY
static String
TEMPLATE_UPDATE_DELAY_KEY
static String
WHITESPACE_STRIPPING_KEY

Fields inherited from class freemarker.core.Configurable

ARITHMETIC_ENGINE_KEY, BOOLEAN_FORMAT_KEY, CLASSIC_COMPATIBLE_KEY, DATETIME_FORMAT_KEY, DATE_FORMAT_KEY, LOCALE_KEY, NUMBER_FORMAT_KEY, OBJECT_WRAPPER_KEY, OUTPUT_ENCODING_KEY, STRICT_BEAN_MODELS, TEMPLATE_EXCEPTION_HANDLER_KEY, TIME_FORMAT_KEY, TIME_ZONE_KEY, URL_ESCAPING_CHARSET_KEY

Constructor Summary

Configuration()

Method Summary

void
addAutoImport(String namespace, String template)
Add an auto-imported template.
void
addAutoInclude(String templateName)
add a template to be automatically included at the top of any template that is vended by this Configuration object.
void
clearEncodingMap()
Clears language-to-encoding map.
void
clearSharedVariables()
Removes all shared variables, except the predefined ones (compress, html_escape, etc.).
void
clearTemplateCache()
Removes all entries from the template cache, thus forcing reloading of templates on subsequent getTemplate calls.
Object
clone()
static Configuration
getDefaultConfiguration()
Deprecated. The usage of the static singleton (the "default") Configuration instance can easily cause erroneous, unpredictable behavior.
String
getDefaultEncoding()
Gets the default encoding for converting bytes to characters when reading template files in a locale for which no explicit encoding was specified.
String
getEncoding(Locale loc)
Gets the preferred character encoding for the given locale, or the default encoding if no encoding is set explicitly for the specified locale.
boolean
getLocalizedLookup()
Returns if localized template lookup is enabled or not.
TemplateModel
getSharedVariable(String name)
Gets a shared variable.
Set
getSharedVariableNames()
Returns the set containing the names of all defined shared variables.
boolean
getStrictSyntaxMode()
Tells whether directives such as if, else, etcetera must be written as #if, #else, etcetera.
int
getTagSyntax()
Template
getTemplate(String name)
Equivalent to getTemplate(name, thisCfg.getLocale(), thisCfg.getEncoding(thisCfg.getLocale()), true).
Template
getTemplate(String name, Locale locale)
Equivalent to getTemplate(name, locale, thisCfg.getEncoding(locale), true).
Template
getTemplate(String name, Locale locale, String encoding)
Equivalent to getTemplate(name, locale, encoding, true).
Template
getTemplate(String name, Locale locale, String encoding, boolean parse)
Retrieves a template specified by a name and locale, interpreted using the specified character encoding, either parsed or unparsed.
Template
getTemplate(String name, String encoding)
Equivalent to getTemplate(name, thisCfg.getLocale(), encoding, true).
TemplateLoader
getTemplateLoader()
static String
getVersionNumber()
Returns FreeMarker version number string.
boolean
getWhitespaceStripping()
Gets whether the FTL parser will try to remove superfluous white-space around certain FTL tags.
void
loadBuiltInEncodingMap()
Loads a preset language-to-encoding map.
void
removeAutoImport(String namespace)
Remove an auto-imported template
void
removeAutoInclude(String templateName)
remove a template from the auto-include list.
void
setAllSharedVariables(TemplateHashModelEx hash)
Adds all object in the hash as shared variable to the configuration.
void
setAutoImports(Map map)
set a map of namespace names to templates for auto-importing a set of templates.
void
setAutoIncludes(List templateNames)
set the list of automatically included templates.
void
setCacheStorage(CacheStorage storage)
void
setClassForTemplateLoading(Class clazz, String pathPrefix)
Sets a class relative to which we do the Class.getResource() call to load templates.
static void
setDefaultConfiguration(Configuration config)
Deprecated. Using the "default" Configuration instance can easily lead to erroneous, unpredictable behaviour.
void
setDefaultEncoding(String encoding)
Sets the default encoding for converting bytes to characters when reading template files in a locale for which no explicit encoding was specified.
void
setDirectoryForTemplateLoading(File dir)
Set the explicit directory from which to load templates.
void
setEncoding(Locale locale, String encoding)
Sets the character set encoding to use for templates of a given locale.
void
setLocalizedLookup(boolean localizedLookup)
Enables/disables localized template lookup.
void
setServletContextForTemplateLoading(Object sctxt, String path)
Sets the servlet context from which to load templates
void
setSetting(String key, String value)
Sets a setting by name and string value.
void
setSharedVariable(String name, Object obj)
Adds shared variable to the configuration.
void
setSharedVariable(String name, TemplateModel tm)
Adds a shared variable to the configuration.
void
setStrictSyntaxMode(boolean b)
Sets whether directives such as if, else, etcetera must be written as #if, #else, etcetera.
void
setTagSyntax(int tagSyntax)
Determines the syntax of the template files (angle bracket VS square bracket) that has no ftl directive in it.
void
setTemplateLoader(TemplateLoader loader)
Sets a template loader that is used to look up and load templates.
void
setTemplateUpdateDelay(int delay)
Set the time in seconds that must elapse before checking whether there is a newer version of a template file.
void
setWhitespaceStripping(boolean b)
Sets whether the FTL parser will try to remove superfluous white-space around certain FTL tags.

Methods inherited from class freemarker.core.Configurable

clone, getArithmeticEngine, getBooleanFormat, getCustomAttribute, getCustomAttributeNames, getDateFormat, getDateTimeFormat, getEnvironment, getLocale, getNumberFormat, getObjectWrapper, getOutputEncoding, getParent, getSetting, getSettings, getTemplateExceptionHandler, getTimeFormat, getTimeZone, getURLEscapingCharset, invalidSettingValueException, isClassicCompatible, removeCustomAttribute, setArithmeticEngine, setBooleanFormat, setClassicCompatible, setCustomAttribute, setDateFormat, setDateTimeFormat, setLocale, setNumberFormat, setObjectWrapper, setOutputEncoding, setSetting, setSettings, setSettings, setStrictBeanModels, setTemplateExceptionHandler, setTimeFormat, setTimeZone, setURLEscapingCharset, unknownSettingException

Field Details

ANGLE_BRACKET_TAG_SYNTAX

public static final int ANGLE_BRACKET_TAG_SYNTAX
Field Value:
1

AUTO_DETECT_TAG_SYNTAX

public static final int AUTO_DETECT_TAG_SYNTAX
Field Value:
0

AUTO_IMPORT_KEY

public static final String AUTO_IMPORT_KEY

AUTO_INCLUDE_KEY

public static final String AUTO_INCLUDE_KEY

CACHE_STORAGE_KEY

public static final String CACHE_STORAGE_KEY

DEFAULT_ENCODING_KEY

public static final String DEFAULT_ENCODING_KEY

LOCALIZED_LOOKUP_KEY

public static final String LOCALIZED_LOOKUP_KEY

SQUARE_BRACKET_TAG_SYNTAX

public static final int SQUARE_BRACKET_TAG_SYNTAX
Field Value:
2

STRICT_SYNTAX_KEY

public static final String STRICT_SYNTAX_KEY

TAG_SYNTAX_KEY

public static final String TAG_SYNTAX_KEY

TEMPLATE_UPDATE_DELAY_KEY

public static final String TEMPLATE_UPDATE_DELAY_KEY

WHITESPACE_STRIPPING_KEY

public static final String WHITESPACE_STRIPPING_KEY

Constructor Details

Configuration

public Configuration()

Method Details

addAutoImport

public void addAutoImport(String namespace,
                          String template)
Add an auto-imported template. The importing will happen at the top of any template that is vended by this Configuration object.
Parameters:
namespace - the name of the namespace into which the template is imported
template - the name of the template

addAutoInclude

public void addAutoInclude(String templateName)
add a template to be automatically included at the top of any template that is vended by this Configuration object.
Parameters:
templateName - the lookup name of the template.

clearEncodingMap

public void clearEncodingMap()
Clears language-to-encoding map.

clearSharedVariables

public void clearSharedVariables()
Removes all shared variables, except the predefined ones (compress, html_escape, etc.).

clearTemplateCache

public void clearTemplateCache()
Removes all entries from the template cache, thus forcing reloading of templates on subsequent getTemplate calls. This method is thread-safe and can be called while the engine works.

clone

public Object clone()
Overrides:
clone in interface Configurable

getDefaultConfiguration

public static Configuration getDefaultConfiguration()

Deprecated. The usage of the static singleton (the "default") Configuration instance can easily cause erroneous, unpredictable behavior. This is because multiple independent software components may use FreeMarker internally inside the same application, so they will interfere because of the common Configuration instance. Each such component should use its own private Configuration object instead, that it typically creates with new Configuration() when the component is initialized.

Returns the default (singleton) Configuration object. Note that you can create as many separate configurations as you wish; this global instance is provided for convenience, or when you have no reason to use a separate instance.

getDefaultEncoding

public String getDefaultEncoding()
Gets the default encoding for converting bytes to characters when reading template files in a locale for which no explicit encoding was specified. Defaults to default system encoding.

getEncoding

public String getEncoding(Locale loc)
Parameters:
loc - the locale
Returns:
the preferred character encoding for the locale.

getLocalizedLookup

public boolean getLocalizedLookup()
Returns if localized template lookup is enabled or not. This method is thread-safe and can be called while the engine works.

getSharedVariable

public TemplateModel getSharedVariable(String name)
Gets a shared variable. Shared variables are variables that are available to all templates. When a template is processed, and an identifier is undefined in the data model, a shared variable object with the same identifier is then looked up in the configuration. There are several predefined variables that are always available through this method, see the FreeMarker manual for a comprehensive list of them.

getSharedVariableNames

public Set getSharedVariableNames()
Returns the set containing the names of all defined shared variables. The method returns a new Set object on each call that is completely disconnected from the Configuration. That is, modifying the set will have no effect on the Configuration object.

getStrictSyntaxMode

public boolean getStrictSyntaxMode()
Tells whether directives such as if, else, etcetera must be written as #if, #else, etcetera.

getTagSyntax

public int getTagSyntax()
Returns:
whether the alternative square bracket syntax is set as the default

getTemplate

public Template getTemplate(String name)
            throws IOException
Equivalent to getTemplate(name, thisCfg.getLocale(), thisCfg.getEncoding(thisCfg.getLocale()), true).

getTemplate

public Template getTemplate(String name,
                            Locale locale)
            throws IOException
Equivalent to getTemplate(name, locale, thisCfg.getEncoding(locale), true).

getTemplate

public Template getTemplate(String name,
                            Locale locale,
                            String encoding)
            throws IOException
Equivalent to getTemplate(name, locale, encoding, true).

getTemplate

public Template getTemplate(String name,
                            Locale locale,
                            String encoding,
                            boolean parse)
            throws IOException
Retrieves a template specified by a name and locale, interpreted using the specified character encoding, either parsed or unparsed. For the exact semantics of parameters, see TemplateCache.getTemplate(String,Locale,String,boolean).
Returns:
the requested template.

getTemplate

public Template getTemplate(String name,
                            String encoding)
            throws IOException
Equivalent to getTemplate(name, thisCfg.getLocale(), encoding, true).

getTemplateLoader

public TemplateLoader getTemplateLoader()
Returns:
the template loader that is used to look up and load templates.

getVersionNumber

public static String getVersionNumber()
Returns FreeMarker version number string. Examples of possible return values: "2.2.5", "2.3pre13", "2.3pre13mod", "2.3rc1", "2.3", "3.0".

Notes on FreeMarker version numbering rules:

  • "pre" and "rc" (lowercase!) means "preview" and "release candidate" respectively. It is must be followed with a number (as "1" for the first release candidate).
  • The "mod" after the version number indicates that it's an unreleased modified version of the released version. After releases, the nighly builds are such releases. E.g. the nightly build after releasing "2.2.1" but before releasing "2.2.2" is "2.2.1mod".
  • The 2nd version number must be present, and maybe 0, as in "3.0".
  • The 3rd version number is never 0. E.g. the version number string for the first release of the 2.2 series is "2.2", and NOT "2.2.0".
  • When only the 3rd version number increases (2.2 -> 2.2.1, 2.2.1 -> 2.2.2 etc.), 100% backward compatiblity with the previous version MUST be kept. This means that freemarker.jar can be replaced in an application without risk (as far as the application doesn't depend on the presence of a FreeMarker bug). Note that backward compatibility restrictions do not apply for preview releases.

getWhitespaceStripping

public boolean getWhitespaceStripping()
Gets whether the FTL parser will try to remove superfluous white-space around certain FTL tags.

loadBuiltInEncodingMap

public void loadBuiltInEncodingMap()
Loads a preset language-to-encoding map. It assumes the usual character encodings for most languages. The previous content of the encoding map will be lost. This default map currently contains the following mappings:
arISO-8859-6
beISO-8859-5
bgISO-8859-5
caISO-8859-1
csISO-8859-2
daISO-8859-1
deISO-8859-1
elISO-8859-7
enISO-8859-1
esISO-8859-1
etISO-8859-1
fiISO-8859-1
frISO-8859-1
hrISO-8859-2
huISO-8859-2
isISO-8859-1
itISO-8859-1
iwISO-8859-8
jaShift_JIS
koEUC-KR
ltISO-8859-2
lvISO-8859-2
mkISO-8859-5
nlISO-8859-1
noISO-8859-1
plISO-8859-2
ptISO-8859-1
roISO-8859-2
ruISO-8859-5
shISO-8859-5
skISO-8859-2
slISO-8859-2
sqISO-8859-2
srISO-8859-5
svISO-8859-1
trISO-8859-9
ukISO-8859-5
zhGB2312
zh_TWBig5

removeAutoImport

public void removeAutoImport(String namespace)
Remove an auto-imported template
Parameters:
namespace - the name of the namespace into which the template was imported

removeAutoInclude

public void removeAutoInclude(String templateName)
remove a template from the auto-include list.
Parameters:
templateName - the lookup name of the template in question.

setAllSharedVariables

public void setAllSharedVariables(TemplateHashModelEx hash)
            throws TemplateModelException
Adds all object in the hash as shared variable to the configuration.

Never use TemplateModel implementation that is not thread-safe for shared variables, if the configuration is used by multiple threads! It is the typical situation for Servlet based Web sites.

Parameters:
hash - a hash model whose objects will be copied to the configuration with same names as they are given in the hash. If a shared variable with these names already exist, it will be replaced with those from the map.

setAutoImports

public void setAutoImports(Map map)
set a map of namespace names to templates for auto-importing a set of templates. Note that all previous auto-imports are removed.

setAutoIncludes

public void setAutoIncludes(List templateNames)
set the list of automatically included templates. Note that all previous auto-includes are removed.

setCacheStorage

public void setCacheStorage(CacheStorage storage)

setClassForTemplateLoading

public void setClassForTemplateLoading(Class clazz,
                                       String pathPrefix)
Sets a class relative to which we do the Class.getResource() call to load templates.

setDefaultConfiguration

public static void setDefaultConfiguration(Configuration config)

Deprecated. Using the "default" Configuration instance can easily lead to erroneous, unpredictable behaviour. See more here....

Sets the Configuration object that will be retrieved from future calls to getDefaultConfiguration().

setDefaultEncoding

public void setDefaultEncoding(String encoding)
Sets the default encoding for converting bytes to characters when reading template files in a locale for which no explicit encoding was specified. Defaults to default system encoding.

setDirectoryForTemplateLoading

public void setDirectoryForTemplateLoading(File dir)
            throws IOException
Set the explicit directory from which to load templates.

setEncoding

public void setEncoding(Locale locale,
                        String encoding)

setLocalizedLookup

public void setLocalizedLookup(boolean localizedLookup)
Enables/disables localized template lookup. Enabled by default. This method is thread-safe and can be called while the engine works.

setServletContextForTemplateLoading

public void setServletContextForTemplateLoading(Object sctxt,
                                                String path)
Sets the servlet context from which to load templates
Parameters:
sctxt - the ServletContext object. Note that the type is Object to prevent class loading errors when user who uses FreeMarker not for servlets has no javax.servlet in the CLASSPATH.
path - the path relative to the ServletContext. If this path is absolute, it is taken to be relative to the server's URL, i.e. http://myserver.com/ and if the path is relative, it is taken to be relative to the web app context, i.e. http://myserver.context.com/mywebappcontext/

setSetting

public void setSetting(String key,
                       String value)
            throws TemplateException
Sets a setting by name and string value. In additional to the settings understood by the super method, it understands these:
  • "auto_import": Sets the list of auto-imports. Example of valid value:
    /lib/form.ftl as f, /lib/widget as w, "/lib/evil name.ftl" as odd See: setAutoImports(Map)
  • "auto_include": Sets the list of auto-includes. Example of valid value:
    /include/common.ftl, "/include/evil name.ftl" See: setAutoIncludes(List)
  • "default_encoding": The name of the charset, such as "UTF-8". See: setDefaultEncoding(String)
  • "localized_lookup": "true", "false", "yes", "no", "t", "f", "y", "n". Case insensitive. See: setLocalizedLookup(boolean)
  • "strict_syntax": "true", "false", etc. See: setStrictSyntaxMode(boolean)
  • "whitespace_stripping": "true", "false", etc. See: setWhitespaceStripping(boolean)
  • "cache_storage": If the value contains dot, then it is interpreted as class name, and the object will be created with its parameterless constructor. If the value does not contain dot, then a MruCacheStorage will be used with the maximum strong and soft sizes specified with the setting value. Examples of valid setting values:
    Setting valuemax. strong sizemax. soft size
    "strong:50, soft:500"50500
    "strong:100, soft"100Integer.MAX_VALUE
    "strong:100"1000
    "soft:100"0100
    "strong"Integer.MAX_VALUE0
    "soft"0Integer.MAX_VALUE
    The value is not case sensitive. The order of soft and strong entries is not significant. See also: setCacheStorage(CacheStorage)
  • "template_update_delay": Valid positive integer, the update delay measured in seconds. See: setTemplateUpdateDelay(int)
  • "tag_syntax": Must be one of: "auto_detect", "angle_bracket", "square_bracket".
Overrides:
setSetting in interface Configurable
Parameters:
key - the name of the setting.
value - the string that describes the new value of the setting.
Throws:
TemplateException - if the new value of the setting can't be set for any other reasons.

setSharedVariable

public void setSharedVariable(String name,
                              Object obj)
            throws TemplateModelException
Adds shared variable to the configuration. It uses Configurable.getObjectWrapper() to wrap the obj.

setSharedVariable

public void setSharedVariable(String name,
                              TemplateModel tm)
Adds a shared variable to the configuration. Shared variables are variables that are visible as top-level variables for all templates which use this configuration, if the data model does not contain a variable with the same name.

Never use TemplateModel implementation that is not thread-safe for shared variables, if the configuration is used by multiple threads! It is the typical situation for Servlet based Web sites.

Parameters:
name - the name used to access the data object from your template. If a shared variable with this name already exists, it will replace that.

setStrictSyntaxMode

public void setStrictSyntaxMode(boolean b)
Sets whether directives such as if, else, etcetera must be written as #if, #else, etcetera. Any tag not starting with <# or </# is considered as plain text and will go to the output as is. Tag starting with <# or </# must be valid FTL tag, or else the template is invalid (i.e. <#noSuchDirective> is an error).

setTagSyntax

public void setTagSyntax(int tagSyntax)
Determines the syntax of the template files (angle bracket VS square bracket) that has no ftl directive in it. The tagSyntax parameter must be one of:

In FreeMarker 2.3.x ANGLE_BRACKET_TAG_SYNTAX is the default for better backward compatibility. Starting from 2.4.x AUTO_DETECT_TAG_SYNTAX is the default, so it is recommended to use that even for 2.3.x.

This setting is ignored for the templates that have ftl directive in it. For those templates the syntax used for the ftl directive determines the syntax.


setTemplateLoader

public void setTemplateLoader(TemplateLoader loader)
Sets a template loader that is used to look up and load templates. By providing your own template loader, you can customize the way templates are loaded. Several convenience methods in this class already allow you to install commonly used loaders: setClassForTemplateLoading(Class,String), setDirectoryForTemplateLoading(File), and setServletContextForTemplateLoading(Object,String). By default, a multi-loader is used that first tries to load a template from the file in the current directory, then from a resource on the classpath.

setTemplateUpdateDelay

public void setTemplateUpdateDelay(int delay)
Set the time in seconds that must elapse before checking whether there is a newer version of a template file. This method is thread-safe and can be called while the engine works.

setWhitespaceStripping

public void setWhitespaceStripping(boolean b)
Sets whether the FTL parser will try to remove superfluous white-space around certain FTL tags.