Configuration (FreeMarker 2.3.21 API)

java.lang.Object
- freemarker.core.Configurable
- - freemarker.template.Configuration

All Implemented Interfaces:

Cloneable
```
public class Configuration
extends Configurable
implements Cloneable
```
The main entry point into the FreeMarker API; encapsulates the configuration settings of FreeMarker, also serves as a central template-loading and caching service.
This class is meant to be used in a singleton pattern. That is, you create an instance of this at the beginning of the application life-cycle, set its configuration settings there (either with the setter methods like setTemplateLoader(TemplateLoader) or by loading a .properties file), and then use that single instance everywhere in your application. Frequently re-creating Configuration is a typical and grave mistake from performance standpoint, as the Configuration holds the template cache, and often also the class introspection cache, which then will be lost. (Note that, naturally, having multiple long-lived instances, like one per component that internally uses FreeMarker is fine.)
The basic usage pattern is like:
```
  // Where the application is initialized; in general you do this ONLY ONCE in the application life-cycle!
  Configuration cfg = new Configuration(VERSION_X_Y_Z));
  // Where X, Y, Z enables the not-100%-backward-compatible fixes introduced in
  // FreeMarker version X.Y.Z  and earlier (see Configuration(Version)).
  cfg.setSomeSetting(...);
  cfg.setOtherSetting(...);
  ...
  
  // Later, whenever the application needs a template (so you may do this a lot, and from multiple threads):
  Template myTemplate = cfg.getTemplate("myTemplate.html");
  myTemplate.process(dataModel, out);
```
A couple of settings that you should not leave on its default value are:
- template_loader: The default value is deprecated and in fact quite useless. (For the most common cases you can use the convenience methods, setDirectoryForTemplateLoading(File) and setClassForTemplateLoading(Class, String) too.)
- default_encoding: The default value is system dependent, which makes it fragile on servers, so it should be set explicitly, like to "UTF-8" nowadays.
- template_exception_handler: For developing HTML pages, the most convenient value is TemplateExceptionHandler.HTML_DEBUG_HANDLER. For production, TemplateExceptionHandler.RETHROW_HANDLER is safer to use.
A Configuration object is thread-safe only after you have stopped modifying the configuration settings, and you have safely published it (see JSR 133 and related literature) to other threads. Generally, you set everything directly after you have instantiated the Configuration object, then you don't change the settings anymore, so then it's safe to make it accessible (again, via a "safe publication" technique) from multiple threads. The methods that aren't for modifying settings, like getTemplate(String), are thread-safe.

Nested Class Summary
- Nested classes/interfaces inherited from class freemarker.core.Configurable
  Configurable.SettingValueAssignmentException, Configurable.UnknownSettingException

Field Summary

Fields
Modifier and Type	Field and Description
`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`	`DEFAULT_INCOMPATIBLE_ENHANCEMENTS` Deprecated. Use `DEFAULT_INCOMPATIBLE_IMPROVEMENTS` instead.
`static Version`	`DEFAULT_INCOMPATIBLE_IMPROVEMENTS` The default of `getIncompatibleImprovements()`, currently `new Version(2, 3, 0)`.
`static String`	`INCOMPATIBLE_ENHANCEMENTS` Deprecated. Use `INCOMPATIBLE_IMPROVEMENTS` instead.
`static String`	`INCOMPATIBLE_IMPROVEMENTS`
`static String`	`LOCALIZED_LOOKUP_KEY`
`static int`	`PARSED_DEFAULT_INCOMPATIBLE_ENHANCEMENTS` Deprecated. Use `DEFAULT_INCOMPATIBLE_IMPROVEMENTS` instead.
`static int`	`SQUARE_BRACKET_TAG_SYNTAX`
`static String`	`STRICT_SYNTAX_KEY`
`static String`	`TAG_SYNTAX_KEY`
`static String`	`TEMPLATE_LOADER_KEY`
`static String`	`TEMPLATE_UPDATE_DELAY_KEY`
`static Version`	`VERSION_2_3_0` FreeMarker version 2.3.0 (an `incompatible improvements break-point`)
`static Version`	`VERSION_2_3_19` FreeMarker version 2.3.19 (an `incompatible improvements break-point`)
`static Version`	`VERSION_2_3_20` FreeMarker version 2.3.20 (an `incompatible improvements break-point`)
`static Version`	`VERSION_2_3_21` FreeMarker version 2.3.21 (an `incompatible improvements break-point`)
`static String`	`WHITESPACE_STRIPPING_KEY`

Constructor Summary

Constructors
Constructor and Description
`Configuration()` Deprecated. Use `Configuration(Version)` instead. Note that the version can be still modified later with `setIncompatibleImprovements(Version)` (or `Configurable.setSettings(Properties)`).
`Configuration(Version incompatibleImprovements)` Creates a new instance and sets which of the non-backward-compatible bugfixes/improvements should be enabled.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`addAutoImport(String namespaceVarName, String templateName)` Adds an invisible `#import templateName as namespaceVarName` at the beginning of all templates.
`void`	`addAutoInclude(String templateName)` Adds an invisible `#include templateName as namespaceVarName` at the beginning of all templates.
`void`	`clearEncodingMap()` Clears language-to-encoding map.
`void`	`clearSharedVariables()` Removes all shared sharedVariables, 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()`
`protected void`	`doAutoImportsAndIncludes(Environment env)`
`CacheStorage`	`getCacheStorage()` The getter pair of `setCacheStorage(CacheStorage)`.
`protected String`	`getCorrectedNameForUnknownSetting(String name)`
`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.
`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.
`static ObjectWrapper`	`getDefaultObjectWrapper(Version incompatibleImprovements)` Returns the default object wrapper for a given "incompatible_improvements" version.
`String`	`getEncoding(Locale locale)` Gets the preferred character encoding for the given locale, or the default encoding if no encoding is set explicitly for the specified locale.
`String`	`getIncompatibleEnhancements()` Deprecated. Use `getIncompatibleImprovements()` instead.
`Version`	`getIncompatibleImprovements()`
`boolean`	`getLocalizedLookup()` The getter pair of `setLocalizedLookup(boolean)`.
`int`	`getParsedIncompatibleEnhancements()` Deprecated. Use `getIncompatibleImprovements()` instead.
`TemplateModel`	`getSharedVariable(String name)` Gets a shared variable.
`Set`	`getSharedVariableNames()` Returns the set containing the names of all defined shared sharedVariables.
`boolean`	`getStrictSyntaxMode()` The getter pair of `setStrictSyntaxMode(boolean)`.
`Set`	`getSupportedBuiltInDirectiveNames()` Returns the names of the directives that are predefined by FreeMarker.
`Set`	`getSupportedBuiltInNames()` Returns the names of the supported "built-ins".
`int`	`getTagSyntax()` The getter pair of `setTagSyntax(int)`.
`Template`	`getTemplate(String name)` Retrieves the template with the given name from the template cache, loading it into the cache first if it's missing/staled.
`Template`	`getTemplate(String name, Locale locale)` Shorthand for `getTemplate(name, locale, getEncoding(locale), true, false)`.
`Template`	`getTemplate(String name, Locale locale, String encoding)` Shorthand for `getTemplate(name, locale, encoding, true, false)`.
`Template`	`getTemplate(String name, Locale locale, String encoding, boolean parseAsFTL)` Shorthand for `getTemplate(name, locale, encoding, parseAsFTL, false)`.
`Template`	`getTemplate(String name, Locale locale, String encoding, boolean parseAsFTL, boolean ignoreMissing)` Retrieves the template with the given name (and according the specified further parameters) from the template cache, loading it into the cache first if it's missing/staled.
`Template`	`getTemplate(String name, String encoding)` Shorthand for `getTemplate(name, getLocale(), encoding, true, false)`.
`TemplateLoader`	`getTemplateLoader()` The getter pair of `setTemplateLoader(TemplateLoader)`.
`static Version`	`getVersion()` Returns the FreeMarker version information, most importantly the major.minor.micro version numbers.
`static String`	`getVersionNumber()` Deprecated. Use `getVersion()` instead.
`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, similarly as if you have called `clearEncodingMap()` and then did multiple `setEncoding(Locale, String)` calls.
`void`	`removeAutoImport(String namespaceVarName)` Removes an auto-import; see `addAutoImport(String, String)`.
`void`	`removeAutoInclude(String templateName)` Removes a template from the auto-include list; see `addAutoInclude(String)`.
`void`	`removeTemplateFromCache(String name)` Equivalent to `removeTemplateFromCache(name, thisCfg.getLocale(), thisCfg.getEncoding(thisCfg.getLocale()), true)`.
`void`	`removeTemplateFromCache(String name, Locale locale)` Equivalent to `removeTemplateFromCache(name, locale, thisCfg.getEncoding(locale), true)`.
`void`	`removeTemplateFromCache(String name, Locale locale, String encoding)` Equivalent to `removeTemplateFromCache(name, locale, encoding, true)`.
`void`	`removeTemplateFromCache(String name, Locale locale, String encoding, boolean parse)` Removes a template from the template cache, hence forcing the re-loading of it when it's next time requested.
`void`	`removeTemplateFromCache(String name, String encoding)` Equivalent to `removeTemplateFromCache(name, thisCfg.getLocale(), encoding, true)`.
`void`	`setAllSharedVariables(TemplateHashModelEx hash)` Adds all object in the hash as shared variable to the configuration; it's like doing several `setSharedVariable(String, Object)` calls, one for each hash entry.
`void`	`setAutoImports(Map map)` Removes all auto-imports, then calls `addAutoImport(String, String)` for each `Map`-entry (the entry key is the `namespaceVarName`).
`void`	`setAutoIncludes(List templateNames)` Removes all auto-includes, then calls `addAutoInclude(String)` for each `List` items.
`void`	`setCacheStorage(CacheStorage storage)` Sets the `CacheStorage` used for caching `Template`-s; the earlier content of the template cache will be dropt.
`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. See more `here...`.
`void`	`setDefaultEncoding(String encoding)` Sets the charset used for decoding byte sequences to character sequences when reading template files in a locale for which no explicit encoding was specified via `setEncoding(Locale, String)`.
`void`	`setDirectoryForTemplateLoading(File dir)` Sets the file system 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`	`setIncompatibleEnhancements(String version)` Deprecated. Use `Configuration(Version)`, or as last chance, `setIncompatibleImprovements(Version)` instead.
`void`	`setIncompatibleImprovements(Version incompatibleImprovements)` Use `Configuration(Version)` instead if possible; see the meaning of the parameter there.
`void`	`setLocalizedLookup(boolean localizedLookup)` Enables/disables localized template lookup.
`void`	`setObjectWrapper(ObjectWrapper objectWrapper)` Sets the object wrapper used to wrap objects to `TemplateModel`-s.
`void`	`setServletContextForTemplateLoading(Object servletContext, String path)` Sets the servlet context from which to load templates.
`void`	`setSetting(String name, String value)` Sets a FreeMarker setting by a name and string value.
`void`	`setSharedVariable(String name, Object value)` Adds shared variable to the configuration; It uses `Configurable.getObjectWrapper()` to wrap the `value`, so it's important that the object wrapper is set before this.
`void`	`setSharedVariable(String name, TemplateModel tm)` Adds a shared variable to the configuration.
`void`	`setSharedVaribles(Map map)` Replaces all shared variables (removes all previously added ones).
`void`	`setStrictSyntaxMode(boolean b)` Deprecated. Only `true` (the default) value will be supported sometimes in the future.
`void`	`setTagSyntax(int tagSyntax)` Determines the syntax of the template files (angle bracket VS square bracket) that has no `#ftl` in it.
`void`	`setTemplateLoader(TemplateLoader templateLoader)` Sets a `TemplateLoader` that is used to look up and load templates; as a side effect the template cache will be emptied.
`void`	`setTemplateUpdateDelay(int seconds)` Sets the time in seconds that must elapse before checking whether there is a newer version of a template file than the cached one.
`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
getArithmeticEngine, getAutoFlush, getBooleanFormat, getClassicCompatibleAsInt, getCustomAttribute, getCustomAttributeNames, getDateFormat, getDateTimeFormat, getEnvironment, getLocale, getNewBuiltinClassResolver, getNumberFormat, getObjectWrapper, getOutputEncoding, getParent, getSetting, getSettings, getShowErrorTips, getSQLDateAndTimeTimeZone, getTemplateExceptionHandler, getTimeFormat, getTimeZone, getURLEscapingCharset, invalidSettingValueException, isClassicCompatible, parseAsImportList, parseAsList, parseAsSegmentedList, removeCustomAttribute, setArithmeticEngine, setAutoFlush, setBooleanFormat, setClassicCompatible, setClassicCompatibleAsInt, setCustomAttribute, setDateFormat, setDateTimeFormat, setLocale, setNewBuiltinClassResolver, setNumberFormat, setOutputEncoding, setSettings, setSettings, setShowErrorTips, setSQLDateAndTimeTimeZone, setStrictBeanModels, setTemplateExceptionHandler, setTimeFormat, setTimeZone, settingValueAssignmentException, setURLEscapingCharset, unknownSettingException

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail
- DEFAULT_ENCODING_KEY
```
public static final String DEFAULT_ENCODING_KEY
```
  See Also:
  
  Constant Field Values
- LOCALIZED_LOOKUP_KEY
```
public static final String LOCALIZED_LOOKUP_KEY
```
  See Also:
  
  Constant Field Values
- STRICT_SYNTAX_KEY
```
public static final String STRICT_SYNTAX_KEY
```
  See Also:
  
  Constant Field Values
- WHITESPACE_STRIPPING_KEY
```
public static final String WHITESPACE_STRIPPING_KEY
```
  See Also:
  
  Constant Field Values
- CACHE_STORAGE_KEY
```
public static final String CACHE_STORAGE_KEY
```
  See Also:
  
  Constant Field Values
- TEMPLATE_UPDATE_DELAY_KEY
```
public static final String TEMPLATE_UPDATE_DELAY_KEY
```
  See Also:
  
  Constant Field Values
- AUTO_IMPORT_KEY
```
public static final String AUTO_IMPORT_KEY
```
  See Also:
  
  Constant Field Values
- AUTO_INCLUDE_KEY
```
public static final String AUTO_INCLUDE_KEY
```
  See Also:
  
  Constant Field Values
- TAG_SYNTAX_KEY
```
public static final String TAG_SYNTAX_KEY
```
  See Also:
  
  Constant Field Values
- TEMPLATE_LOADER_KEY
```
public static final String TEMPLATE_LOADER_KEY
```
  See Also:
  
  Constant Field Values
- INCOMPATIBLE_IMPROVEMENTS
```
public static final String INCOMPATIBLE_IMPROVEMENTS
```
  See Also:
  
  Constant Field Values
- INCOMPATIBLE_ENHANCEMENTS
```
public static final String INCOMPATIBLE_ENHANCEMENTS
```
  Deprecated. Use INCOMPATIBLE_IMPROVEMENTS instead.
  
  See Also:
  
  Constant Field Values
- AUTO_DETECT_TAG_SYNTAX
```
public static final int AUTO_DETECT_TAG_SYNTAX
```
  See Also:
  
  Constant Field Values
- ANGLE_BRACKET_TAG_SYNTAX
```
public static final int ANGLE_BRACKET_TAG_SYNTAX
```
  See Also:
  
  Constant Field Values
- SQUARE_BRACKET_TAG_SYNTAX
```
public static final int SQUARE_BRACKET_TAG_SYNTAX
```
  See Also:
  
  Constant Field Values
- VERSION_2_3_0
```
public static final Version VERSION_2_3_0
```
  FreeMarker version 2.3.0 (an incompatible improvements break-point)
- VERSION_2_3_19
```
public static final Version VERSION_2_3_19
```
  FreeMarker version 2.3.19 (an incompatible improvements break-point)
- VERSION_2_3_20
```
public static final Version VERSION_2_3_20
```
  FreeMarker version 2.3.20 (an incompatible improvements break-point)
- VERSION_2_3_21
```
public static final Version VERSION_2_3_21
```
  FreeMarker version 2.3.21 (an incompatible improvements break-point)
- DEFAULT_INCOMPATIBLE_IMPROVEMENTS
```
public static final Version DEFAULT_INCOMPATIBLE_IMPROVEMENTS
```
  The default of getIncompatibleImprovements(), currently new Version(2, 3, 0).
- DEFAULT_INCOMPATIBLE_ENHANCEMENTS
```
public static final String DEFAULT_INCOMPATIBLE_ENHANCEMENTS
```
  Deprecated. Use DEFAULT_INCOMPATIBLE_IMPROVEMENTS instead.
- PARSED_DEFAULT_INCOMPATIBLE_ENHANCEMENTS
```
public static final int PARSED_DEFAULT_INCOMPATIBLE_ENHANCEMENTS
```
  Deprecated. Use DEFAULT_INCOMPATIBLE_IMPROVEMENTS instead.

Constructor Detail
- Configuration
```
public Configuration()
```
  Deprecated. Use Configuration(Version) instead. Note that the version can be still modified later with setIncompatibleImprovements(Version) (or Configurable.setSettings(Properties)).
- Configuration
```
public Configuration(Version incompatibleImprovements)
```
  Creates a new instance and sets which of the non-backward-compatible bugfixes/improvements should be enabled. Note that the specified versions corresponds to the incompatible_improvements configuration setting, and can be changed later, with setIncompatibleImprovements(Version) for example.
  About the "incompatible improvements" setting
  The setting value is the FreeMarker version number where the bugfixes/improvements to enable were already implemented (but possibly wasn't active by default, as that would break backward-compatibility).
  The default value is 2.3.0 for maximum backward-compatibility when upgrading freemkarer.jar under an existing application. For actively developed applications usually you should set this to the highest possible value where the 1st or 2nd version is still the same as in the version where you have started development. As far as the 1st and 2nd version number remains, these changes are always very low-risk, so usually they don't break anything. Of course, you are still encouraged to read the list of changes below.
  Note that at FreeMarker minor (2nd) or major (1st) version number increments, it's possible that emulating some of the old bugs will become unsupported, that is, even if you set this setting to a low value, it silently wont bring back the old behavior anymore.
  This setting doesn't affect important not-fully-backward compatible security fixes; they are always enabled, regardless of what you set here.
  Currently the effects of this setting are:
  - 2.3.0: This is the lowest supported value, the version used in older projects. This is the default in the FreeMarker 2.3.x series.
  - 2.3.19 (or higher): Bug fix: Wrong # tags were printed as static text instead of causing parsing error when there was no correct # or @ tag earlier in the same template.
  - 2.3.20 (or higher): ?html will escape apostrophe-quotes just like ?xhtml does. Utilizing this is highly recommended, because otherwise if interpolations are used inside attribute values that use apostrophe-quotation (<foo bar='${val}'>) instead of plain quotation mark (<foo bar="${val}">), they might produce HTML/XML that's not well-formed. Note that ?html didn't do this because long ago there was no cross-browser way of doing this, but it's not a concern anymore.
  - 2.3.21 (or higher):
    - The default of the object_wrapper setting (Configurable.getObjectWrapper()) changes from ObjectWrapper.DEFAULT_WRAPPER to another almost identical DefaultObjectWrapper singleton, returned by DefaultObjectWrapperBuilder.build(). The new default object wrapper's "incompatible improvements" version is set to the same as of the Configuration. See BeansWrapper.BeansWrapper(Version) for further details. Furthermore, the new default object wrapper doesn't allow changing its settings; setter methods throw IllegalStateException). (If anything tries to call setters on the old default in your application, that's a dangerous bug that won't remain hidden now. As the old default is a singleton too, potentially shared by independently developed components, most of them expects the out-of-the-box behavior from it (and the others are necessarily buggy). Also, then concurrency glitches can occur (and even pollute the class introspection cache) because the singleton is modified after publishing to other threads.) Furthermore the new default object wrapper shares class introspection cache with other BeansWrapper-s created with BeansWrapperBuilder, which has an impact as BeansWrapper.clearClassIntrospecitonCache() will be disallowed; see more about it there.
    - The ?iso_... built-ins won't show the time zone offset for Time values anymore, because most databases store time values that aren't in any time zone, but just store hour, minute, second, and decimal second field values. If you still want to show the offset (like for PostgreSQL "time with time zone" columns you should), you can force showing the time zone offset by using myTime?string.iso_fz (and its other variants).
    - ?is_enumerable correctly returns false for Java methods get from Java objects that are wrapped with BeansWrapper and its subclasses, like DefaultObjectWrapper. Although method values implement TemplateSequenceModel (because of a historical design quirk in BeansWrapper), trying to #list them will cause error, hence they aren't enumerable.
    - ?c will return "INF", "-INF" and "NaN" for positive/negative infinity and IEEE floating point Not-a-Number, respectively. These are the XML Schema compatible representations of these special values. Earlier it has returned what DecimalFormat did with US locale, none of which was understood by any (common) computer language.
    - FTL hash literals that repeat keys now only have the key once with ?keys, and only has the last value associated to that key with ?values. This is consistent with the behavior of hash[key] and how maps work in Java.
    - In most cases (where FreeMarker is able to do that), for TemplateLoader-s that use URLConnection, URLConnection#setUseCaches(boolean) will called with false, so that only FreeMarker will do caching, not the URL scheme's handler. See URLTemplateLoader.setURLConnectionUsesCaches(Boolean) for more details.
    - The default of the template_loader setting (getTemplateLoader()) changes to null, which means that FreeMarker will not find any templates. Earlier the default was a FileTemplateLoader that used the current directory as the root. This was dangerous and fragile as you usually don't have good control over what the current directory will be. Luckily, the old default almost never looked for the templates at the right place anyway, so pretty much all applications had to set the template_loader setting, so it's unlikely that changing the default breaks your application.
    - Right-unlimited ranges become readable (like listable), so <#list 1.. as i>...</#list> works. Earlier they were only usable for slicing (like hits[10..]).
    - Empty ranges return Constants.EMPTY_SEQUENCE instead of an empty SimpleSequence. This is in theory backward compatible, as the API only promises to give something that implements TemplateSequenceModel.
    - Unclosed comments (<#-- ...) and #noparse-s won't be silently closed at the end of template anymore, but cause a parsing error instead.
  Throws:
  
  IllegalArgumentException - if incompatibleImmprovements is greater than the current FreeMarker version, or less than 2.3.0.
  
  Since:
  
  2.3.21

Method Detail

clone
```
public Object clone()
```
Overrides:

clone in class Configurable

loadBuiltInEncodingMap

public void loadBuiltInEncodingMap()

Loads a preset language-to-encoding map, similarly as if you have called clearEncodingMap() and then did multiple setEncoding(Locale, String) calls. 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:

ar	ISO-8859-6
be	ISO-8859-5
bg	ISO-8859-5
ca	ISO-8859-1
cs	ISO-8859-2
da	ISO-8859-1
de	ISO-8859-1
el	ISO-8859-7
en	ISO-8859-1
es	ISO-8859-1
et	ISO-8859-1
fi	ISO-8859-1
fr	ISO-8859-1
hr	ISO-8859-2
hu	ISO-8859-2
is	ISO-8859-1
it	ISO-8859-1
iw	ISO-8859-8
ja	Shift_JIS
ko	EUC-KR
lt	ISO-8859-2
lv	ISO-8859-2
mk	ISO-8859-5
nl	ISO-8859-1
no	ISO-8859-1
pl	ISO-8859-2
pt	ISO-8859-1
ro	ISO-8859-2
ru	ISO-8859-5
sh	ISO-8859-5
sk	ISO-8859-2
sl	ISO-8859-2
sq	ISO-8859-2
sr	ISO-8859-5
sv	ISO-8859-1
tr	ISO-8859-9
uk	ISO-8859-5
zh	GB2312
zh_TW	Big5

See Also:: clearEncodingMap(), setEncoding(Locale, String), setDefaultEncoding(String)

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

See Also:

loadBuiltInEncodingMap(), setEncoding(java.util.Locale, java.lang.String)

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.

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().

setTemplateLoader
```
public void setTemplateLoader(TemplateLoader templateLoader)
```
Sets a TemplateLoader that is used to look up and load templates; as a side effect the template cache will be emptied. By providing your own TemplateLoader implementation, you can load templates from whatever kind of storages, like from relational databases, NoSQL-storages, etc.
Convenience methods exists to install commonly used loaders, instead of using this method: setClassForTemplateLoading(Class, String), setDirectoryForTemplateLoading(File), and setServletContextForTemplateLoading(Object, String).
You can chain several TemplateLoader-s together with MultiTemplateLoader.
Default value: You should always set the template loader instead of relying on the default value. (But if you still care what it is, before "incompatible improvements" 2.3.21 it's a FileTemplateLoader that uses the current directory as its root; as it's hard tell what that directory will be, it's not very useful and dangerous. Starting with "incompatible improvements" 2.3.21 the default is null.)
Note that setting the template loader will re-create the template cache, so all its content will be lost.

getTemplateLoader
```
public TemplateLoader getTemplateLoader()
```
The getter pair of setTemplateLoader(TemplateLoader).

setCacheStorage
```
public void setCacheStorage(CacheStorage storage)
```
Sets the CacheStorage used for caching Template-s; the earlier content of the template cache will be dropt. The default is a SoftCacheStorage. If the total size of the Template objects is significant but most templates are used rarely, using a MruCacheStorage instead might be advisable. If you don't want caching at all, use NullCacheStorage (you can't use null).
Note that setting the cache storage will re-create the template cache, so all its content will be lost.

getCacheStorage
```
public CacheStorage getCacheStorage()
```
The getter pair of setCacheStorage(CacheStorage).

Since:

2.3.20

setDirectoryForTemplateLoading
```
public void setDirectoryForTemplateLoading(File dir)
                                    throws IOException
```
Sets the file system directory from which to load templates. This is equivalent to setTemplateLoader(new FileTemplateLoader(dir)), so see FileTemplateLoader.FileTemplateLoader(File) for more details. Note that FreeMarker can load templates from non-file-system sources too. See setTemplateLoader(TemplateLoader) from more details.

Throws:

IOException

setServletContextForTemplateLoading
```
public void setServletContextForTemplateLoading(Object servletContext,
                                                String path)
```
Sets the servlet context from which to load templates. This is equivalent to setTemplateLoader(new WebappTemplateLoader(sctxt, path)) or setTemplateLoader(new WebappTemplateLoader(sctxt)) if path was null, so see WebappTemplateLoader for more details.

Parameters:

servletContext - the ServletContext object. (The declared type is Object to prevent class loading error when using FreeMarker in an environment where there's no servlet classes available.)

path - the path relative to the ServletContext.

See Also:

setTemplateLoader(TemplateLoader)

setClassForTemplateLoading
```
public void setClassForTemplateLoading(Class clazz,
                                       String pathPrefix)
```
Sets a class relative to which we do the Class.getResource() call to load templates. This is equivalent to setTemplateLoader(new ClassTemplateLoader(clazz, pathPrefix)), so see ClassTemplateLoader.ClassTemplateLoader(Class, String) for more details.

See Also:

setTemplateLoader(TemplateLoader)

setTemplateUpdateDelay
```
public void setTemplateUpdateDelay(int seconds)
```
Sets the time in seconds that must elapse before checking whether there is a newer version of a template file than the cached one.
Historical note: Despite what the API documentation said earlier, this method is not thread-safe. While it works well on most hardware, it's not guaranteed that FreeMarker will see the update in all threads, and theoretically it's also possible that it will see a value that's a binary mixture of the new and the old one.

setStrictSyntaxMode
```
public void setStrictSyntaxMode(boolean b)
```
Deprecated. Only true (the default) value will be supported sometimes in the future.

Sets whether directives such as if, else, etc must be written as #if, #else, etc. Defaults to true.
When this is true, any tag not starting with <# or </# or <@ 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).

setObjectWrapper
```
public void setObjectWrapper(ObjectWrapper objectWrapper)
```
Description copied from class: Configurable

Sets the object wrapper used to wrap objects to TemplateModel-s. The default is ObjectWrapper.DEFAULT_WRAPPER.

Overrides:

setObjectWrapper in class Configurable

getStrictSyntaxMode
```
public boolean getStrictSyntaxMode()
```
The getter pair of setStrictSyntaxMode(boolean).

setIncompatibleImprovements
```
public void setIncompatibleImprovements(Version incompatibleImprovements)
```
Use Configuration(Version) instead if possible; see the meaning of the parameter there. If the default value of a setting depends on the incompatibleImprovements and the value of that setting was never set in this Configuration object through the public API, its value will be set to the default value appropriate for the new incompatibleImprovements. (This adjustment of a setting value doesn't count as setting that setting, so setting incompatibleImprovements for multiple times also works as expected.) Note that if the template_loader have to be changed because of this, the template cache will be emptied.

Throws:

IllegalArgumentException - if incompatibleImmprovements is greater than the current FreeMarker version, or less than 2.3.0, or null.

Since:

2.3.20

getIncompatibleImprovements
```
public Version getIncompatibleImprovements()
```
Returns:

Never null.

Since:

2.3.20

See Also:

setIncompatibleImprovements(Version)

setIncompatibleEnhancements
```
public void setIncompatibleEnhancements(String version)
```
Deprecated. Use Configuration(Version), or as last chance, setIncompatibleImprovements(Version) instead.

getIncompatibleEnhancements
```
public String getIncompatibleEnhancements()
```
Deprecated. Use getIncompatibleImprovements() instead.

getParsedIncompatibleEnhancements
```
public int getParsedIncompatibleEnhancements()
```
Deprecated. Use getIncompatibleImprovements() instead.

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

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

See Also:

setWhitespaceStripping(boolean)

setTagSyntax
```
public void setTagSyntax(int tagSyntax)
```
Determines the syntax of the template files (angle bracket VS square bracket) that has no #ftl in it. The tagSyntax parameter must be one of:
- AUTO_DETECT_TAG_SYNTAX: use the syntax of the first FreeMarker tag (can be anything, like #list, #include, user defined, etc.)
- ANGLE_BRACKET_TAG_SYNTAX: use the angle bracket syntax (the normal syntax)
- SQUARE_BRACKET_TAG_SYNTAX: use the square bracket syntax
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's 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.

getTagSyntax
```
public int getTagSyntax()
```
The getter pair of setTagSyntax(int).

getTemplate
```
public Template getTemplate(String name)
                     throws IOException
```
Retrieves the template with the given name from the template cache, loading it into the cache first if it's missing/staled.
This is a shorthand for getTemplate(name, getLocale(), getEncoding(getLocale()), true, false); see more details there.
See Configuration for an example of basic usage.

Throws:

IOException

getTemplate

public Template getTemplate(String name,
                            Locale locale)
                     throws IOException

Shorthand for getTemplate(name, locale, getEncoding(locale), true, false).

Throws:: IOException

getTemplate

public Template getTemplate(String name,
                            String encoding)
                     throws IOException

Shorthand for getTemplate(name, getLocale(), encoding, true, false).

Throws:: IOException

getTemplate

public Template getTemplate(String name,
                            Locale locale,
                            String encoding)
                     throws IOException

Shorthand for getTemplate(name, locale, encoding, true, false).

Throws:: IOException

getTemplate

public Template getTemplate(String name,
                            Locale locale,
                            String encoding,
                            boolean parseAsFTL)
                     throws IOException

Shorthand for getTemplate(name, locale, encoding, parseAsFTL, false).

Throws:: IOException

getTemplate
```
public Template getTemplate(String name,
                            Locale locale,
                            String encoding,
                            boolean parseAsFTL,
                            boolean ignoreMissing)
                     throws IOException
```
Retrieves the template with the given name (and according the specified further parameters) from the template cache, loading it into the cache first if it's missing/staled.
This method is thread-safe.
See Configuration for an example of basic usage.

Parameters:

name - The name or path of the template, which is not a real path, but interpreted inside the current TemplateLoader. Can't be null. The exact syntax of the name is interpreted by the underlying TemplateLoader, but the cache makes some assumptions. First, the name is expected to be a hierarchical path, with path components separated by a slash character (not with backslash!). The path (the name) given here must not begin with slash; it's always interpreted relative to the "template root directory". Then, the .. and . path meta-elements will be resolved. For example, if the name is a/../b/./c.ftl, then it will be simplified to b/c.ftl. The rules regarding this are the same as with conventional UN*X paths. The path must not reach outside the template root directory, that is, it can't be something like "../templates/my.ftl" (not even if this path happens to be equivalent with "/my.ftl"). Further, the path is allowed to contain at most one path element whose name is * (asterisk). This path meta-element triggers the acquisition mechanism. If the template is not found in the location described by the concatenation of the path left to the asterisk (called base path) and the part to the right of the asterisk (called resource path), the cache will attempt to remove the rightmost path component from the base path ("go up one directory") and concatenate that with the resource path. The process is repeated until either a template is found, or the base path is completely exhausted.

locale - The requested locale of the template. Can't be null. Assuming you have specified en_US as the locale and myTemplate.ftl as the name of the template, the cache will first try to retrieve myTemplate_en_US.html, then myTemplate.en.ftl, and finally myTemplate.ftl.

encoding - The charset used to interpret the template source code bytes. Can't be null.

parseAsFTL - If true, the loaded template is parsed and interpreted normally, as a regular FreeMarker template. If false, the loaded template is treated as a static text, so ${...}, <#...> etc. will not have special meaning in it.

ignoreMissing - If true, the method won't throw FileNotFoundException if the template doesn't exist, instead it returns null. Other kind of exceptions won't be suppressed.

Returns:

the requested template; maybe null when the ignoreMissing parameter is true.

Throws:

FileNotFoundException - if the template could not be found.

IOException - if there was a problem loading the template.

ParseException - (extends IOException) if the template is syntactically bad.

Since:

2.3.21

setDefaultEncoding
```
public void setDefaultEncoding(String encoding)
```
Sets the charset used for decoding byte sequences to character sequences when reading template files in a locale for which no explicit encoding was specified via setEncoding(Locale, String). Note that by default there is no locale specified for any locale, so the default encoding is always in effect.
Defaults to the default system encoding, which can change from one server to another, so you should always set this setting. If you don't know what charset your should chose, "UTF-8" is usually a good choice.
Note that individual templates may specify their own charset by starting with <#ftl encoding="...">

Parameters:

encoding - The name of the charset, such as "UTF-8" or "ISO-8859-1"

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 locale)
```
Gets the preferred character encoding for the given locale, or the default encoding if no encoding is set explicitly for the specified locale. You can associate encodings with locales using setEncoding(Locale, String) or loadBuiltInEncodingMap().

setEncoding
```
public void setEncoding(Locale locale,
                        String encoding)
```
Sets the character set encoding to use for templates of a given locale. If there is no explicit encoding set for some locale, then the default encoding will be used, what you can set with setDefaultEncoding(java.lang.String).

See Also:

clearEncodingMap(), loadBuiltInEncodingMap()

setSharedVariable
```
public void setSharedVariable(String name,
                              TemplateModel tm)
```
Adds a shared variable to the configuration. Shared sharedVariables are sharedVariables that are visible as top-level sharedVariables 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 sharedVariables, if the configuration is used by multiple threads! It is the typical situation for Servlet based Web sites.
This method is not thread safe; use it with the same restrictions as those that modify setting values.

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.

See Also:

setAllSharedVariables(freemarker.template.TemplateHashModelEx), setSharedVariable(String,Object)

getSharedVariableNames
```
public Set getSharedVariableNames()
```
Returns the set containing the names of all defined shared sharedVariables. 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.

setSharedVariable
```
public void setSharedVariable(String name,
                              Object value)
                       throws TemplateModelException
```
Adds shared variable to the configuration; It uses Configurable.getObjectWrapper() to wrap the value, so it's important that the object wrapper is set before this.
This method is not thread safe; use it with the same restrictions as those that modify setting values.
The added value should be thread safe, if you are running templates from multiple threads with this configuration.

Throws:

TemplateModelException - If some of the variables couldn't be wrapped via Configurable.getObjectWrapper().

See Also:

setSharedVaribles(Map), setSharedVariable(String,TemplateModel), setAllSharedVariables(TemplateHashModelEx)

setSharedVaribles
```
public void setSharedVaribles(Map map)
                       throws TemplateModelException
```
Replaces all shared variables (removes all previously added ones).
The values in the map can be TemplateModel-s or plain Java objects which will be immediately converted to TemplateModel with the ObjectWrapper returned by Configurable.getObjectWrapper(). If setObjectWrapper(ObjectWrapper) is called later, this conversion will be re-applied. Thus, ignoring some extra resource usage, it doesn't mater if in what order are setObjectWrapper(ObjectWrapper) and setSharedVaribles(Map) called. This is essential when you don't have control over the order in which the setters are called.
The values in the map must be thread safe, if you are running templates from multiple threads with this configuration. This means that both the plain Java object and the TemplateModel-s created from them by the ObjectWrapper must be thread safe. (The standard ObjectWrapper-s of FreeMarker create thread safe TemplateModel-s.) The Map itself need not be thread-safe.
This setter method has no getter pair because of the tricky relation ship with setSharedVariable(String, Object).

Throws:

TemplateModelException - If some of the variables couldn't be wrapped via Configurable.getObjectWrapper().

Since:

2.3.21

setAllSharedVariables
```
public void setAllSharedVariables(TemplateHashModelEx hash)
                           throws TemplateModelException
```
Adds all object in the hash as shared variable to the configuration; it's like doing several setSharedVariable(String, Object) calls, one for each hash entry. It doesn't remove the already added shared variable before doing this.
Never use TemplateModel implementation that is not thread-safe for shared shared variable values, if the configuration is used by multiple threads! It is the typical situation for Servlet based Web sites.
This method is not thread safe; use it with the same restrictions as those that modify setting values.

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.

Throws:

TemplateModelException

See Also:

setSharedVariable(String,Object), setSharedVariable(String,TemplateModel)

getSharedVariable
```
public TemplateModel getSharedVariable(String name)
```
Gets a shared variable. Shared sharedVariables are sharedVariables 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 sharedVariables that are always available through this method, see the FreeMarker manual for a comprehensive list of them.

See Also:

setSharedVariable(String,Object), setSharedVariable(String,TemplateModel), setAllSharedVariables(freemarker.template.TemplateHashModelEx)

clearSharedVariables
```
public void clearSharedVariables()
```
Removes all shared sharedVariables, 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 processes templates.

removeTemplateFromCache
```
public void removeTemplateFromCache(String name)
                             throws IOException
```
Equivalent to removeTemplateFromCache(name, thisCfg.getLocale(), thisCfg.getEncoding(thisCfg.getLocale()), true).

Throws:

IOException

Since:

2.3.19

removeTemplateFromCache

public void removeTemplateFromCache(String name,
                                    Locale locale)
                             throws IOException

Equivalent to removeTemplateFromCache(name, locale, thisCfg.getEncoding(locale), true).

Throws:: IOException
Since:: 2.3.19

removeTemplateFromCache

public void removeTemplateFromCache(String name,
                                    String encoding)
                             throws IOException

Equivalent to removeTemplateFromCache(name, thisCfg.getLocale(), encoding, true).

Throws:: IOException
Since:: 2.3.19

removeTemplateFromCache

public void removeTemplateFromCache(String name,
                                    Locale locale,
                                    String encoding)
                             throws IOException

Equivalent to removeTemplateFromCache(name, locale, encoding, true).

Throws:: IOException
Since:: 2.3.19

removeTemplateFromCache
```
public void removeTemplateFromCache(String name,
                                    Locale locale,
                                    String encoding,
                                    boolean parse)
                             throws IOException
```
Removes a template from the template cache, hence forcing the re-loading of it when it's next time requested. This is to give the application finer control over cache updating than setTemplateUpdateDelay(int) alone does.
For the meaning of the parameters, see getTemplate(String, Locale, String, boolean).
This method is thread-safe and can be called while the engine processes templates.

Throws:

IOException

Since:

2.3.19

getLocalizedLookup
```
public boolean getLocalizedLookup()
```
The getter pair of setLocalizedLookup(boolean).
This method is thread-safe and can be called while the engine works.

setLocalizedLookup
```
public void setLocalizedLookup(boolean localizedLookup)
```
Enables/disables localized template lookup. Enabled by default.
Localized lookup works like this: Let's say your locale setting is "en_AU", and you call cfg.getTemplate("foo.ftl"). Then FreeMarker will look for the template under names, stopping at the first that exists: "foo_en_AU.ftl", "foo_en.ftl", "foo.ftl".
Historical note: Despite what the API documentation said earlier, this method is not thread-safe. While setting it can't cause any serious problems, and in fact it works well on most hardware, it's not guaranteed that FreeMarker will see the update in all threads.

setSetting

public void setSetting(String name,
                       String value)
                throws TemplateException

Description copied from class: Configurable

Sets a FreeMarker setting by a name and string value. If you can configure FreeMarker directly with Java (or other programming language), you should use the dedicated setter methods instead (like Configurable.setObjectWrapper(ObjectWrapper). This meant to be used if you get the settings from somewhere as text. Regardless, below you will find an overview of the settings available no matter how you set them.

The list of settings commonly supported in all Configurable subclasses:

"locale": See Configurable.setLocale(Locale).
String value: local codes with the usual format in Java, such as "en_US".
"classic_compatible": See Configurable.setClassicCompatible(boolean) and Configurable.setClassicCompatibleAsInt(int).
String value: "true", "false", also since 2.3.20 0 or 1 or 2. (Also accepts "yes", "no", "t", "f", "y", "n".) Case insensitive.
"template_exception_handler": See Configurable.setTemplateExceptionHandler(TemplateExceptionHandler).
String value: If the value contains dot, then it's interpreted as an object builder expression. If the value does not contain dot, then it must be one of these predefined values (case insensitive): "rethrow" (means TemplateExceptionHandler.RETHROW_HANDLER), "debug" (means TemplateExceptionHandler.DEBUG_HANDLER), "html_debug" (means TemplateExceptionHandler.HTML_DEBUG_HANDLER), "ignore" (means TemplateExceptionHandler.IGNORE_HANDLER).
"arithmetic_engine": See Configurable.setArithmeticEngine(ArithmeticEngine).
String value: If the value contains dot, then it's interpreted as an object builder expression. If the value does not contain dot, then it must be one of these special values (case insensitive): "bigdecimal", "conservative".
"object_wrapper": See Configurable.setObjectWrapper(ObjectWrapper).
String value: If the value contains dot, then it's interpreted as an object builder expression, with the addition that BeansWrapper, DefaultObjectWrapper and SimpleObjectWrapper can be referred without package name. For example, these strings are valid values: "DefaultObjectWrapper(2.3.21)", "BeansWrapper(2.3.21, simpleMapWrapper=true)".
If the value does not contain dot, then it must be one of these special values (case insensitive): "default" (means ObjectWrapper.DEFAULT_WRAPPER or DefaultObjectWrapperBuilder.build()), "simple" (means ObjectWrapper.SIMPLE_WRAPPER), "beans" (means ObjectWrapper.BEANS_WRAPPER or BeansWrapperBuilder.build()), "jython" (means ObjectWrapper.DEFAULT_WRAPPER)
"number_format": See Configurable.setNumberFormat(String).
"boolean_format": See Configurable.setBooleanFormat(String) .
"date_format", "time_format", "datetime_format": See Configurable.setDateFormat(String), Configurable.setTimeFormat(String), Configurable.setDateTimeFormat(String).
"time_zone": See Configurable.setTimeZone(TimeZone).
String value: With the format as TimeZone.getTimeZone(java.lang.String) defines it. Also, since 2.3.21 "JVM default" can be used that will be replaced with the actual JVM default time zone when Configurable.setSetting(String, String) is called. For example "GMT-8:00" or "America/Los_Angeles"
If you set this setting, consider setting sql_date_and_time_time_zone too (see below)!
sql_date_and_time_time_zone: See Configurable.setSQLDateAndTimeTimeZone(TimeZone). Since 2.3.21.
String value: With the format as TimeZone.getTimeZone(java.lang.String) defines it. Also, "JVM default" can be used that will be replaced with the actual JVM default time zone when Configurable.setSetting(String, String) is called. Also "null" can be used, which has the same effect as setSQLDateAndTimeTimeZone(null).
"output_encoding": See Configurable.setOutputEncoding(String).
"url_escaping_charset": See Configurable.setURLEscapingCharset(String).
"auto_flush": See Configurable.setAutoFlush(boolean). Since 2.3.17.
String value: "true", "false", "y", etc.

"new_builtin_class_resolver": See Configurable.setNewBuiltinClassResolver(TemplateClassResolver). Since 2.3.17.
String value: If the value contains dot, then it's interpreted as an object builder expression. Otherwise the value must be one of these (ignore the quotation marks):

"unrestricted": Use TemplateClassResolver.UNRESTRICTED_RESOLVER
"safer": Use TemplateClassResolver.SAFER_RESOLVER
"allows_nothing": Use TemplateClassResolver.ALLOWS_NOTHING_RESOLVER

Something that contains colon will use OptInTemplateClassResolver and is expected to store comma separated values (possibly quoted) segmented with "allowed_classes:" and/or "trusted_templates:". Examples of valid values:

Setting value	Meaning
`allowed_classes: com.example.C1, com.example.C2, trusted_templates: lib/*, safe.ftl`	Only allow instantiating the `com.example.C1` and `com.example.C2` classes. But, allow templates within the `lib/` directory (like `lib/foo/bar.ftl`) and template `safe.ftl` (that does not match `foo/safe.ftl`, only exactly `safe.ftl`) to instantiate anything that `TemplateClassResolver.SAFER_RESOLVER` allows.
`allowed_classes: com.example.C1, com.example.C2`	Only allow instantiating the `com.example.C1` and `com.example.C2` classes. There are no trusted templates.
`trusted_templates: lib/*, safe.ftl`	Do not allow instantiating any classes, except in templates inside `lib/` or in template `safe.ftl`.

For more details see OptInTemplateClassResolver.

Otherwise if the value contains dot, it's interpreted as a full-qualified class name, and the object will be created with its parameterless constructor.

"show_error_tips": See Configurable.setShowErrorTips(boolean). Since 2.3.21.
String value: "true", "false", "y", etc.

Configuration (a subclass of Configurable) also understands these:

"auto_import": See setAutoImports(Map)
String value is something like:
/lib/form.ftl as f, /lib/widget as w, "/lib/odd name.ftl" as odd
"auto_include": Sets the list of auto-includes. See setAutoIncludes(List)
String value is something like:
/include/common.ftl, "/include/evil name.ftl"
"default_encoding": See setDefaultEncoding(String).
As the default value is the system default, which can change from one server to another, you should always set this!
"localized_lookup": See setLocalizedLookup(boolean).
String value: "true", "false" (also the equivalents: "yes", "no", "t", "f", "y", "n"). Case insensitive.
"strict_syntax": See setStrictSyntaxMode(boolean). Deprecated.
String value: "true", "false", yes, etc.
"whitespace_stripping": See setWhitespaceStripping(boolean).
String value: "true", "false", yes, etc.

"cache_storage": See setCacheStorage(freemarker.cache.CacheStorage).
String value: If the value contains dot, then it's interpreted as an object builder expression. 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 value	max. strong size	max. soft size
`"strong:50, soft:500"`	50	500
`"strong:100, soft"`	100	`Integer.MAX_VALUE`
`"strong:100"`	100	0
`"soft:100"`	0	100
`"strong"`	`Integer.MAX_VALUE`	0
`"soft"`	0	`Integer.MAX_VALUE`

The value is not case sensitive. The order of soft and strong entries is not significant.

"template_update_delay": See setTemplateUpdateDelay(int).
String value: Valid positive integer, the update delay measured in seconds.
"tag_syntax": See setTagSyntax(int).
String value: Must be one of "auto_detect", "angle_bracket", and "square_bracket".
"incompatible_improvements": See setIncompatibleImprovements(Version).
String value: version number like 2.3.20.
"incompatible_enhancements": See: setIncompatibleEnhancements(String). This setting name is deprecated, use "incompatible_improvements" instead.
"template_loader": See: setTemplateLoader(TemplateLoader).
String value: Interpreted as an object builder expression.

Regarding object builder expressions (used by the setting values where it was indicated):

Before FreeMarker 2.3.21 it had to be a fully qualified class name, and nothing else.
Since 2.3.21, the generic syntax is: className(constrArg1, constrArg2, ... constrArgN, propName1=propValue1, propName2=propValue2, ... propNameN=propValueN), where className is the fully qualified class name of the instance to create (except if we have builder class or INSTANCE field around, but see that later), constrArg-s are the values of constructor arguments, and propName=propValue-s set JavaBean properties (like x=1 means setX(1)) on the created instance. You can have any number of constructor arguments and property setters, including 0. Constructor arguments must precede any property setters.
Example: com.example.MyObjectWrapper(1, 2, exposeFields=true, cacheSize=5000) is nearly equivalent with this Java code: obj = new com.example.MyObjectWrapper(1, 2); obj.setExposeFields(true); obj.setCacheSize(5000);
If you have no constructor arguments and property setters, and the className class has a public static INSTANCE field, the value of that filed will be the value of the expression, and the constructor won't be called.
If there exists a class named classNameBuilder, then that class will be instantiated instead with the given constructor arguments, and the JavaBean properties of that builder instance will be set. After that, the public build() method of the instance will be called, whose return value will be the value of the whole expression. (The builder class and the build() method is simply found by name, there's no special interface to implement.) Note that if you use the backward compatible syntax, where these's no parenthesis after the class name, then it will not look for builder class.
Currently, the values of arguments and properties can only be one of these:
- A numerical literal, like 123 or -1.5. Like in FTL, there are no numerical types, the value will be automatically converted to the type of the target.
- A boolean literal: true or false
- The null literal: null
- A string literal with FTL syntax, except that it can't contain ${...}-s and #{...}-s. Examples: "Line 1\nLine 2" or r"C:\temp".
- An object builder expression. That is, object builder expressions can be nested into each other.
The top-level object builder expressions may omit (). In that case, for backward compatibility, the INSTANCE field and the builder class is not searched, so the instance will be always created with its parameterless constructor. (This behavior will possibly change in 2.4.) The () can't be omitted for nested expressions.
The classes and methods that the expression meant to access must be all public.

Overrides:: setSetting in class Configurable
Parameters:: name - the name of the setting.; value - the string that describes the new value of the setting.
Throws:: Configurable.UnknownSettingException - if the name is wrong.; TemplateException - if the new value of the setting can't be set for any other reasons.

getCorrectedNameForUnknownSetting
```
protected String getCorrectedNameForUnknownSetting(String name)
```
Overrides:

getCorrectedNameForUnknownSetting in class Configurable

Parameters:

name - The wrong name

Returns:

The corrected name, or null if there's no known correction

addAutoImport
```
public void addAutoImport(String namespaceVarName,
                          String templateName)
```
Adds an invisible #import templateName as namespaceVarName at the beginning of all templates. The order of the imports will be the same as the order in which they were added with this method.

removeAutoImport
```
public void removeAutoImport(String namespaceVarName)
```
Removes an auto-import; see addAutoImport(String, String). Does nothing if the auto-import doesn't exist.

setAutoImports
```
public void setAutoImports(Map map)
```
Removes all auto-imports, then calls addAutoImport(String, String) for each Map-entry (the entry key is the namespaceVarName). The order of the auto-imports will be the same as Map.keySet() returns the keys, thus, it's not the best idea to use a HashMap (although the order of imports doesn't mater for properly designed libraries).

doAutoImportsAndIncludes

protected void doAutoImportsAndIncludes(Environment env)
                                 throws TemplateException,
                                        IOException

Overrides:: doAutoImportsAndIncludes in class Configurable
Throws:: TemplateException; IOException

addAutoInclude
```
public void addAutoInclude(String templateName)
```
Adds an invisible #include templateName as namespaceVarName at the beginning of all templates. The order of the inclusions will be the same as the order in which they were added with this method.

setAutoIncludes
```
public void setAutoIncludes(List templateNames)
```
Removes all auto-includes, then calls addAutoInclude(String) for each List items.

removeAutoInclude
```
public void removeAutoInclude(String templateName)
```
Removes a template from the auto-include list; see addAutoInclude(String). Does nothing if the template is not there.

getVersionNumber
```
public static String getVersionNumber()
```
Deprecated. Use getVersion() instead.

Returns FreeMarker version number string.

getVersion
```
public static Version getVersion()
```
Returns the FreeMarker version information, most importantly the major.minor.micro version numbers. On FreeMarker version numbering rules:
- For final/stable releases the version number is like major.minor.micro, like 2.3.19. (Historically, when micro was 0 the version strings was like major.minor instead of the proper major.minor.0, but that's not like that anymore.)
- When only the micro version is increased, compatibility with previous versions with the same major.minor is kept. Thus freemarker.jar can be replaced in an existing application without breaking it.
- For non-final/unstable versions (that almost nobody uses), the format is:
  - Starting from 2.3.20: major.minor.micro-extraInfo, like 2.3.20-nightly_20130506T123456Z, 2.4.0-RC01. The major.minor.micro always indicates the target we move towards, so 2.3.20-nightly or 2.3.20-M01 is after 2.3.19 and will eventually become to 2.3.20. "PRE", "M" and "RC" (uppercase!) means "preview", "milestone" and "release candidate" respectively, and is always followed by a 2 digit 0-padded counter, like M03 is the 3rd milestone release of a given major.minor.micro.
  - Before 2.3.20: The extraInfo wasn't preceded by a "-". Instead of "nightly" there was "mod", where the major.minor.micro part has indicated where are we coming from, so 2.3.19mod (read as: 2.3.19 modified) was after 2.3.19 but before 2.3.20. Also, "pre" and "rc" was lowercase, and was followd by a number without 0-padding.
Since:

2.3.20

getDefaultObjectWrapper
```
public static ObjectWrapper getDefaultObjectWrapper(Version incompatibleImprovements)
```
Returns the default object wrapper for a given "incompatible_improvements" version.

Since:

2.3.21

See Also:

setIncompatibleImprovements(Version)

getSupportedBuiltInNames
```
public Set getSupportedBuiltInNames()
```
Returns the names of the supported "built-ins". These are the (expr?builtin_name-like things). As of this writing, this information doesn't depend on the configuration options, so it could be a static method, but to be future-proof, it's an instance method.

Returns:

Set of String-s.

Since:

2.3.20

getSupportedBuiltInDirectiveNames
```
public Set getSupportedBuiltInDirectiveNames()
```
Returns the names of the directives that are predefined by FreeMarker. These are the things that you call like <#directiveName ...>.

Returns:

Set of String-s.

Since:

2.3.21

Class Configuration

Nested Class Summary

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

Field Summary

Fields inherited from class freemarker.core.Configurable

Constructor Summary

Method Summary

Methods inherited from class freemarker.core.Configurable

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_ENCODING_KEY

LOCALIZED_LOOKUP_KEY

STRICT_SYNTAX_KEY

WHITESPACE_STRIPPING_KEY

CACHE_STORAGE_KEY

TEMPLATE_UPDATE_DELAY_KEY

AUTO_IMPORT_KEY

AUTO_INCLUDE_KEY

TAG_SYNTAX_KEY

TEMPLATE_LOADER_KEY

INCOMPATIBLE_IMPROVEMENTS

INCOMPATIBLE_ENHANCEMENTS

AUTO_DETECT_TAG_SYNTAX

ANGLE_BRACKET_TAG_SYNTAX

SQUARE_BRACKET_TAG_SYNTAX

VERSION_2_3_0

VERSION_2_3_19

VERSION_2_3_20

VERSION_2_3_21

DEFAULT_INCOMPATIBLE_IMPROVEMENTS

DEFAULT_INCOMPATIBLE_ENHANCEMENTS

PARSED_DEFAULT_INCOMPATIBLE_ENHANCEMENTS

Constructor Detail

Configuration

Configuration

Method Detail

clone

loadBuiltInEncodingMap

clearEncodingMap

getDefaultConfiguration

setDefaultConfiguration

setTemplateLoader

getTemplateLoader

setCacheStorage

getCacheStorage

setDirectoryForTemplateLoading

setServletContextForTemplateLoading

setClassForTemplateLoading

setTemplateUpdateDelay

setStrictSyntaxMode

setObjectWrapper

getStrictSyntaxMode

setIncompatibleImprovements

getIncompatibleImprovements

setIncompatibleEnhancements

getIncompatibleEnhancements

getParsedIncompatibleEnhancements

setWhitespaceStripping

getWhitespaceStripping

setTagSyntax

getTagSyntax

getTemplate

getTemplate

getTemplate

getTemplate

getTemplate

getTemplate

setDefaultEncoding

getDefaultEncoding

getEncoding

setEncoding

setSharedVariable

getSharedVariableNames

setSharedVariable

setSharedVaribles

setAllSharedVariables

getSharedVariable

clearSharedVariables

clearTemplateCache

removeTemplateFromCache