Package freemarker.template

Class Configuration

java.lang.Object

freemarker.core.Configurable

freemarker.template.Configuration

All Implemented Interfaces:

ParserConfiguration, Cloneable

public class Configuration
extends Configurable
implements Cloneable, ParserConfiguration

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 VERSION_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.ftlh");
  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) and setClassLoaderForTemplateLoading(ClassLoader, 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	Description
static int	ANGLE_BRACKET_TAG_SYNTAX	For example <#if x><@foo /></#if>
static int	AUTO_DETECT_NAMING_CONVENTION
static int	AUTO_DETECT_TAG_SYNTAX	The parser decides between ANGLE_BRACKET_TAG_SYNTAX and SQUARE_BRACKET_TAG_SYNTAX based on the first tag (like [#if x] or <#if x>) it mets.
static String	AUTO_ESCAPING_POLICY_KEY	Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.
static String	AUTO_ESCAPING_POLICY_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	AUTO_ESCAPING_POLICY_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.
static String	AUTO_IMPORT_KEY	Deprecated. Use Configurable.AUTO_IMPORT_KEY_SNAKE_CASE instead.
static String	AUTO_IMPORT_KEY_CAMEL_CASE	Deprecated. Use Configurable.AUTO_IMPORT_KEY_CAMEL_CASE instead.
static String	AUTO_IMPORT_KEY_SNAKE_CASE	Deprecated. Use Configurable.AUTO_IMPORT_KEY_SNAKE_CASE instead.
static String	AUTO_INCLUDE_KEY	Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.
static String	AUTO_INCLUDE_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	AUTO_INCLUDE_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.
static String	CACHE_STORAGE_KEY	Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.
static String	CACHE_STORAGE_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	CACHE_STORAGE_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.
static int	CAMEL_CASE_NAMING_CONVENTION
static String	DEFAULT_ENCODING_KEY	Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.
static String	DEFAULT_ENCODING_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	DEFAULT_ENCODING_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.
static String	DEFAULT_INCOMPATIBLE_ENHANCEMENTS	Deprecated. Use DEFAULT_INCOMPATIBLE_IMPROVEMENTS instead.
static Version	DEFAULT_INCOMPATIBLE_IMPROVEMENTS	The default of getIncompatibleImprovements(), currently VERSION_2_3_0.
static int	DISABLE_AUTO_ESCAPING_POLICY	Don't enable auto-escaping, regardless of what the OutputFormat is.
static int	DOLLAR_INTERPOLATION_SYNTAX	${expression} only (not #{expression; numFormat}) @since 2.3.28
static int	ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY	Enable auto-escaping if the output format supports it and MarkupOutputFormat.isAutoEscapedByDefault() is true.
static int	ENABLE_IF_SUPPORTED_AUTO_ESCAPING_POLICY	Enable auto-escaping if the OutputFormat supports it.
static String	FALLBACK_ON_NULL_LOOP_VARIABLE_KEY	Alias to the ..._SNAKE_CASE variation.
static String	FALLBACK_ON_NULL_LOOP_VARIABLE_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	FALLBACK_ON_NULL_LOOP_VARIABLE_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.
static int	FORCE_AUTO_ESCAPING_POLICY	This policy is to always require auto-escaping, to avoid accidents where because of misconfiguration, or a mistake of the template author it's disabled.
static String	INCOMPATIBLE_ENHANCEMENTS	Deprecated. Use INCOMPATIBLE_IMPROVEMENTS_KEY instead.
static String	INCOMPATIBLE_IMPROVEMENTS	Deprecated. Use INCOMPATIBLE_IMPROVEMENTS_KEY instead.
static String	INCOMPATIBLE_IMPROVEMENTS_KEY	Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.
static String	INCOMPATIBLE_IMPROVEMENTS_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	INCOMPATIBLE_IMPROVEMENTS_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.
static String	INTERPOLATION_SYNTAX_KEY	Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.
static String	INTERPOLATION_SYNTAX_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	INTERPOLATION_SYNTAX_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.
static int	LEGACY_INTERPOLATION_SYNTAX	${expression} and the deprecated #{expression; numFormat} @since 2.3.28
static int	LEGACY_NAMING_CONVENTION
static String	LOCALIZED_LOOKUP_KEY	Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.
static String	LOCALIZED_LOOKUP_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	LOCALIZED_LOOKUP_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.
static String	NAMING_CONVENTION_KEY	Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.
static String	NAMING_CONVENTION_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	NAMING_CONVENTION_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.
static String	OUTPUT_FORMAT_KEY	Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.
static String	OUTPUT_FORMAT_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	OUTPUT_FORMAT_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.
static int	PARSED_DEFAULT_INCOMPATIBLE_ENHANCEMENTS	Deprecated. Use DEFAULT_INCOMPATIBLE_IMPROVEMENTS instead.
static String	RECOGNIZE_STANDARD_FILE_EXTENSIONS_KEY	Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.
static String	RECOGNIZE_STANDARD_FILE_EXTENSIONS_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	RECOGNIZE_STANDARD_FILE_EXTENSIONS_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.
static String	REGISTERED_CUSTOM_OUTPUT_FORMATS_KEY	Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.
static String	REGISTERED_CUSTOM_OUTPUT_FORMATS_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	REGISTERED_CUSTOM_OUTPUT_FORMATS_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.
static int	SQUARE_BRACKET_INTERPOLATION_SYNTAX	[=expression] instead of ${expression}.
static int	SQUARE_BRACKET_TAG_SYNTAX	For example [#if x][@foo /][/#if].
static String	STRICT_SYNTAX_KEY	Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.
static String	STRICT_SYNTAX_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	STRICT_SYNTAX_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.
static String	TAB_SIZE_KEY	Alias to the ..._SNAKE_CASE variation.
static String	TAB_SIZE_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	TAB_SIZE_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.
static String	TAG_SYNTAX_KEY	Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.
static String	TAG_SYNTAX_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	TAG_SYNTAX_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.
static String	TEMPLATE_CONFIGURATIONS_KEY	Alias to the ..._SNAKE_CASE variation.
static String	TEMPLATE_CONFIGURATIONS_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	TEMPLATE_CONFIGURATIONS_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.
static String	TEMPLATE_LOADER_KEY	Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.
static String	TEMPLATE_LOADER_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	TEMPLATE_LOADER_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.
static String	TEMPLATE_LOOKUP_STRATEGY_KEY	Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.
static String	TEMPLATE_LOOKUP_STRATEGY_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	TEMPLATE_LOOKUP_STRATEGY_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.
static String	TEMPLATE_NAME_FORMAT_KEY	Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.
static String	TEMPLATE_NAME_FORMAT_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	TEMPLATE_NAME_FORMAT_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.
static String	TEMPLATE_UPDATE_DELAY_KEY	Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.
static String	TEMPLATE_UPDATE_DELAY_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	TEMPLATE_UPDATE_DELAY_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.
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 Version	VERSION_2_3_22	FreeMarker version 2.3.22 (an incompatible improvements break-point)
static Version	VERSION_2_3_23	FreeMarker version 2.3.23 (an incompatible improvements break-point)
static Version	VERSION_2_3_24	FreeMarker version 2.3.24 (an incompatible improvements break-point)
static Version	VERSION_2_3_25	FreeMarker version 2.3.25 (an incompatible improvements break-point)
static Version	VERSION_2_3_26	FreeMarker version 2.3.26 (an incompatible improvements break-point)
static Version	VERSION_2_3_27	FreeMarker version 2.3.27 (an incompatible improvements break-point)
static Version	VERSION_2_3_28	FreeMarker version 2.3.28 (an incompatible improvements break-point)
static Version	VERSION_2_3_29	FreeMarker version 2.3.29 (an incompatible improvements break-point)
static Version	VERSION_2_3_30	FreeMarker version 2.3.30 (an incompatible improvements break-point)
static Version	VERSION_2_3_31	FreeMarker version 2.3.31 (an incompatible improvements break-point)
static Version	VERSION_2_3_32	FreeMarker version 2.3.32 (an incompatible improvements break-point)
static Version	VERSION_2_3_33	FreeMarker version 2.3.33 (an incompatible improvements break-point)
static String	WHITESPACE_STRIPPING_KEY	Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.
static String	WHITESPACE_STRIPPING_KEY_CAMEL_CASE	Modern, camel case (likeThis) variation of the setting name.
static String	WHITESPACE_STRIPPING_KEY_SNAKE_CASE	Legacy, snake case (like_this) variation of the setting name.

Fields inherited from class freemarker.core.Configurable

API_BUILTIN_ENABLED_KEY, API_BUILTIN_ENABLED_KEY_CAMEL_CASE, API_BUILTIN_ENABLED_KEY_SNAKE_CASE, ARITHMETIC_ENGINE_KEY, ARITHMETIC_ENGINE_KEY_CAMEL_CASE, ARITHMETIC_ENGINE_KEY_SNAKE_CASE, ATTEMPT_EXCEPTION_REPORTER_KEY, ATTEMPT_EXCEPTION_REPORTER_KEY_CAMEL_CASE, ATTEMPT_EXCEPTION_REPORTER_KEY_SNAKE_CASE, AUTO_FLUSH_KEY, AUTO_FLUSH_KEY_CAMEL_CASE, AUTO_FLUSH_KEY_SNAKE_CASE, BOOLEAN_FORMAT_KEY, BOOLEAN_FORMAT_KEY_CAMEL_CASE, BOOLEAN_FORMAT_KEY_SNAKE_CASE, C_FORMAT_KEY, C_FORMAT_KEY_CAMEL_CASE, C_FORMAT_KEY_SNAKE_CASE, CLASSIC_COMPATIBLE_KEY, CLASSIC_COMPATIBLE_KEY_CAMEL_CASE, CLASSIC_COMPATIBLE_KEY_SNAKE_CASE, CUSTOM_DATE_FORMATS_KEY, CUSTOM_DATE_FORMATS_KEY_CAMEL_CASE, CUSTOM_DATE_FORMATS_KEY_SNAKE_CASE, CUSTOM_NUMBER_FORMATS_KEY, CUSTOM_NUMBER_FORMATS_KEY_CAMEL_CASE, CUSTOM_NUMBER_FORMATS_KEY_SNAKE_CASE, DATE_FORMAT_KEY, DATE_FORMAT_KEY_CAMEL_CASE, DATE_FORMAT_KEY_SNAKE_CASE, DATETIME_FORMAT_KEY, DATETIME_FORMAT_KEY_CAMEL_CASE, DATETIME_FORMAT_KEY_SNAKE_CASE, LAZY_AUTO_IMPORTS_KEY, LAZY_AUTO_IMPORTS_KEY_CAMEL_CASE, LAZY_AUTO_IMPORTS_KEY_SNAKE_CASE, LAZY_IMPORTS_KEY, LAZY_IMPORTS_KEY_CAMEL_CASE, LAZY_IMPORTS_KEY_SNAKE_CASE, LOCALE_KEY, LOCALE_KEY_CAMEL_CASE, LOCALE_KEY_SNAKE_CASE, LOG_TEMPLATE_EXCEPTIONS_KEY, LOG_TEMPLATE_EXCEPTIONS_KEY_CAMEL_CASE, LOG_TEMPLATE_EXCEPTIONS_KEY_SNAKE_CASE, NEW_BUILTIN_CLASS_RESOLVER_KEY, NEW_BUILTIN_CLASS_RESOLVER_KEY_CAMEL_CASE, NEW_BUILTIN_CLASS_RESOLVER_KEY_SNAKE_CASE, NUMBER_FORMAT_KEY, NUMBER_FORMAT_KEY_CAMEL_CASE, NUMBER_FORMAT_KEY_SNAKE_CASE, OBJECT_WRAPPER_KEY, OBJECT_WRAPPER_KEY_CAMEL_CASE, OBJECT_WRAPPER_KEY_SNAKE_CASE, OUTPUT_ENCODING_KEY, OUTPUT_ENCODING_KEY_CAMEL_CASE, OUTPUT_ENCODING_KEY_SNAKE_CASE, SHOW_ERROR_TIPS_KEY, SHOW_ERROR_TIPS_KEY_CAMEL_CASE, SHOW_ERROR_TIPS_KEY_SNAKE_CASE, SQL_DATE_AND_TIME_TIME_ZONE_KEY, SQL_DATE_AND_TIME_TIME_ZONE_KEY_CAMEL_CASE, SQL_DATE_AND_TIME_TIME_ZONE_KEY_SNAKE_CASE, STRICT_BEAN_MODELS, STRICT_BEAN_MODELS_KEY, STRICT_BEAN_MODELS_KEY_CAMEL_CASE, STRICT_BEAN_MODELS_KEY_SNAKE_CASE, TEMPLATE_EXCEPTION_HANDLER_KEY, TEMPLATE_EXCEPTION_HANDLER_KEY_CAMEL_CASE, TEMPLATE_EXCEPTION_HANDLER_KEY_SNAKE_CASE, TIME_FORMAT_KEY, TIME_FORMAT_KEY_CAMEL_CASE, TIME_FORMAT_KEY_SNAKE_CASE, TIME_ZONE_KEY, TIME_ZONE_KEY_CAMEL_CASE, TIME_ZONE_KEY_SNAKE_CASE, TRUNCATE_BUILTIN_ALGORITHM_KEY, TRUNCATE_BUILTIN_ALGORITHM_KEY_CAMEL_CASE, TRUNCATE_BUILTIN_ALGORITHM_KEY_SNAKE_CASE, URL_ESCAPING_CHARSET_KEY, URL_ESCAPING_CHARSET_KEY_CAMEL_CASE, URL_ESCAPING_CHARSET_KEY_SNAKE_CASE, WRAP_UNCHECKED_EXCEPTIONS_KEY, WRAP_UNCHECKED_EXCEPTIONS_KEY_CAMEL_CASE, WRAP_UNCHECKED_EXCEPTIONS_KEY_SNAKE_CASE

Constructor Summary

Constructors

Constructor	Description
Configuration()	Deprecated. Use Configuration(Version) instead.
Configuration(Version incompatibleImprovements)	Creates a new instance and sets which of the non-backward-compatible bugfixes/improvements should be enabled.

Method Summary

Modifier and Type	Method	Description
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()
protected void	doAutoImportsAndIncludes(Environment env)	Executes the auto-imports and auto-includes for the main template of this environment.
int	getAutoEscapingPolicy()	Getter pair of setAutoEscapingPolicy(int)
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.
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.
boolean	getFallbackOnNullLoopVariable()	The getter pair of setFallbackOnNullLoopVariable(boolean).
String	getIncompatibleEnhancements()	Deprecated. Use getIncompatibleImprovements() instead.
Version	getIncompatibleImprovements()	See getIncompatibleImprovements().
int	getInterpolationSyntax()	The getter pair of setInterpolationSyntax(int).
boolean	getLocalizedLookup()	The getter pair of setLocalizedLookup(boolean).
int	getNamingConvention()	The getter pair of setNamingConvention(int).
OutputFormat	getOutputFormat()	Getter pair of setOutputFormat(OutputFormat)
OutputFormat	getOutputFormat(String name)	Returns the output format for a name.
int	getParsedIncompatibleEnhancements()	Deprecated. Use getIncompatibleImprovements() instead.
boolean	getRecognizeStandardFileExtensions()	Getter pair of setRecognizeStandardFileExtensions(boolean).
Collection<? extends OutputFormat>	getRegisteredCustomOutputFormats()	Getter pair of setRegisteredCustomOutputFormats(Collection).
Set<String>	getSettingNames(boolean camelCase)	Returns the valid Configuration setting names.
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()	Same as getSupportedBuiltInDirectiveNames(int) with argument getNamingConvention().
Set<String>	getSupportedBuiltInDirectiveNames(int namingConvention)	Returns the names of the directives that are predefined by FreeMarker.
Set	getSupportedBuiltInNames()	Same as getSupportedBuiltInNames(int) with argument getNamingConvention().
Set<String>	getSupportedBuiltInNames(int namingConvention)	Returns the names of the supported "built-ins".
int	getTabSize()	The getter pair of setTabSize(int).
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, String encoding)	Shorthand for getTemplate(name, null, null, encoding, true, false).
Template	getTemplate(String name, Locale locale)	Shorthand for getTemplate(name, locale, null, null, true, false).
Template	getTemplate(String name, Locale locale, Object customLookupCondition, 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, Locale locale, String encoding)	Shorthand for getTemplate(name, locale, null, encoding, true, false).
Template	getTemplate(String name, Locale locale, String encoding, boolean parseAsFTL)	Shorthand for getTemplate(name, locale, null, encoding, parseAsFTL, false).
Template	getTemplate(String name, Locale locale, String encoding, boolean parseAsFTL, boolean ignoreMissing)	Shorthand for getTemplate(name, locale, null, encoding, parseAsFTL, ignoreMissing).
TemplateConfigurationFactory	getTemplateConfigurations()	The getter pair of setTemplateConfigurations(TemplateConfigurationFactory).
TemplateLoader	getTemplateLoader()	The getter pair of setTemplateLoader(TemplateLoader).
TemplateLookupStrategy	getTemplateLookupStrategy()	The getter pair of setTemplateLookupStrategy(TemplateLookupStrategy).
TemplateNameFormat	getTemplateNameFormat()	The getter pair of setTemplateNameFormat(TemplateNameFormat).
long	getTemplateUpdateDelayMilliseconds()	The getter pair of setTemplateUpdateDelayMilliseconds(long).
static Version	getVersion()	Returns FreeMarker version information, most importantly the major.minor.micro version numbers; do NOT use this as the value of the incompatible_improvements setting (as the parameter to Configuration(Version)), as then your application can break when you upgrade FreeMarker! Use a constant value, like VERSION_2_3_28, to protect your application from fixes/changes that aren't entirely backward compatible.
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.
boolean	isAttemptExceptionReporterExplicitlySet()	Tells if setAttemptExceptionReporter(AttemptExceptionReporter) (or equivalent) was already called on this instance.
boolean	isCacheStorageExplicitlySet()	Tells if setCacheStorage(CacheStorage) (or equivalent) was already called on this instance.
boolean	isCFormatExplicitlySet()	Tells if setCFormat(CFormat) (or equivalent) was already called on this instance.
boolean	isDefaultEncodingExplicitlySet()	Tells if setDefaultEncoding(String) (or equivalent) was already called on this instance, or it just holds the default value.
boolean	isLocaleExplicitlySet()	Tells if setLocale(Locale) (or equivalent) was already called on this instance, or it just holds the default value.
boolean	isLogTemplateExceptionsExplicitlySet()	Tells if setLogTemplateExceptions(boolean) (or equivalent) was already called on this instance.
boolean	isObjectWrapperExplicitlySet()	Tells if setObjectWrapper(ObjectWrapper) (or equivalent) was already called on this instance.
boolean	isOutputFormatExplicitlySet()	Tells if setOutputFormat(OutputFormat) (or equivalent) was already called on this instance.
boolean	isRecognizeStandardFileExtensionsExplicitlySet()	Tells if setRecognizeStandardFileExtensions(boolean) (or equivalent) was already called on this instance.
boolean	isTemplateExceptionHandlerExplicitlySet()	Tells if setTemplateExceptionHandler(TemplateExceptionHandler) (or equivalent) was already called on this instance.
boolean	isTemplateLoaderExplicitlySet()	Tells if setTemplateLoader(TemplateLoader) (or equivalent) was already called on this instance.
boolean	isTemplateLookupStrategyExplicitlySet()	Tells if setTemplateLookupStrategy(TemplateLookupStrategy) (or equivalent) was already called on this instance.
boolean	isTemplateNameFormatExplicitlySet()	Tells if setTemplateNameFormat(TemplateNameFormat) (or equivalent) was already called on this instance.
boolean	isTimeZoneExplicitlySet()	Tells if setTimeZone(TimeZone) (or equivalent) was already called on this instance, or it just holds the default value.
boolean	isWrapUncheckedExceptionsExplicitlySet()	Tells if setWrapUncheckedExceptions(boolean) (or equivalent) was already called on this instance.
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	removeTemplateFromCache(String name)	Equivalent to removeTemplateFromCache(name, thisCfg.getLocale(), null, thisCfg.getEncoding(thisCfg.getLocale()), true).
void	removeTemplateFromCache(String name, String encoding)	Equivalent to removeTemplateFromCache(name, thisCfg.getLocale(), null, encoding, true).
void	removeTemplateFromCache(String name, Locale locale)	Equivalent to removeTemplateFromCache(name, locale, null, thisCfg.getEncoding(locale), true).
void	removeTemplateFromCache(String name, Locale locale, Object customLookupCondition, 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, Locale locale, String encoding)	Equivalent to removeTemplateFromCache(name, locale, null, encoding, true).
void	removeTemplateFromCache(String name, Locale locale, String encoding, boolean parse)	Equivalent to removeTemplateFromCache(name, locale, null, encoding, parse).
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	setAttemptExceptionReporter(AttemptExceptionReporter attemptExceptionReporter)	Specifies how exceptions handled (and hence suppressed) by an #attempt blocks will be logged or otherwise reported.
void	setAutoEscapingPolicy(int autoEscapingPolicy)	Sets when auto-escaping should be enabled depending on the current output format; default is ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY.
void	setCacheStorage(CacheStorage cacheStorage)	Sets the CacheStorage used for caching Template-s; the earlier content of the template cache will be dropt.
void	setCFormat(CFormat cFormat)	Sets the format (usually a computer language) used for ?c, ?cn, and for the "c" ("computer" before 2.3.32) number_format, and the "c" boolean_format.
void	setClassForTemplateLoading(Class resourceLoaderClass, String basePackagePath)	Sets the class whose Class.getResource(String) method will be used to load templates, from the inside the package specified.
void	setClassLoaderForTemplateLoading(ClassLoader classLoader, String basePackagePath)	Sets the ClassLoader whose ClassLoader.getResource(String) method will be used to load templates, from the inside the package specified.
static void	setDefaultConfiguration(Configuration config)	Deprecated. Using the "default" Configuration instance can easily lead to erroneous, unpredictable behaviour.
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	setFallbackOnNullLoopVariable(boolean fallbackOnNullLoopVariable)	Specifies the behavior when reading a loop variable (like i in <#list items as i>, or in <@myMacro items; i>) that's null (missing); if true, FreeMarker will look for a variable with the same name in higher variable scopes, or if false the variable will be simply null (missing).
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	setInterpolationSyntax(int interpolationSyntax)	Determines the interpolation syntax (like ${x} VS [=x]) of the template files.
void	setLocale(Locale locale)	Sets the locale used for number and date formatting (among others), also the locale used for searching localized template variations when no locale was explicitly requested.
void	setLocalizedLookup(boolean localizedLookup)	Enables/disables localized template lookup.
void	setLogTemplateExceptions(boolean value)	Specifies if TemplateException-s thrown by template processing are logged by FreeMarker or not.
void	setNamingConvention(int namingConvention)	Sets the naming convention used for the identifiers that are part of the template language.
void	setObjectWrapper(ObjectWrapper objectWrapper)	Sets the ObjectWrapper used to wrap objects to TemplateModel-s when using this Configurable.
void	setOutputFormat(OutputFormat outputFormat)	Sets the default output format.
void	setRecognizeStandardFileExtensions(boolean recognizeStandardFileExtensions)	Sets if the "file" extension part of the source name (Template.getSourceName()) will influence certain parsing settings.
void	setRegisteredCustomOutputFormats(Collection<? extends OutputFormat> registeredCustomOutputFormats)	Sets the custom output formats that can be referred by their unique name (OutputFormat.getName()) from templates.
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, TemplateModel tm)	Adds a shared variable to the configuration.
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	setSharedVariables(Map<String,?> map)	Replaces all shared variables (removes all previously added ones).
void	setSharedVaribles(Map map)	Deprecated. Use setSharedVariables(Map) instead.
void	setStrictSyntaxMode(boolean b)	Deprecated. Only true (the default) value will be supported sometimes in the future.
void	setTabSize(int tabSize)	Sets the assumed display width of the tab character (ASCII 9), which influences the column number shown in error messages (or the column number you get through other API-s).
void	setTagSyntax(int tagSyntax)	Determines the tag syntax (like <#if x> VS [#if x]) of the template files that has no #ftl header to decide that.
void	setTemplateConfigurations(TemplateConfigurationFactory templateConfigurations)	Sets a TemplateConfigurationFactory that will configure individual templates where their settings differ from those coming from the common Configuration object.
void	setTemplateExceptionHandler(TemplateExceptionHandler templateExceptionHandler)	Sets the exception handler used to handle exceptions occurring inside templates.
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 (unless the new and the old values are the same).
void	setTemplateLookupStrategy(TemplateLookupStrategy templateLookupStrategy)	Sets the TemplateLookupStrategy that is used to look up templates based on the requested name; as a side effect the template cache will be emptied.
void	setTemplateNameFormat(TemplateNameFormat templateNameFormat)	Sets the template name format used.
void	setTemplateUpdateDelay(int seconds)	Deprecated. Use setTemplateUpdateDelayMilliseconds(long) instead, because the time granularity of this method is often misunderstood to be milliseconds.
void	setTemplateUpdateDelayMilliseconds(long millis)	Sets the time in milliseconds that must elapse before checking whether there is a newer version of a template "file" than the cached one.
void	setTimeZone(TimeZone timeZone)	Sets the time zone to use when formatting date/time values.
void	setWhitespaceStripping(boolean b)	Sets whether the FTL parser will try to remove superfluous white-space around certain FTL tags.
void	setWrapUncheckedExceptions(boolean value)	Specifies if unchecked exceptions thrown during expression evaluation or during executing custom directives (and transform) will be wrapped into TemplateException-s, or will bubble up to the caller of Template.process(Object, Writer, ObjectWrapper) as is.
void	unsetAttemptExceptionReporter()	Resets the setting to its default, as if it was never set.
void	unsetCacheStorage()	Resets the setting to its default, as if it was never set.
void	unsetCFormat()	Resets the setting to its default, as if it was never set.
void	unsetDefaultEncoding()	Resets the setting to its default, as if it was never set.
void	unsetLocale()	Resets the setting to its default, as if it was never set.
void	unsetLogTemplateExceptions()	Resets the setting to its default, as if it was never set.
void	unsetObjectWrapper()	Resets the setting to its default, as if it was never set.
void	unsetOutputFormat()	Resets the setting to its default, as if it was never set.
void	unsetRecognizeStandardFileExtensions()	Resets the setting to its default, as if it was never set.
void	unsetTemplateExceptionHandler()	Resets the setting to its default, as if it was never set.
void	unsetTemplateLoader()	Resets the setting to its default, as if it was never set.
void	unsetTemplateLookupStrategy()	Resets the setting to its default, as if it was never set.
void	unsetTemplateNameFormat()	Resets the setting to its default, as if it was never set.
void	unsetTimeZone()	Resets the setting to its default, as if it was never set.
void	unsetWrapUncheckedExceptions()

Methods inherited from class freemarker.core.Configurable

addAutoImport, addAutoInclude, getArithmeticEngine, getAttemptExceptionReporter, getAutoFlush, getAutoImports, getAutoImportsWithoutFallback, getAutoIncludes, getAutoIncludesWithoutFallback, getBooleanFormat, getCFormat, getClassicCompatibleAsInt, getCustomAttribute, getCustomAttributeNames, getCustomDateFormat, getCustomDateFormats, getCustomDateFormatsWithoutFallback, getCustomNumberFormat, getCustomNumberFormats, getCustomNumberFormatsWithoutFallback, getDateFormat, getDateTimeFormat, getEnvironment, getLazyAutoImports, getLazyImports, getLocale, getLogTemplateExceptions, getNewBuiltinClassResolver, getNumberFormat, getObjectWrapper, getOutputEncoding, getParent, getSetting, getSettings, getShowErrorTips, getSQLDateAndTimeTimeZone, getTemplateExceptionHandler, getTimeFormat, getTimeZone, getTruncateBuiltinAlgorithm, getURLEscapingCharset, getWrapUncheckedExceptions, hasCustomFormats, invalidSettingValueException, isAPIBuiltinEnabled, isAPIBuiltinEnabledSet, isArithmeticEngineSet, isAttemptExceptionReporterSet, isAutoFlushSet, isAutoImportsSet, isAutoIncludesSet, isBooleanFormatSet, isCFormatSet, isClassicCompatible, isClassicCompatibleSet, isCustomDateFormatsSet, isCustomNumberFormatsSet, isDateFormatSet, isDateTimeFormatSet, isLazyAutoImportsSet, isLazyImportsSet, isLocaleSet, isLogTemplateExceptionsSet, isNewBuiltinClassResolverSet, isNumberFormatSet, isObjectWrapperSet, isOutputEncodingSet, isShowErrorTipsSet, isSQLDateAndTimeTimeZoneSet, isTemplateExceptionHandlerSet, isTimeFormatSet, isTimeZoneSet, isTruncateBuiltinAlgorithmSet, isURLEscapingCharsetSet, isWrapUncheckedExceptionsSet, parseAsImportList, parseAsList, parseAsSegmentedList, removeAutoImport, removeAutoInclude, removeCustomAttribute, setAPIBuiltinEnabled, setArithmeticEngine, setAutoFlush, setAutoImports, setAutoIncludes, setBooleanFormat, setClassicCompatible, setClassicCompatibleAsInt, setCustomAttribute, setCustomDateFormats, setCustomNumberFormats, setDateFormat, setDateTimeFormat, setLazyAutoImports, setLazyImports, setNewBuiltinClassResolver, setNumberFormat, setOutputEncoding, setSettings, setSettings, setShowErrorTips, setSQLDateAndTimeTimeZone, setStrictBeanModels, setTimeFormat, settingValueAssignmentException, setTruncateBuiltinAlgorithm, setURLEscapingCharset, unknownSettingException

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface freemarker.core.ParserConfiguration

getArithmeticEngine

Field Details

DEFAULT_ENCODING_KEY_SNAKE_CASE

public static final String DEFAULT_ENCODING_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

DEFAULT_ENCODING_KEY_CAMEL_CASE

public static final String DEFAULT_ENCODING_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

DEFAULT_ENCODING_KEY

public static final String DEFAULT_ENCODING_KEY

Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.

See Also:

Constant Field Values

LOCALIZED_LOOKUP_KEY_SNAKE_CASE

public static final String LOCALIZED_LOOKUP_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

LOCALIZED_LOOKUP_KEY_CAMEL_CASE

public static final String LOCALIZED_LOOKUP_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

LOCALIZED_LOOKUP_KEY

public static final String LOCALIZED_LOOKUP_KEY

Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.

See Also:

Constant Field Values

STRICT_SYNTAX_KEY_SNAKE_CASE

public static final String STRICT_SYNTAX_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

STRICT_SYNTAX_KEY_CAMEL_CASE

public static final String STRICT_SYNTAX_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

STRICT_SYNTAX_KEY

public static final String STRICT_SYNTAX_KEY

Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.

See Also:

Constant Field Values

WHITESPACE_STRIPPING_KEY_SNAKE_CASE

public static final String WHITESPACE_STRIPPING_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

WHITESPACE_STRIPPING_KEY_CAMEL_CASE

public static final String WHITESPACE_STRIPPING_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

WHITESPACE_STRIPPING_KEY

public static final String WHITESPACE_STRIPPING_KEY

Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.

See Also:

Constant Field Values

OUTPUT_FORMAT_KEY_SNAKE_CASE

public static final String OUTPUT_FORMAT_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.24

See Also:

Constant Field Values

OUTPUT_FORMAT_KEY_CAMEL_CASE

public static final String OUTPUT_FORMAT_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.24

See Also:

Constant Field Values

OUTPUT_FORMAT_KEY

public static final String OUTPUT_FORMAT_KEY

Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.

See Also:

Constant Field Values

RECOGNIZE_STANDARD_FILE_EXTENSIONS_KEY_SNAKE_CASE

public static final String RECOGNIZE_STANDARD_FILE_EXTENSIONS_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.24

See Also:

Constant Field Values

RECOGNIZE_STANDARD_FILE_EXTENSIONS_KEY_CAMEL_CASE

public static final String RECOGNIZE_STANDARD_FILE_EXTENSIONS_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.24

See Also:

Constant Field Values

RECOGNIZE_STANDARD_FILE_EXTENSIONS_KEY

public static final String RECOGNIZE_STANDARD_FILE_EXTENSIONS_KEY

Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.

See Also:

Constant Field Values

REGISTERED_CUSTOM_OUTPUT_FORMATS_KEY_SNAKE_CASE

public static final String REGISTERED_CUSTOM_OUTPUT_FORMATS_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.24

See Also:

Constant Field Values

REGISTERED_CUSTOM_OUTPUT_FORMATS_KEY_CAMEL_CASE

public static final String REGISTERED_CUSTOM_OUTPUT_FORMATS_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.24

See Also:

Constant Field Values

REGISTERED_CUSTOM_OUTPUT_FORMATS_KEY

public static final String REGISTERED_CUSTOM_OUTPUT_FORMATS_KEY

Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.

See Also:

Constant Field Values

AUTO_ESCAPING_POLICY_KEY_SNAKE_CASE

public static final String AUTO_ESCAPING_POLICY_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.24

See Also:

Constant Field Values

AUTO_ESCAPING_POLICY_KEY_CAMEL_CASE

public static final String AUTO_ESCAPING_POLICY_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.24

See Also:

Constant Field Values

AUTO_ESCAPING_POLICY_KEY

public static final String AUTO_ESCAPING_POLICY_KEY

Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.

See Also:

Constant Field Values

CACHE_STORAGE_KEY_SNAKE_CASE

public static final String CACHE_STORAGE_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

CACHE_STORAGE_KEY_CAMEL_CASE

public static final String CACHE_STORAGE_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

CACHE_STORAGE_KEY

public static final String CACHE_STORAGE_KEY

Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.

See Also:

Constant Field Values

TEMPLATE_UPDATE_DELAY_KEY_SNAKE_CASE

public static final String TEMPLATE_UPDATE_DELAY_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

TEMPLATE_UPDATE_DELAY_KEY_CAMEL_CASE

public static final String TEMPLATE_UPDATE_DELAY_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

TEMPLATE_UPDATE_DELAY_KEY

public static final String TEMPLATE_UPDATE_DELAY_KEY

Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.

See Also:

Constant Field Values

AUTO_IMPORT_KEY_SNAKE_CASE

public static final String AUTO_IMPORT_KEY_SNAKE_CASE

Deprecated.

Use Configurable.AUTO_IMPORT_KEY_SNAKE_CASE instead.

Legacy, snake case (like_this) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

AUTO_IMPORT_KEY_CAMEL_CASE

public static final String AUTO_IMPORT_KEY_CAMEL_CASE

Deprecated.

Use Configurable.AUTO_IMPORT_KEY_CAMEL_CASE instead.

Modern, camel case (likeThis) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

AUTO_IMPORT_KEY

public static final String AUTO_IMPORT_KEY

Deprecated.

Use Configurable.AUTO_IMPORT_KEY_SNAKE_CASE instead.

Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.

See Also:

Constant Field Values

AUTO_INCLUDE_KEY_SNAKE_CASE

public static final String AUTO_INCLUDE_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

AUTO_INCLUDE_KEY_CAMEL_CASE

public static final String AUTO_INCLUDE_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

AUTO_INCLUDE_KEY

public static final String AUTO_INCLUDE_KEY

Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.

See Also:

Constant Field Values

TAG_SYNTAX_KEY_SNAKE_CASE

public static final String TAG_SYNTAX_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

TAG_SYNTAX_KEY_CAMEL_CASE

public static final String TAG_SYNTAX_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

TAG_SYNTAX_KEY

public static final String TAG_SYNTAX_KEY

Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.

See Also:

Constant Field Values

INTERPOLATION_SYNTAX_KEY_SNAKE_CASE

public static final String INTERPOLATION_SYNTAX_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.28

See Also:

Constant Field Values

INTERPOLATION_SYNTAX_KEY_CAMEL_CASE

public static final String INTERPOLATION_SYNTAX_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.28

See Also:

Constant Field Values

INTERPOLATION_SYNTAX_KEY

public static final String INTERPOLATION_SYNTAX_KEY

Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.

See Also:

Constant Field Values

NAMING_CONVENTION_KEY_SNAKE_CASE

public static final String NAMING_CONVENTION_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

NAMING_CONVENTION_KEY_CAMEL_CASE

public static final String NAMING_CONVENTION_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

NAMING_CONVENTION_KEY

public static final String NAMING_CONVENTION_KEY

Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.

See Also:

Constant Field Values

TAB_SIZE_KEY_SNAKE_CASE

public static final String TAB_SIZE_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.25

See Also:

Constant Field Values

TAB_SIZE_KEY_CAMEL_CASE

public static final String TAB_SIZE_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.25

See Also:

Constant Field Values

TAB_SIZE_KEY

public static final String TAB_SIZE_KEY

Alias to the ..._SNAKE_CASE variation. @since 2.3.25

See Also:

Constant Field Values

TEMPLATE_LOADER_KEY_SNAKE_CASE

public static final String TEMPLATE_LOADER_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

TEMPLATE_LOADER_KEY_CAMEL_CASE

public static final String TEMPLATE_LOADER_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

TEMPLATE_LOADER_KEY

public static final String TEMPLATE_LOADER_KEY

Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.

See Also:

Constant Field Values

TEMPLATE_LOOKUP_STRATEGY_KEY_SNAKE_CASE

public static final String TEMPLATE_LOOKUP_STRATEGY_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

TEMPLATE_LOOKUP_STRATEGY_KEY_CAMEL_CASE

public static final String TEMPLATE_LOOKUP_STRATEGY_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

TEMPLATE_LOOKUP_STRATEGY_KEY

public static final String TEMPLATE_LOOKUP_STRATEGY_KEY

Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.

See Also:

Constant Field Values

TEMPLATE_NAME_FORMAT_KEY_SNAKE_CASE

public static final String TEMPLATE_NAME_FORMAT_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

TEMPLATE_NAME_FORMAT_KEY_CAMEL_CASE

public static final String TEMPLATE_NAME_FORMAT_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

TEMPLATE_NAME_FORMAT_KEY

public static final String TEMPLATE_NAME_FORMAT_KEY

Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.

See Also:

Constant Field Values

TEMPLATE_CONFIGURATIONS_KEY_SNAKE_CASE

public static final String TEMPLATE_CONFIGURATIONS_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.24

See Also:

Constant Field Values

TEMPLATE_CONFIGURATIONS_KEY_CAMEL_CASE

public static final String TEMPLATE_CONFIGURATIONS_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.24

See Also:

Constant Field Values

TEMPLATE_CONFIGURATIONS_KEY

public static final String TEMPLATE_CONFIGURATIONS_KEY

Alias to the ..._SNAKE_CASE variation. @since 2.3.24

See Also:

Constant Field Values

INCOMPATIBLE_IMPROVEMENTS_KEY_SNAKE_CASE

public static final String INCOMPATIBLE_IMPROVEMENTS_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

INCOMPATIBLE_IMPROVEMENTS_KEY_CAMEL_CASE

public static final String INCOMPATIBLE_IMPROVEMENTS_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.23

See Also:

Constant Field Values

INCOMPATIBLE_IMPROVEMENTS_KEY

public static final String INCOMPATIBLE_IMPROVEMENTS_KEY

Alias to the ..._SNAKE_CASE variation due to backward compatibility constraints.

See Also:

Constant Field Values

INCOMPATIBLE_IMPROVEMENTS

@Deprecated
public static final String INCOMPATIBLE_IMPROVEMENTS

Deprecated.

Use INCOMPATIBLE_IMPROVEMENTS_KEY instead.

See Also:

Constant Field Values

INCOMPATIBLE_ENHANCEMENTS

@Deprecated
public static final String INCOMPATIBLE_ENHANCEMENTS

Deprecated.

Use INCOMPATIBLE_IMPROVEMENTS_KEY instead.

See Also:

Constant Field Values

FALLBACK_ON_NULL_LOOP_VARIABLE_KEY_SNAKE_CASE

public static final String FALLBACK_ON_NULL_LOOP_VARIABLE_KEY_SNAKE_CASE

Legacy, snake case (like_this) variation of the setting name. @since 2.3.29

See Also:

Constant Field Values

FALLBACK_ON_NULL_LOOP_VARIABLE_KEY_CAMEL_CASE

public static final String FALLBACK_ON_NULL_LOOP_VARIABLE_KEY_CAMEL_CASE

Modern, camel case (likeThis) variation of the setting name. @since 2.3.29

See Also:

Constant Field Values

FALLBACK_ON_NULL_LOOP_VARIABLE_KEY

public static final String FALLBACK_ON_NULL_LOOP_VARIABLE_KEY

Alias to the ..._SNAKE_CASE variation. @since 2.3.25

See Also:

Constant Field Values

AUTO_DETECT_TAG_SYNTAX

public static final int AUTO_DETECT_TAG_SYNTAX

The parser decides between ANGLE_BRACKET_TAG_SYNTAX and SQUARE_BRACKET_TAG_SYNTAX based on the first tag (like [#if x] or <#if x>) it mets. Note that [=...] is not a tag, but an interpolation, so it's not used for tag syntax auto-detection.

See Also:

Constant Field Values

ANGLE_BRACKET_TAG_SYNTAX

public static final int ANGLE_BRACKET_TAG_SYNTAX

For example <#if x><@foo /></#if>

See Also:

Constant Field Values

SQUARE_BRACKET_TAG_SYNTAX

public static final int SQUARE_BRACKET_TAG_SYNTAX

For example [#if x][@foo /][/#if]. It does not change ${x} to [=x]; that's square bracket interpolation syntax (SQUARE_BRACKET_INTERPOLATION_SYNTAX).

See Also:

Constant Field Values

LEGACY_INTERPOLATION_SYNTAX

public static final int LEGACY_INTERPOLATION_SYNTAX

${expression} and the deprecated #{expression; numFormat} @since 2.3.28

See Also:

Constant Field Values

DOLLAR_INTERPOLATION_SYNTAX

public static final int DOLLAR_INTERPOLATION_SYNTAX

${expression} only (not #{expression; numFormat}) @since 2.3.28

See Also:

Constant Field Values

SQUARE_BRACKET_INTERPOLATION_SYNTAX

public static final int SQUARE_BRACKET_INTERPOLATION_SYNTAX

[=expression] instead of ${expression}. It does not change <#if x> to [#if x]; that's square bracket tag syntax (SQUARE_BRACKET_TAG_SYNTAX).

Since:

2.3.28

See Also:

Constant Field Values

AUTO_DETECT_NAMING_CONVENTION

public static final int AUTO_DETECT_NAMING_CONVENTION

See Also:

Constant Field Values

LEGACY_NAMING_CONVENTION

public static final int LEGACY_NAMING_CONVENTION

See Also:

Constant Field Values

CAMEL_CASE_NAMING_CONVENTION

public static final int CAMEL_CASE_NAMING_CONVENTION

See Also:

Constant Field Values

DISABLE_AUTO_ESCAPING_POLICY

public static final int DISABLE_AUTO_ESCAPING_POLICY

Don't enable auto-escaping, regardless of what the OutputFormat is. Note that a <#ftl auto_esc=true> in the template will override this.

See Also:

Constant Field Values

ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY

public static final int ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY

Enable auto-escaping if the output format supports it and MarkupOutputFormat.isAutoEscapedByDefault() is true.

See Also:

Constant Field Values

ENABLE_IF_SUPPORTED_AUTO_ESCAPING_POLICY

public static final int ENABLE_IF_SUPPORTED_AUTO_ESCAPING_POLICY

Enable auto-escaping if the OutputFormat supports it.

See Also:

Constant Field Values

FORCE_AUTO_ESCAPING_POLICY

public static final int FORCE_AUTO_ESCAPING_POLICY

This policy is to always require auto-escaping, to avoid accidents where because of misconfiguration, or a mistake of the template author it's disabled. With this policy, using output formats that don't support escaping will not be allowed. Using built-ins, and directives that disable auto-escaping (like ?no_esc) will also be errors (on parse-time). Note that if markup (like HTML) comers from the data model, then with this policy you will have to ensure that they come as TemplateMarkupOutputModel-s (which won't be auto-escaped even with this policy), not as String-s, because the template authors can't disable escaping for the value anymore.

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)

VERSION_2_3_22

public static final Version VERSION_2_3_22

FreeMarker version 2.3.22 (an incompatible improvements break-point)

VERSION_2_3_23

public static final Version VERSION_2_3_23

FreeMarker version 2.3.23 (an incompatible improvements break-point)

VERSION_2_3_24

public static final Version VERSION_2_3_24

FreeMarker version 2.3.24 (an incompatible improvements break-point)

VERSION_2_3_25

public static final Version VERSION_2_3_25

FreeMarker version 2.3.25 (an incompatible improvements break-point)

VERSION_2_3_26

public static final Version VERSION_2_3_26

FreeMarker version 2.3.26 (an incompatible improvements break-point)

VERSION_2_3_27

public static final Version VERSION_2_3_27

FreeMarker version 2.3.27 (an incompatible improvements break-point)

VERSION_2_3_28

public static final Version VERSION_2_3_28

FreeMarker version 2.3.28 (an incompatible improvements break-point)

VERSION_2_3_29

public static final Version VERSION_2_3_29

FreeMarker version 2.3.29 (an incompatible improvements break-point)

VERSION_2_3_30

public static final Version VERSION_2_3_30

FreeMarker version 2.3.30 (an incompatible improvements break-point)

VERSION_2_3_31

public static final Version VERSION_2_3_31

FreeMarker version 2.3.31 (an incompatible improvements break-point)

VERSION_2_3_32

public static final Version VERSION_2_3_32

FreeMarker version 2.3.32 (an incompatible improvements break-point)

VERSION_2_3_33

public static final Version VERSION_2_3_33

FreeMarker version 2.3.33 (an incompatible improvements break-point)

DEFAULT_INCOMPATIBLE_IMPROVEMENTS

public static final Version DEFAULT_INCOMPATIBLE_IMPROVEMENTS

The default of getIncompatibleImprovements(), currently VERSION_2_3_0.

DEFAULT_INCOMPATIBLE_ENHANCEMENTS

@Deprecated
public static final String DEFAULT_INCOMPATIBLE_ENHANCEMENTS

Deprecated.

Use DEFAULT_INCOMPATIBLE_IMPROVEMENTS instead.

PARSED_DEFAULT_INCOMPATIBLE_ENHANCEMENTS

@Deprecated
public static final int PARSED_DEFAULT_INCOMPATIBLE_ENHANCEMENTS

Deprecated.

Use DEFAULT_INCOMPATIBLE_IMPROVEMENTS instead.

Constructor Details

Configuration

@Deprecated
public Configuration()

Deprecated.

Use Configuration(Version) instead. Note that the version can be still modified later with setIncompatibleImprovements(Version) (or Configurable.setSettings(Properties)).

Same as Configuration(Configuration.DEFAULT_INCOMPATIBLE_IMPROVEMENTS).

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

This setting value is the FreeMarker version number where the not 100% backward compatible bug fixes and improvements that you want to enable were already implemented. In new projects you should set this to the fixed FreeMarker version that you start the development with. In older projects it's also usually better to keep this high, however you should check the changes activated (find them below), especially if not only the 3rd version number (the micro version) of incompatibleImprovements is increased. Generally, as far as you only increase the last version number of this setting, the changes are low risk. The default value is 2.3.0 to maximize backward compatibility, but that value isn't recommended.

Bugfixes and improvements that are fully backward compatible, also those that are important security fixes, are enabled regardless of the incompatible improvements setting.

Do NOT ever use getVersion() to set the "incompatible improvements". Always use a fixed value, like VERSION_2_3_33. Otherwise, your application can break as you upgrade FreeMarker. (As of 2.3.30, doing this will be logged as an error. As of 2.4.0, it will be probably disallowed, by throwing exception.)

An important consequence of setting this setting is that now your application will check if the stated minimum FreeMarker version requirement is met. Like if you set this setting to 2.3.22, but accidentally the application is deployed with FreeMarker 2.3.21, then FreeMarker will fail, telling that a higher version is required. After all, the fixes/improvements you have requested aren't available on a lower version.

Note that as FreeMarker's 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 won't bring back the old behavior anymore. Information about that will be present here.

Note that DefaultObjectWrapper (and BeansWrapper, which it extends) has its own "incompatible improvements" setting (see DefaultObjectWrapper(Version)), but if you leave the object_wrapper setting at its default (and most do), then that will be kept the same as of the Configuration.

Currently the effects of this setting are:

• 2.3.0: This is the lowest supported value, the version used in very old projects. This is the default in the FreeMarker 2.3.x series (the one used by the deprecated Configuration() constructor) for maximum backward compatibility.

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

• 2.3.22 (or higher):

  • DefaultObjectWrapper has some substantial changes with incompatibleImprovements 2.3.22; check them out at DefaultObjectWrapper(Version). It's important to know that if you set the object_wrapper setting (to an other value than "default"), rather than leaving it on its default value, the object_wrapper won't inherit the incompatibleImprovements of the Configuration. In that case, if you want the 2.3.22 improvements of DefaultObjectWrapper, you have to set it in the DefaultObjectWrapper object itself too! (Note that it's OK to use a DefaultObjectWrapper with a different incompatibleImprovements version number than that of the Configuration, if that's really what you want.)

  • In templates, .template_name will always return the main (top level) template's name. It won't be affected by #include and #nested anymore. This is unintended, a bug with incompatible_improvement 2.3.22 (a consequence of the lower level fixing described in the next point). The old behavior of .template_name is restored if you set incompatible_improvement to 2.3.23 (while Configurable.getParent() of Environment keeps the changed behavior shown in the next point).

  • #include and #nested doesn't change the parent Template (see Configurable.getParent()) of the Environment anymore to the Template that's included or whose namespace #nested "returns" to. Thus, the parent of Environment will be now always the main Template. (The main Template is the Template whose process or createProcessingEnvironment method was called to initiate the output generation.) Note that apart from the effect on FTL's .template_name (see previous point), this should only matter if you have set settings directly on Template objects, and almost nobody does that. Also note that macro calls have never changed the Environment parent to the Template that contains the macro definition, so this mechanism was always broken. As now we consistently never change the parent, the behavior when calling macros didn't change.

  • When using freemarker.ext.servlet.FreemarkerServlet:

    • When using custom JSP tag libraries: Fixes bug where some kind of values, when put into the JSP page scope (via #global or via the JSP PageContext API) and later read back with the JSP PageContext API (typically in a custom JSP tag), might come back as FreeMarker TemplateModel objects instead of as objects with a standard Java type. Other Servlet scopes aren't affected. It's highly unlikely that something expects the presence of this bug. The affected values are of the FTL types listed below, and to trigger the bug, they either had to be created directly in the template (like as an FTL literal or with ?date/time/datetime), or you had to use DefaultObjectWrapper or SimpleObjectWrapper (or a subclass of them):

      • FTL date/time/date-time values may came back as SimpleDate-s, now they come back as java.util.Date-s instead.
      • FTL sequence values may came back as SimpleSequence-s, now they come back as List-s as expected. This at least stands assuming that the object_wrapper configuration setting is a subclass of BeansWrapper (such as DefaultObjectWrapper, which is the default), but that's practically always the case in applications that use FreeMarker's JSP extension (otherwise it can still work, but it depends on the quality and capabilities of the ObjectWrapper implementation).
      • FTL hash values may came back as SimpleHash-es, now they come back as Map-s as expected (again, assuming that the object wrapper is a subclass of BeansWrapper, like preferably DefaultObjectWrapper, which is also the default).
      • FTL collection values may came back as SimpleCollection-s, now they come back as Collection-s as expected (again, assuming that the object wrapper is a subclass of BeansWrapper, like preferably DefaultObjectWrapper).

    • Initial "[" in the TemplatePath init-param has special meaning; it's used for specifying multiple comma separated locations, like in <param-value>[ WEB-INF/templates, classpath:com/example/myapp/templates ]</param-value>

    • Initial "{" in the TemplatePath init-param is reserved for future purposes, and thus will throw exception.

• 2.3.23 (or higher):

  • Fixed a loophole in the implementation of the long existing parse-time rule that says that #break, in the FTL source code itself, must occur nested inside a breakable directive, such as #list or #switch. This check could be circumvented with #macro or #function, like this: <#list 1..1 as x><#macro callMeLater><#break></#macro></#list><@callMeLater />. After activating this fix, this will be a parse time error.

  • If you have used incompatible_improvements 2.3.22 earlier, know that there the behavior of the .template_name special variable used in templates was accidentally altered, but now it's restored to be backward compatible with 2.3.0. (Ironically, the restored legacy behavior itself is broken when it comes to macro invocations, we just keep it for backward compatibility. If you need fixed behavior, use .current_template_name or .main_template_name instead.)

• 2.3.24 (or higher):

  • The default of the recognize_standard_file_extensions setting changes to true, which means that templates whose name ends with ".ftlh" or ".ftlx" will automatically get HTMLOutputFormat.INSTANCE or XMLOutputFormat.INSTANCE output format respectively, in both cases with ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY auto_escaping_policy. These "file" extensions aren't case sensitive.

  • In number format and date format strings (like in the number_format setting, or in templates in n?string("0.##")), an initial '@' has special meaning; they refer to a custom format with the name given after the @ (see: Configurable.setCustomNumberFormats(Map), Configurable.setCustomDateFormats(Map), Configurable.setNumberFormat(String), and Configurable.setDateTimeFormat(java.lang.String)). If the custom format doesn't exist, that will be an error. To have a literal @ as the first character in the output, it has to be written as @@. Again, all this only applies to the very first character of the format string, so @ characters elsewhere must not be doubled. Also, if there are any custom formats defined, initial '@' will have the new meaning regardless of the value of the incompatible_improvements setting. So you don't need to set the incompatible_improvements only to use custom formats.

  • Expressions inside interpolations that were inside string literal expressions (not ${...}-s in general), like in <#assign s="Hello ${name}!">, has always used incompatbileImprovement-s 0 (2.3.0 in effect). Now it's fixed.

  • DefaultObjectWrapper has some minor changes with incompatibleImprovements 2.3.24; check them out at DefaultObjectWrapper(Version). It's important to know that if you set the object_wrapper setting (to an other value than "default"), rather than leaving it on its default value, the object_wrapper won't inherit the incompatibleImprovements of the Configuration. In that case, if you want the 2.3.24 improvements of DefaultObjectWrapper, you have to set it in the DefaultObjectWrapper object itself too! (Note that it's OK to use a DefaultObjectWrapper with a different incompatibleImprovements version number than that of the Configuration, if that's really what you want.)

  • Fixed bug: The #import directive meant to copy the library variable into a global variable if it's executed in the main namespace, but that haven't happened when the imported template was already imported earlier in another namespace.

  • ?is_sequence doesn't return true for Java methods wrapped by BeansWrapper and its subclasses (most notably DefaultObjectWrapper) anymore, as they only implement the [index] operator, but not ?size, which causes <#list ...> to fail among others. (They shouldn't implement either, but this is historical heritage.)

• 2.3.25 (or higher):

  • When calling Configurable.setAutoIncludes(List) on a Configuration, it filters out duplicates from the list, similarly as repeatedly calling Configurable.addAutoInclude(String) would, hence avoiding repeated inclusions. Calling Configurable.setAutoIncludes(List) on other Configurable-s always do this filtering regardless of the incompatible improvements setting.

• 2.3.26 (or higher):

  • The default object_wrapper now exposes Java 8 default methods (and the bean properties they define); see BeansWrapper(Version).

• 2.3.27 (or higher):

  • The default object_wrapper now prefers the non-indexed JavaBean property read method over the indexed read method when Java 8 exposes both; see BeansWrapper(Version).

  • The following unchecked exceptions (but not their subclasses) will be wrapped into TemplateException-s when thrown during evaluating expressions or calling directives: NullPointerException, ClassCastException, IndexOutOfBoundsException, and InvocationTargetException. The goal of this is the same as of setting wrap_unchecked_exceptions to true (see more there), but this is more backward compatible, as it avoids wrapping unchecked exceptions that the calling application is likely to catch specifically (like application-specific unchecked exceptions).

  • When the Writer returned by TemplateTransformModel.getWriter(Writer, Map) implements TransformControl, exceptions that are used internally by FreeMarker for flow control (for <#return>, <#break>, etc.) won't be passed to TransformControl.onError(Throwable) anymore. Earlier, if onError didn't rethrow the exception (though almost all implementation does), you couldn't use said directives inside the transformed block. It's very unlikely that user code is affected by this, partially because these aren't commonly implemented interfaces (especially not TransformControl), and because it's unlikely that templates utilize the the bug that's not fixed.

• 2.3.28 (or higher):

  • When calling a macro or function (things defined in a template, not directly in Java) and the argument list contains .current_template_name, now it will correctly evaluate to the template that contains the call, rather than to the template that contains the macro or function definition. (Of course, the parameter default value expression is still evaluated in the context of the called macro or function.) Similarly, .macro_caller_template_name (which itself was added in 2.3.28), when used in a macro call argument, won't be incorrectly evaluated in the context of the called macro.

  • Fixed legacy parser glitch where a tag can be closed with an illegal ] (when it's not part of an expression) despite that the tag syntax is set to angle brackets. For example <#if x] worked just like <#if x>. Note that it doesn't affect the legal usage of ], like <#if x[0]> works correctly without this fix as well.

• 2.3.31 (or higher):

  • When you set the number_format setting to "computer" (or you call Environment.getCNumberFormat()), the format now matches the behavior of ?c, when formatting infinite (positive and negative), and NaN. Matching the behavior of ?c was always the intent, but before this incompatible improvement, the "computer" format always behaved like ?c before Incompatible Improvements 2.3.21, where instead of INF, and NaN, the results used unicode characters U+221E, and U+FFFD.

• 2.3.32 (or higher):

  • The number formatting of ?c, ?cn (and thus also of the "c", and "computer" number_format) changes, if the c_format setting was left on its default. The default of c_format changes to JavaScriptOrJSONCFormat.INSTANCE, from LegacyCFormat.INSTANCE, and that's what contains the changes:

    • Changes affecting non-whole numbers, and whole numbers with over 100 digits: Formatting is now lossless, so it potentially shows much more decimals. It now uses exponential format (like 1.2E-7 instead of 0.00000012) for numbers whose absolute value is less than 1E-6 (0.000001), and for whole numbers whose absolute value is at least 1E101 (so over 100 digits). It also uses exponential format for whole floating point (double/Double}, or float/Float) numbers, when their absolute value is too big for the floating point type to store them precisely (so if the intent was to store some ID-s, they are likely corrupted anyway, as the type skips some whole numbers).

    • Changes affecting floating point infinity: Output changes from INF to Infinity, which is the JavaScript and JSON syntax. If you generate XML with XSD-style number syntax (which uses INF), but you want the other number formatting changes (recommended), then set c_format to XSCFormat.INSTANCE/"XS".

• 2.3.33 (or higher):

  • Comparing strings is now way faster. If your template does lot of string comparisons, this can mean very significant speedup. We now use a simpler way of comparing strings, and because templates were only ever allowed equality comparisons between strings (not less-than, or greater-than), it's very unlikely to change the behavior of your templates. (Technically, what changes is that instead of using Java's localized Collator-s, we switch to a simple binary comparison after UNICODE NFKC normalization. So, in theory it's possible that for some locales two different but similarly looking characters were treated as equal by the collator, but will count as different now. But it's very unlikely that anyone wanted to depend on such fragile logic anyway. Note again that we still do UNICODE normalization, so combining characters won't break your comparisons.)

  • The default object_wrapper now exposes Java records public methods with 0-arguments and non-void return type are now exposed both as properties, and as methods; see BeansWrapper(Version).

Throws:

IllegalArgumentException - If incompatibleImmprovements refers to a version that wasn't released yet when the currently used FreeMarker version was released, or is less than 2.3.0, or is null.

Since:

2.3.21

Method Details

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:

Preset language to encoding mapping

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

@Deprecated
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

@Deprecated
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 (unless the new and the old values are the same). 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), setClassLoaderForTemplateLoading(ClassLoader, 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.)

unsetTemplateLoader

public void unsetTemplateLoader()

Resets the setting to its default, as if it was never set. This means that when you change the incompatibe_improvements setting later, the default will also change as appropriate. Also isTemplateLoaderExplicitlySet() will return false.

Since:

2.3.22

isTemplateLoaderExplicitlySet

public boolean isTemplateLoaderExplicitlySet()

Tells if setTemplateLoader(TemplateLoader) (or equivalent) was already called on this instance.

Since:

2.3.22

getTemplateLoader

public TemplateLoader getTemplateLoader()

The getter pair of setTemplateLoader(TemplateLoader).

setTemplateLookupStrategy

public void setTemplateLookupStrategy(TemplateLookupStrategy templateLookupStrategy)

Sets the TemplateLookupStrategy that is used to look up templates based on the requested name; as a side effect the template cache will be emptied. The default value is TemplateLookupStrategy.DEFAULT_2_3_0.

Since:

2.3.22

unsetTemplateLookupStrategy

public void unsetTemplateLookupStrategy()

Resets the setting to its default, as if it was never set. This means that when you change the incompatibe_improvements setting later, the default will also change as appropriate. Also isTemplateLookupStrategyExplicitlySet() will return false.

Since:

2.3.22

isTemplateLookupStrategyExplicitlySet

public boolean isTemplateLookupStrategyExplicitlySet()

Tells if setTemplateLookupStrategy(TemplateLookupStrategy) (or equivalent) was already called on this instance.

Since:

2.3.22

getTemplateLookupStrategy

public TemplateLookupStrategy getTemplateLookupStrategy()

The getter pair of setTemplateLookupStrategy(TemplateLookupStrategy).

setTemplateNameFormat

public void setTemplateNameFormat(TemplateNameFormat templateNameFormat)

Sets the template name format used. The default is TemplateNameFormat.DEFAULT_2_3_0, while the recommended value for new projects is TemplateNameFormat.DEFAULT_2_4_0.

Since:

2.3.22

unsetTemplateNameFormat

public void unsetTemplateNameFormat()

Resets the setting to its default, as if it was never set. This means that when you change the incompatibe_improvements setting later, the default will also change as appropriate. Also isTemplateNameFormatExplicitlySet() will return false.

Since:

2.3.22

isTemplateNameFormatExplicitlySet

public boolean isTemplateNameFormatExplicitlySet()

Tells if setTemplateNameFormat(TemplateNameFormat) (or equivalent) was already called on this instance.

Since:

2.3.22

getTemplateNameFormat

public TemplateNameFormat getTemplateNameFormat()

The getter pair of setTemplateNameFormat(TemplateNameFormat).

setTemplateConfigurations

public void setTemplateConfigurations(TemplateConfigurationFactory templateConfigurations)

Sets a TemplateConfigurationFactory that will configure individual templates where their settings differ from those coming from the common Configuration object. A typical use case for that is specifying the outputFormat for templates based on their file extension or parent directory.

Note that the settings suggested by standard file extensions are stronger than that you set here. See setRecognizeStandardFileExtensions(boolean) for more information about standard file extensions.

See "Template configurations" in the FreeMarker Manual for examples.

Since:

2.3.24

getTemplateConfigurations

public TemplateConfigurationFactory getTemplateConfigurations()

The getter pair of setTemplateConfigurations(TemplateConfigurationFactory).

setCacheStorage

public void setCacheStorage(CacheStorage cacheStorage)

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.

unsetCacheStorage

public void unsetCacheStorage()

Resets the setting to its default, as if it was never set. This means that when you change the incompatibe_improvements setting later, the default will also change as appropriate. Also isCacheStorageExplicitlySet() will return false.

Since:

2.3.22

isCacheStorageExplicitlySet

public boolean isCacheStorageExplicitlySet()

Tells if setCacheStorage(CacheStorage) (or equivalent) was already called on this instance.

Since:

2.3.22

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(File) for more details.

Note that FreeMarker can load templates from non-file-system sources too. See setTemplateLoader(TemplateLoader) from more details.

Note that this shouldn't be used for loading templates that are coming from a WAR; use setServletContextForTemplateLoading(Object, String) then. Servlet containers might not unpack the WAR file, in which case you clearly can't access the contained files via File. Even if the WAR is unpacked, the servlet container might not expose the location as a File. setServletContextForTemplateLoading(Object, String) on the other hand will work in all these cases.

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 freemarker.cache.WebappTemplateLoader for more details.

Parameters:

servletContext - the javax.servlet.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.) Can't be null.

path - the path relative to the ServletContext; maybe null.

See Also:

setTemplateLoader(TemplateLoader)

setClassForTemplateLoading

public void setClassForTemplateLoading(Class resourceLoaderClass,
 String basePackagePath)

Sets the class whose Class.getResource(String) method will be used to load templates, from the inside the package specified. See ClassTemplateLoader(Class, String) for more details.

Parameters:

basePackagePath - Separate steps with "/", not ".", and note that it matters if this starts with / or not. See ClassTemplateLoader(Class, String) for more details.

See Also:

setClassLoaderForTemplateLoading(ClassLoader, String), setTemplateLoader(TemplateLoader)

setClassLoaderForTemplateLoading

public void setClassLoaderForTemplateLoading(ClassLoader classLoader,
 String basePackagePath)

Sets the ClassLoader whose ClassLoader.getResource(String) method will be used to load templates, from the inside the package specified. See ClassTemplateLoader(Class, String) for more details.

Parameters:

basePackagePath - Separate steps with "/", not ".". See ClassTemplateLoader(Class, String) for more details.

Since:

2.3.22

See Also:

setClassForTemplateLoading(Class, String), setTemplateLoader(TemplateLoader)

setTemplateUpdateDelay

@Deprecated
public void setTemplateUpdateDelay(int seconds)

Deprecated.

Use setTemplateUpdateDelayMilliseconds(long) instead, because the time granularity of this method is often misunderstood to be milliseconds.

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.

setTemplateUpdateDelayMilliseconds

public void setTemplateUpdateDelayMilliseconds(long millis)

Sets the time in milliseconds that must elapse before checking whether there is a newer version of a template "file" than the cached one. Defaults to 5000 ms.

When you get a template via getTemplate(String) (or some of its overloads). FreeMarker will try to get the template from the template cache. If the template is found, and at least this amount of time was elapsed since the template last modification date was checked, FreeMarker will re-check the last modification date (this could mean I/O), possibly reloading the template and updating the cache as a consequence (can mean even more I/O). The getTemplate(String) (or some of its overloads) call will only return after this all is done, so it will return the fresh template.

Since:

2.3.23

getTemplateUpdateDelayMilliseconds

public long getTemplateUpdateDelayMilliseconds()

The getter pair of setTemplateUpdateDelayMilliseconds(long).

Since:

2.3.23

setStrictSyntaxMode

@Deprecated
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 ObjectWrapper used to wrap objects to TemplateModel-s when using this Configurable.

On Configuration level, the default is a DefaultObjectWrapper instance with the same incompatible_improvements setting value as of the Configuration. (Also, with very low incompatible improvements it's ObjectWrapper.DEFAULT_WRAPPER.). Untill you called this method, the default value will be automatically replaced when setIncompatibleImprovements(Version) is called, to follow the value of the incompatible_improvements setting.

Below Configuration level it's usually unset, so we fall back to what's coming from Configuration.

Overrides:

setObjectWrapper in class Configurable

Parameters:

objectWrapper - Not null.

unsetObjectWrapper

public void unsetObjectWrapper()

Resets the setting to its default, as if it was never set. This means that when you change the incompatibe_improvements setting later, the default will also change as appropriate. Also isObjectWrapperExplicitlySet() will return false.

Since:

2.3.22

isObjectWrapperExplicitlySet

public boolean isObjectWrapperExplicitlySet()

Tells if setObjectWrapper(ObjectWrapper) (or equivalent) was already called on this instance.

Since:

2.3.22

setLocale

public void setLocale(Locale locale)

Description copied from class: Configurable

Sets the locale used for number and date formatting (among others), also the locale used for searching localized template variations when no locale was explicitly requested. On the Configuration level it defaults to the default locale of system (of the JVM), for server-side application usually you should set it explicitly in the Configuration to use the preferred locale of your application instead.

Overrides:

setLocale in class Configurable

See Also:

getTemplate(String, Locale)

unsetLocale

public void unsetLocale()

Resets the setting to its default, as if it was never set.

Since:

2.3.26

isLocaleExplicitlySet

public boolean isLocaleExplicitlySet()

Tells if setLocale(Locale) (or equivalent) was already called on this instance, or it just holds the default value.

Since:

2.3.26

setTimeZone

public void setTimeZone(TimeZone timeZone)

Description copied from class: Configurable

Sets the time zone to use when formatting date/time values. Defaults to the system time zone (TimeZone.getDefault()), regardless of the "locale" FreeMarker setting, so in a server application you probably want to set it explicitly in the Environment to match the preferred time zone of target audience (like the Web page visitor).

If you or the templates set the time zone, you should probably also set Configurable.setSQLDateAndTimeTimeZone(TimeZone)!

Overrides:

setTimeZone in class Configurable

See Also:

Configurable.setSQLDateAndTimeTimeZone(TimeZone)

unsetTimeZone

public void unsetTimeZone()

Resets the setting to its default, as if it was never set.

Since:

2.3.26

isTimeZoneExplicitlySet

public boolean isTimeZoneExplicitlySet()

Tells if setTimeZone(TimeZone) (or equivalent) was already called on this instance, or it just holds the default value.

Since:

2.3.26

setTemplateExceptionHandler

public void setTemplateExceptionHandler(TemplateExceptionHandler templateExceptionHandler)

Description copied from class: Configurable

Sets the exception handler used to handle exceptions occurring inside templates. The default is TemplateExceptionHandler.DEBUG_HANDLER. The recommended values are:

• In production systems: TemplateExceptionHandler.RETHROW_HANDLER
• During development of HTML templates: TemplateExceptionHandler.HTML_DEBUG_HANDLER
• During development of non-HTML templates: TemplateExceptionHandler.DEBUG_HANDLER

All of these will let the exception propagate further, so that you can catch it around Template.process(Object, Writer) for example. The difference is in what they print on the output before they do that.

Note that the TemplateExceptionHandler is not meant to be used for generating HTTP error pages. Neither is it meant to be used to roll back the printed output. These should be solved outside template processing when the exception raises from Template.process. TemplateExceptionHandler meant to be used if you want to include special content in the template output, or if you want to suppress certain exceptions. If you suppress an exception, and the Configurable.getLogTemplateExceptions() returns false, then it's the responsibility of the TemplateExceptionHandler to log the exception (if you want it to be logged).

Overrides:

setTemplateExceptionHandler in class Configurable

See Also:

Configurable.setLogTemplateExceptions(boolean), Configurable.setAttemptExceptionReporter(AttemptExceptionReporter)

unsetTemplateExceptionHandler

public void unsetTemplateExceptionHandler()

Resets the setting to its default, as if it was never set. This means that when you change the incompatibe_improvements setting later, the default will also change as appropriate. Also isTemplateExceptionHandlerExplicitlySet() will return false.

Since:

2.3.22

isTemplateExceptionHandlerExplicitlySet

public boolean isTemplateExceptionHandlerExplicitlySet()

Tells if setTemplateExceptionHandler(TemplateExceptionHandler) (or equivalent) was already called on this instance.

Since:

2.3.22

setAttemptExceptionReporter

public void setAttemptExceptionReporter(AttemptExceptionReporter attemptExceptionReporter)

Description copied from class: Configurable

Specifies how exceptions handled (and hence suppressed) by an #attempt blocks will be logged or otherwise reported. The default value is AttemptExceptionReporter.LOG_ERROR_REPORTER.

Note that #attempt is not supposed to be a general purpose error handler mechanism, like try is in Java. It's for decreasing the impact of unexpected errors, by making it possible that only part of the page is going down, instead of the whole page. But it's still an error, something that someone should fix. So the error should be reported, not just ignored in a custom AttemptExceptionReporter-s.

The AttemptExceptionReporter is invoked regardless of the value of the log_template_exceptions setting. The AttemptExceptionReporter is not invoked if the TemplateExceptionHandler has suppressed the exception.

Overrides:

setAttemptExceptionReporter in class Configurable

unsetAttemptExceptionReporter

public void unsetAttemptExceptionReporter()

Resets the setting to its default, as if it was never set. This means that when you change the incompatibe_improvements setting later, the default will also change as appropriate. Also isAttemptExceptionReporterExplicitlySet() will return false.

Since:

2.3.27

isAttemptExceptionReporterExplicitlySet

public boolean isAttemptExceptionReporterExplicitlySet()

Tells if setAttemptExceptionReporter(AttemptExceptionReporter) (or equivalent) was already called on this instance.

Since:

2.3.27

setLogTemplateExceptions

public void setLogTemplateExceptions(boolean value)

Specifies if TemplateException-s thrown by template processing are logged by FreeMarker or not. The default is true for backward compatibility, but that results in logging the exception twice in properly written applications, because there the TemplateException thrown by the public FreeMarker API is also logged by the caller (even if only as the cause exception of a higher level exception). Hence, in modern applications it should be set to false. Note that this setting has no effect on the logging of exceptions caught by #attempt; by default those are always logged as errors (because those exceptions won't bubble up to the API caller), however, that can be changed with the attempt_exception_reporter setting.

Overrides:

setLogTemplateExceptions in class Configurable

Since:

2.3.22

unsetLogTemplateExceptions

public void unsetLogTemplateExceptions()

Resets the setting to its default, as if it was never set. This means that when you change the incompatibe_improvements setting later, the default will also change as appropriate. Also isTemplateExceptionHandlerExplicitlySet() will return false.

Since:

2.3.22

isLogTemplateExceptionsExplicitlySet

public boolean isLogTemplateExceptionsExplicitlySet()

Tells if setLogTemplateExceptions(boolean) (or equivalent) was already called on this instance.

Since:

2.3.22

setWrapUncheckedExceptions

public void setWrapUncheckedExceptions(boolean value)

Specifies if unchecked exceptions thrown during expression evaluation or during executing custom directives (and transform) will be wrapped into TemplateException-s, or will bubble up to the caller of Template.process(Object, Writer, ObjectWrapper) as is. The default is false for backward compatibility (as some applications catch certain unchecked exceptions thrown by the template processing to do something special), but the recommended value is true. When this is true, the unchecked exceptions will be wrapped into a TemplateException-s, thus the exception will include the location in the template (not just the Java stack trace). Another consequence of the wrapping is that the TemplateExceptionHandler will be invoked for the exception (as that only handles TemplateException-s, it wasn't invoked for unchecked exceptions). When this setting is false, unchecked exception will be thrown by Template.process(Object, Writer, ObjectWrapper). Note that plain Java methods called from templates aren't user defined TemplateMethodModel-s, and have always wrapped the thrown exception into TemplateException, regardless of this setting.

Overrides:

setWrapUncheckedExceptions in class Configurable

Since:

2.3.27

unsetWrapUncheckedExceptions

public void unsetWrapUncheckedExceptions()

Since:

2.3.27

isWrapUncheckedExceptionsExplicitlySet

public boolean isWrapUncheckedExceptionsExplicitlySet()

Tells if setWrapUncheckedExceptions(boolean) (or equivalent) was already called on this instance.

Since:

2.3.27

getStrictSyntaxMode

public boolean getStrictSyntaxMode()

The getter pair of setStrictSyntaxMode(boolean).

Specified by:

getStrictSyntaxMode in interface ParserConfiguration

setIncompatibleImprovements

public void setIncompatibleImprovements(Version incompatibleImprovements)

Use Configuration(Version) instead if possible; see the meaning of the parameter there.

Do NOT ever use getVersion() to set the "incompatible improvements"! Always use a fixed value, like VERSION_2_3_30. Otherwise, your application can break as you upgrade FreeMarker. (As of 2.3.30, doing this will be logged as an error. As of 2.4.0, it will be probably disallowed, by throwing exception.)

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 refers to a version that wasn't released yet when the currently used FreeMarker version was released, or is less than 2.3.0, or is null.

Since:

2.3.20

getIncompatibleImprovements

public Version getIncompatibleImprovements()

Description copied from interface: ParserConfiguration

See getIncompatibleImprovements().

Specified by:

getIncompatibleImprovements in interface ParserConfiguration

Returns:

Never null.

Since:

2.3.20

See Also:

setIncompatibleImprovements(Version)

setIncompatibleEnhancements

@Deprecated
public void setIncompatibleEnhancements(String version)

Deprecated.

Use Configuration(Version), or as last chance, setIncompatibleImprovements(Version) instead.

getIncompatibleEnhancements

@Deprecated
public String getIncompatibleEnhancements()

Deprecated.

Use getIncompatibleImprovements() instead.

getParsedIncompatibleEnhancements

@Deprecated
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.

Specified by:

getWhitespaceStripping in interface ParserConfiguration

See Also:

setWhitespaceStripping(boolean)

setAutoEscapingPolicy

public void setAutoEscapingPolicy(int autoEscapingPolicy)

Sets when auto-escaping should be enabled depending on the current output format; default is ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY.

Note that the default output format, UndefinedOutputFormat, is a non-escaping format, so there auto-escaping will be off.

Note that the templates can turn auto-escaping on/off locally with directives like <#ftl auto_esc=...>, <#autoesc>...</#autoesc>, and <#noautoesc>...</#noautoesc>, which are ignoring the auto-escaping policy.

About auto-escaping

Auto-escaping has significance when a value is printed with ${...} (or #{...}). If auto-escaping is on, FreeMarker will assume that the value is plain text (as opposed to markup or some kind of rich text), so it will escape it according the current output format (see setOutputFormat(OutputFormat) and TemplateConfiguration.setOutputFormat(OutputFormat)). If auto-escaping is off, FreeMarker will assume that the string value is already in the output format, so it prints it as is to the output.

Further notes on auto-escaping:

• When printing numbers, dates, and other kind of non-string values with ${...}, they will be first converted to string (according the formatting settings and locale), then they are escaped just like string values.
• When printing TemplateMarkupOutputModel-s, they aren't escaped again (they are already escaped).
• Auto-escaping doesn't do anything if the current output format isn't an MarkupOutputFormat. That's the case for the default output format, UndefinedOutputFormat, and also for PlainTextOutputFormat.
• The output format inside a string literal expression is always PlainTextOutputFormat (regardless of the output format of the containing template), which is a non-escaping format. Thus for example, with <#assign s = "foo${bar}">, bar will always get into s without escaping, but with <#assign s>foo${bar}<#assign> it may will be escaped.

Note that what you set here is just a default, which can be overridden for individual templates via setTemplateConfigurations(TemplateConfigurationFactory). This setting is also overridden by the standard file extensions; see them at setRecognizeStandardFileExtensions(boolean).

Parameters:

autoEscapingPolicy - One of the ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY, ENABLE_IF_SUPPORTED_AUTO_ESCAPING_POLICY, DISABLE_AUTO_ESCAPING_POLICY, and FORCE_AUTO_ESCAPING_POLICY constants.

Since:

2.3.24

See Also:

TemplateConfiguration.setAutoEscapingPolicy(int), setOutputFormat(OutputFormat), TemplateConfiguration.setOutputFormat(OutputFormat)

getAutoEscapingPolicy

public int getAutoEscapingPolicy()

Getter pair of setAutoEscapingPolicy(int)

Specified by:

getAutoEscapingPolicy in interface ParserConfiguration

Since:

2.3.24

setOutputFormat

public void setOutputFormat(OutputFormat outputFormat)

Sets the default output format. Usually, you should leave this on its default, which is UndefinedOutputFormat.INSTANCE, and then use standard file extensions like "ftlh" (for HTML) or "ftlx" (for XML) and ensure that setRecognizeStandardFileExtensions(boolean) is true (see more there). Where you can't use the standard extensions, templates still can be associated to output formats with patterns matching their name (their path) using setTemplateConfigurations(TemplateConfigurationFactory). But if all templates will have the same output format, you may use setOutputFormat(OutputFormat) after all, to a value like HTMLOutputFormat.INSTANCE, XMLOutputFormat.INSTANCE, etc. Also note that templates can specify their own output format like <#ftl output_format="HTML">, which overrides any configuration settings.

The output format is mostly important because of auto-escaping (see setAutoEscapingPolicy(int)), but maybe also used by the embedding application to set the HTTP response MIME type, etc.

Parameters:

outputFormat - Not null; use UndefinedOutputFormat.INSTANCE instead.

Since:

2.3.24

See Also:

setRegisteredCustomOutputFormats(Collection), setTemplateConfigurations(TemplateConfigurationFactory), setRecognizeStandardFileExtensions(boolean), setAutoEscapingPolicy(int)

getOutputFormat

public OutputFormat getOutputFormat()

Getter pair of setOutputFormat(OutputFormat)

Specified by:

getOutputFormat in interface ParserConfiguration

Since:

2.3.24

isOutputFormatExplicitlySet

public boolean isOutputFormatExplicitlySet()

Tells if setOutputFormat(OutputFormat) (or equivalent) was already called on this instance.

Since:

2.3.24

unsetOutputFormat

public void unsetOutputFormat()

Resets the setting to its default, as if it was never set. This means that when you change the incompatibe_improvements setting later, the default will also change as appropriate. Also isOutputFormatExplicitlySet() will return false.

Since:

2.3.24

getOutputFormat

public OutputFormat getOutputFormat(String name)
                             throws UnregisteredOutputFormatException

Returns the output format for a name.

Parameters:

name - Either the name of the output format as it was registered with setRegisteredCustomOutputFormats(Collection), or a combined output format name. A combined output format is created ad-hoc from the registered formats. For example, if you need RTF embedded into HTML, the name will be HTML{RTF}, where "HTML" and "RTF" refer to the existing formats. This logic can be used recursively, so for example XML{HTML{RTF}} is also valid.

Returns:

Not null.

Throws:

UnregisteredOutputFormatException - If there's no output format registered with the given name.

IllegalArgumentException - If the usage of { and } in the name is syntactically wrong, or if not all OutputFormat-s are MarkupOutputFormat-s in the ...{...} expression.

Since:

2.3.24

setRegisteredCustomOutputFormats

public void setRegisteredCustomOutputFormats(Collection<? extends OutputFormat> registeredCustomOutputFormats)

Sets the custom output formats that can be referred by their unique name (OutputFormat.getName()) from templates. Names are also used to look up the OutputFormat for standard file extensions; see them at setRecognizeStandardFileExtensions(boolean).

When there's a clash between a custom output format name and a standard output format name, the custom format will win, thus you can override the meaning of standard output format names. Except, it's not allowed to override UndefinedOutputFormat and PlainTextOutputFormat.

The default value is an empty collection.

Parameters:

registeredCustomOutputFormats - The collection of the OutputFormat-s, each must be different and has a unique name ( OutputFormat.getName()) within this collection.

Throws:

IllegalArgumentException - When multiple different OutputFormat-s have the same name in the parameter collection. When the same OutputFormat object occurs for multiple times in the collection. If an OutputFormat name is 0 long. If an OutputFormat name doesn't start with letter or digit. If an OutputFormat name contains '+' or '{' or '}'. If an OutputFormat name equals to UndefinedOutputFormat.getName() or PlainTextOutputFormat.getName().

Since:

2.3.24

getRegisteredCustomOutputFormats

public Collection<? extends OutputFormat> getRegisteredCustomOutputFormats()

Getter pair of setRegisteredCustomOutputFormats(Collection).

Since:

2.3.24

setRecognizeStandardFileExtensions

public void setRecognizeStandardFileExtensions(boolean recognizeStandardFileExtensions)

Sets if the "file" extension part of the source name (Template.getSourceName()) will influence certain parsing settings. For backward compatibility, it defaults to false if getIncompatibleImprovements() is less than 2.3.24. Starting from incompatibleImprovements 2.3.24, it defaults to true, so the following standard file extensions take their effect:

• ftlh: Sets outputFormat to "HTML" (i.e., HTMLOutputFormat.INSTANCE, unless the "HTML" name is overridden by setRegisteredCustomOutputFormats(Collection)) and autoEscapingPolicy to ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY.
• ftlx: Sets outputFormat to "XML" (i.e., XMLOutputFormat.INSTANCE, unless the "XML" name is overridden by setRegisteredCustomOutputFormats(Collection)) and autoEscapingPolicy to ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY.

These file extensions are not case sensitive. The file extension is the part after the last dot in the source name. If the source name contains no dot, then it has no file extension.

The settings activated by these file extensions override the setting values dictated by setTemplateConfigurations(TemplateConfigurationFactory).

unsetRecognizeStandardFileExtensions

public void unsetRecognizeStandardFileExtensions()

Resets the setting to its default, as if it was never set. This means that when you change the incompatibe_improvements setting later, the default will also change as appropriate. Also isRecognizeStandardFileExtensionsExplicitlySet() will return false.

Since:

2.3.24

isRecognizeStandardFileExtensionsExplicitlySet

public boolean isRecognizeStandardFileExtensionsExplicitlySet()

Tells if setRecognizeStandardFileExtensions(boolean) (or equivalent) was already called on this instance.

Since:

2.3.24

getRecognizeStandardFileExtensions

public boolean getRecognizeStandardFileExtensions()

Getter pair of setRecognizeStandardFileExtensions(boolean).

Specified by:

getRecognizeStandardFileExtensions in interface ParserConfiguration

Since:

2.3.24

setCFormat

public void setCFormat(CFormat cFormat)

Description copied from class: Configurable

Sets the format (usually a computer language) used for ?c, ?cn, and for the "c" ("computer" before 2.3.32) number_format, and the "c" boolean_format.

The default value depends on incompatible_improvements. If that's 2.3.32 or higher, then it's "JavaScript or JSON", otherwise it's "legacy".

Overrides:

setCFormat in class Configurable

unsetCFormat

public void unsetCFormat()

Resets the setting to its default, as if it was never set. This means that when you change the incompatibe_improvements setting later, the default will also change as appropriate. Also isCFormatExplicitlySet() will return false.

Since:

2.3.32

isCFormatExplicitlySet

public boolean isCFormatExplicitlySet()

Tells if setCFormat(CFormat) (or equivalent) was already called on this instance.

Since:

2.3.32

setTagSyntax

public void setTagSyntax(int tagSyntax)

Determines the tag syntax (like <#if x> VS [#if x]) of the template files that has no #ftl header to decide that. Don't confuse this with the interpolation syntax (setInterpolationSyntax(int)); they are independent.

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 tag syntax (the normal syntax), like <#include ...>
• SQUARE_BRACKET_TAG_SYNTAX: Use the square bracket tag syntax, like [#include ...]. Note that this does not change ${x} to [=...]; that's interpolation syntax, so use setInterpolationSyntax(int) for that.

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.

See Also:

setInterpolationSyntax(int)

getTagSyntax

public int getTagSyntax()

The getter pair of setTagSyntax(int).

Specified by:

getTagSyntax in interface ParserConfiguration

setInterpolationSyntax

public void setInterpolationSyntax(int interpolationSyntax)

Determines the interpolation syntax (like ${x} VS [=x]) of the template files. Don't confuse this with the tag syntax (setTagSyntax(int)); they are independent.

The interpolationSyntax parameter must be one of LEGACY_INTERPOLATION_SYNTAX, DOLLAR_INTERPOLATION_SYNTAX, and SQUARE_BRACKET_INTERPOLATION_SYNTAX. Note that SQUARE_BRACKET_INTERPOLATION_SYNTAX does not change <#if x> to [#if x]; that's tag syntax, so use setTagSyntax(int) for that.

Since:

2.3.28

See Also:

setTagSyntax(int)

getInterpolationSyntax

public int getInterpolationSyntax()

The getter pair of setInterpolationSyntax(int).

Specified by:

getInterpolationSyntax in interface ParserConfiguration

Since:

2.3.28

setNamingConvention

public void setNamingConvention(int namingConvention)

Sets the naming convention used for the identifiers that are part of the template language. The available naming conventions are legacy (directive (tag) names are all-lower-case likethis, others are snake case like_this), and camel case (likeThis). The default is auto-detect, which detects the naming convention used and enforces that same naming convention for the whole template.

This setting doesn't influence what naming convention is used for the setting names outside templates. Also, it won't ever convert the names of user-defined things, like of data-model members, or the names of user defined macros/functions. It only influences the names of the built-in directives (#elseIf VS elseif), built-ins (?upper_case VS ?upperCase ), special variables (.data_model VS .dataModel).

Which convention to use: FreeMarker prior to 2.3.23 has only supported LEGACY_NAMING_CONVENTION, so that's how most templates and examples out there are written as of 2015. But as templates today are mostly written by programmers and often access Java API-s which already use camel case, CAMEL_CASE_NAMING_CONVENTION is the recommended option for most projects. However, it's no necessary to make a application-wide decision; see auto-detection below.

FreeMarker will decide the naming convention automatically for each template individually when this setting is set to AUTO_DETECT_NAMING_CONVENTION (which is the default). The naming convention of a template is decided when the first core (non-user-defined) identifier is met during parsing (not during processing) where the naming convention is relevant (like for s?upperCase or s?upper_case it's relevant, but for s?length it isn't). At that point, the naming convention of the template is decided, and any later core identifier that uses a different convention will be a parsing error. As the naming convention is decided per template, it's not a problem if a template and the other template it #include-s/#import uses a different convention.

FreeMarker always enforces the same naming convention to be used consistently within the same template "file". Additionally, when this setting is set to non-AUTO_DETECT_NAMING_CONVENTION, the selected naming convention is enforced on all templates. Thus such a setup can be used to enforce an application-wide naming convention.

Non-strict tags (a long deprecated syntax from FreeMarker 1, activated via setStrictSyntaxMode(boolean)) are only recognized as FTL tags when they are using the LEGACY_NAMING_CONVENTION syntax, regardless of this setting. As they aren't exempt from the naming convention consistency enforcement, generally, you can't use strict CAMEL_CASE_NAMING_CONVENTION tags mixed with non-strict tags.

Parameters:

namingConvention - One of the AUTO_DETECT_NAMING_CONVENTION or LEGACY_NAMING_CONVENTION CAMEL_CASE_NAMING_CONVENTION.

Throws:

IllegalArgumentException - If the parameter isn't one of the valid constants.

Since:

2.3.23

getNamingConvention

public int getNamingConvention()

The getter pair of setNamingConvention(int).

Specified by:

getNamingConvention in interface ParserConfiguration

Since:

2.3.23

setTabSize

public void setTabSize(int tabSize)

Sets the assumed display width of the tab character (ASCII 9), which influences the column number shown in error messages (or the column number you get through other API-s). So for example if the users edit templates in an editor where the tab width is set to 4, you should set this to 4 so that the column numbers printed by FreeMarker will match the column number shown in the editor. This setting doesn't affect the output of templates, as a tab in the template will remain a tab in the output too. If you set this setting to 1, then tab characters will be kept in the return value of Template.getSource(int, int, int, int), otherwise they will be replaced with the appropriate number of spaces.

Parameters:

tabSize - At least 1, at most 256.

Since:

2.3.25

getTabSize

public int getTabSize()

The getter pair of setTabSize(int).

Specified by:

getTabSize in interface ParserConfiguration

Since:

2.3.25

getFallbackOnNullLoopVariable

public boolean getFallbackOnNullLoopVariable()

The getter pair of setFallbackOnNullLoopVariable(boolean).

Since:

2.3.29

setFallbackOnNullLoopVariable

public void setFallbackOnNullLoopVariable(boolean fallbackOnNullLoopVariable)

Specifies the behavior when reading a loop variable (like i in <#list items as i>, or in <@myMacro items; i>) that's null (missing); if true, FreeMarker will look for a variable with the same name in higher variable scopes, or if false the variable will be simply null (missing). For backward compatibility the default is true. The recommended value for new projects is false, as otherwise adding new variables to higher scopes (typically to the data-model) can unintentionally change the behavior of templates. You have to be quite unlucky for that to happen though: The newly added variable has to have the same name as the loop variable, and there must be some null (missing) values in what you loop through.

This setting doesn't influence the behavior of lambdas, like items?filter(i -> i?hasContent), as they never had this problem. Reading a lambda argument never falls back to higher scopes.

Since:

2.3.29

getTemplate

public Template getTemplate(String name)
                     throws TemplateNotFoundException,
MalformedTemplateNameException,
ParseException,
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, null, null, null, true, false); see more details there.

See Configuration for an example of basic usage.

Throws:

TemplateNotFoundException

MalformedTemplateNameException

ParseException

IOException

getTemplate

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

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

Throws:

TemplateNotFoundException

MalformedTemplateNameException

ParseException

IOException

getTemplate

public Template getTemplate(String name,
 String encoding)
                     throws TemplateNotFoundException,
MalformedTemplateNameException,
ParseException,
IOException

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

Throws:

TemplateNotFoundException

MalformedTemplateNameException

ParseException

IOException

getTemplate

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

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

Throws:

TemplateNotFoundException

MalformedTemplateNameException

ParseException

IOException

getTemplate

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

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

Throws:

TemplateNotFoundException

MalformedTemplateNameException

ParseException

IOException

getTemplate

public Template getTemplate(String name,
 Locale locale,
 String encoding,
 boolean parseAsFTL,
 boolean ignoreMissing)
                     throws TemplateNotFoundException,
MalformedTemplateNameException,
ParseException,
IOException

Shorthand for getTemplate(name, locale, null, encoding, parseAsFTL, ignoreMissing).

Throws:

TemplateNotFoundException

MalformedTemplateNameException

ParseException

IOException

Since:

2.3.21

getTemplate

public Template getTemplate(String name,
 Locale locale,
 Object customLookupCondition,
 String encoding,
 boolean parseAsFTL,
 boolean ignoreMissing)
                     throws TemplateNotFoundException,
MalformedTemplateNameException,
ParseException,
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 depends on 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"). Furthermore, 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. This is what Configurable.getLocale() on the resulting Template will return (unless it's overridden via getTemplateConfigurations()). This parameter can be null since 2.3.22, in which case it defaults to Configurable.getLocale() (note that Configurable.getLocale() will give the default value, not null). This parameter also drives localized template lookup. Assuming that you have specified en_US as the locale and myTemplate.ftl as the name of the template, and the default TemplateLookupStrategy is used and #setLocalizedLookup(boolean) localized_lookup is true, FreeMarker will first try to retrieve myTemplate_en_US.html, then myTemplate.en.ftl, and finally myTemplate.ftl. Note that that the template's locale will be en_US even if it only finds myTemplate.ftl. Note that when the locale setting is overridden with a TemplateConfiguration provided by getTemplateConfigurations(), that overrides the value specified here, but only after the localized lookup, that is, it modifies the template found by the localized lookup.

customLookupCondition - This value can be used by a custom TemplateLookupStrategy; has no effect with the default one. Can be null (though it's up to the custom TemplateLookupStrategy if it allows that). This object will be used as part of the cache key, so it must to have a proper Object.equals(Object) and Object.hashCode() method. It also should have reasonable Object.toString(), as it's possibly quoted in error messages. The expected type is up to the custom TemplateLookupStrategy. See also: TemplateLookupContext.getCustomLookupCondition().

encoding - Deprecated mechanism, null is the recommended; the charset used to interpret the template source code bytes (if it's read from a binary source). Can be null since 2.3.22, in which case it will default to getEncoding(Locale) where Locale is the locale parameter (when locale was null too, the its default value is used instead). Why is this deprecated: It doesn't make sense to get the same template with different encodings, hence, it's error prone to specify the encoding where you get the template. Instead, if you have template "files" with different charsets, you should use setTemplateConfigurations(TemplateConfigurationFactory), where you can associate encodings to individual templates based on their names (like which "directory" are they in, what's their file extension, etc.). The encoding associated with the templates that way overrides the encoding that you specify here.

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 TemplateNotFoundException 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:

TemplateNotFoundException - If the template could not be found. Note that this exception extends IOException.

MalformedTemplateNameException - If the template name given was in violation with the TemplateNameFormat in use. Note that this exception extends IOException.

ParseException - (extends IOException) if the template is syntactically bad. Note that this exception extends IOException.

IOException - If there was some other problem with reading the template "file". Note that the other exceptions extend IOException, so this should be catched the last.

Since:

2.3.22

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 the default system encoding.

unsetDefaultEncoding

public void unsetDefaultEncoding()

Resets the setting to its default, as if it was never set.

Since:

2.3.26

isDefaultEncodingExplicitlySet

public boolean isDefaultEncodingExplicitlySet()

Tells if setDefaultEncoding(String) (or equivalent) was already called on this instance, or it just holds the default value.

Since:

2.3.26

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

Parameters:

locale - Shouldn't be null, though for backward compatibility it's accepted when the locale to encoding Map (see earlier) is empty.

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)

setSharedVariables

public void setSharedVariables(Map<String,?> 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.29

setSharedVaribles

public void setSharedVaribles(Map map)
                       throws TemplateModelException

Deprecated.

Use setSharedVariables(Map) instead.

Same as setSharedVariables(Map), but with typo in the name.

Throws:

TemplateModelException

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:

setSharedVaribles(Map), setSharedVariable(String,Object), setSharedVariable(String,TemplateModel)

getSharedVariable

public TemplateModel getSharedVariable(String name)

Gets a shared variable. Shared 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 shared variables 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 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 processes templates.

removeTemplateFromCache

public void removeTemplateFromCache(String name)
                             throws IOException

Equivalent to removeTemplateFromCache(name, thisCfg.getLocale(), null, 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, null, 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(), null, 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, null, encoding, true).

Throws:

IOException

Since:

2.3.19

removeTemplateFromCache

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

Equivalent to removeTemplateFromCache(name, locale, null, encoding, parse).

Throws:

IOException

Since:

2.3.19

removeTemplateFromCache

public void removeTemplateFromCache(String name,
 Locale locale,
 Object customLookupCondition,
 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, Object, String, boolean, boolean).

This method is thread-safe and can be called while the engine processes templates.

Throws:

IOException

Since:

2.3.28

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.

With the default TemplateLookupStrategy, localized lookup works like this: Let's say your locale setting is Locale("en", "AU"), and you call cfg.getTemplate("foo.ftl"). Then FreeMarker will look for the template under these names, stopping at the first that exists: "foo_en_AU.ftl", "foo_en.ftl", "foo.ftl". See the description of the default value at setTemplateLookupStrategy(TemplateLookupStrategy) for a more details. If you need to generate different template names, use setTemplateLookupStrategy(TemplateLookupStrategy) with your custom TemplateLookupStrategy.

Note that changing the value of this setting causes the template cache to be emptied so that old lookup results won't be reused (since 2.3.22).

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 only when you get settings from somewhere as String-String name-value pairs (typically, as a Properties object). Below you find an overview of the settings available.

Note: As of FreeMarker 2.3.23, setting names can be written in camel case too. For example, instead of date_format you can also use dateFormat. It's likely that camel case will become to the recommended convention in the future.

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", or since 2.3.26, "JVM default" (ignoring case) to use the default locale of the Java environment.

• "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.

• "custom_number_formats": See Configurable.setCustomNumberFormats(Map).
  String value: Interpreted as an object builder expression.
  Example: { "hex": com.example.HexTemplateNumberFormatFactory, "gps": com.example.GPSTemplateNumberFormatFactory }

• "custom_date_formats": See Configurable.setCustomDateFormats(Map).
  String value: Interpreted as an object builder expression.
  Example: { "trade": com.example.TradeTemplateDateFormatFactory, "log": com.example.LogTemplateDateFormatFactory }

• "c_format": See setCFormat(CFormat).
  String value: "default" (case insensitive) for the default (on Configuration only), or one of the predefined values "JavaScript or JSON", "JSON", "JavaScript", "Java", "XS", "legacy", or an object builder expression that gives a CFormat object.

• "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), or "default" (only allowed for Configuration instances) for the default value.

• "attempt_exception_reporter": See Configurable.setAttemptExceptionReporter(AttemptExceptionReporter).
  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): "log_error" (means AttemptExceptionReporter.LOG_ERROR_REPORTER), "log_warn" (means AttemptExceptionReporter.LOG_WARN_REPORTER), or "default" (only allowed for Configuration instances) for the default value.

• "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, forceLegacyNonListCollections=false, iterableSupport=true)", "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 the default of Configuration (the default depends on the Configuration#Configuration(Version) incompatible_improvements, but a bug existed in 2.3.21 where that was ignored), "default_2_3_0" (means the deprecated ObjectWrapper.DEFAULT_WRAPPER) "simple" (means the deprecated ObjectWrapper.SIMPLE_WRAPPER), "beans" (means the deprecated 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(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(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.

• "auto_import": See Configurable.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 Configurable.setAutoIncludes(List)
  String value is something like:
  /include/common.ftl, "/include/evil name.ftl"

• "lazy_auto_imports": See Configurable.setLazyAutoImports(Boolean).
  String value: "true", "false" (also the equivalents: "yes", "no", "t", "f", "y", "n"), case insensitive. Also can be "null".

• "lazy_imports": See Configurable.setLazyImports(boolean).
  String value: "true", "false" (also the equivalents: "yes", "no", "t", "f", "y", "n"), case insensitive.

• "new_builtin_class_resolver": See Configurable.setNewBuiltinClassResolver(TemplateClassResolver). Since 2.3.17. The value must be one of these (ignore the quotation marks):

  1. "unrestricted": Use TemplateClassResolver.UNRESTRICTED_RESOLVER

  2. "safer": Use TemplateClassResolver.SAFER_RESOLVER

  3. "allows_nothing" (or "allowsNothing"): Use TemplateClassResolver.ALLOWS_NOTHING_RESOLVER

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

     trusted_templates value examples

     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.

  5. Otherwise if the value contains dot, it's interpreted as an object builder expression.

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

• api_builtin_enabled: See Configurable.setAPIBuiltinEnabled(boolean). Since 2.3.22.
  String value: "true", "false", "y", etc.

• "truncate_builtin_algorithm": See Configurable.setTruncateBuiltinAlgorithm(TruncateBuiltinAlgorithm). Since 2.3.19.
  String value: An object builder expression, or one of the predefined values (case insensitive), ascii (for DefaultTruncateBuiltinAlgorithm.ASCII_INSTANCE) and unicode (for DefaultTruncateBuiltinAlgorithm.UNICODE_INSTANCE).
  Example object builder expressions:
  Use "..." as terminator (and same as markup terminator), and add space if the truncation happened on word boundary:
  DefaultTruncateBuiltinAlgorithm("...", true)
  Use "..." as terminator, and also a custom HTML for markup terminator, and add space if the truncation happened on word boundary:
  DefaultTruncateBuiltinAlgorithm("...", markup(HTMLOutputFormat(), "<span class=trunc>...</span>"), true)
  Recreate default truncate algorithm, but with not preferring truncation at word boundaries (i.e., with wordBoundaryMinLength 1.0):
  freemarker.core.DefaultTruncateBuiltinAlgorithm(
DefaultTruncateBuiltinAlgorithm.STANDARD_ASCII_TERMINATOR, null, null,
DefaultTruncateBuiltinAlgorithm.STANDARD_M_TERMINATOR, null, null,
true, 1.0)

Configuration (a subclass of Configurable) also understands these:

• "auto_escaping": See setAutoEscapingPolicy(int)
  String value: "enable_if_default" or "enableIfDefault" for ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY, "enable_if_supported" or "enableIfSupported" for ENABLE_IF_SUPPORTED_AUTO_ESCAPING_POLICY, "force" for FORCE_AUTO_ESCAPING_POLICY, or "disable" for DISABLE_AUTO_ESCAPING_POLICY.

• "default_encoding": See setDefaultEncoding(String); since 2.3.26 also accepts value "JVM default" (not case sensitive) to set the Java environment default value.
  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.

• "output_format": See setOutputFormat(OutputFormat).
  String value: "default" (case insensitive) for the default, one of undefined, HTML, XHTML, XML, RTF, plainText, CSS, JavaScript, JSON, or an object builder expression that gives an OutputFormat, for example HTMLOutputFormat, or com.example.MyOutputFormat().

• "registered_custom_output_formats": See setRegisteredCustomOutputFormats(Collection).
  String value: an object builder expression that gives a List of OutputFormat-s. Example: [com.example.MyOutputFormat(), com.example.MyOtherOutputFormat()]

• "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:

  cache_storage value examples

  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": Template update delay in seconds (not in milliseconds) if no unit is specified; see setTemplateUpdateDelayMilliseconds(long) for more.
  String value: Valid positive integer, optionally followed by a time unit (recommended). The default unit is seconds. It's strongly recommended to specify the unit for clarity, like in "500 ms" or "30 s". Supported units are: "s" (seconds), "ms" (milliseconds), "m" (minutes), "h" (hours). The whitespace between the unit and the number is optional. Units are only supported since 2.3.23.

• "tag_syntax": See setTagSyntax(int).
  String value: Must be one of "auto_detect", "angle_bracket", and "square_bracket" (like [#if x]).
  Note that setting the "tagSyntax" to "square_bracket" does not change ${x} to [=...]; that's interpolation syntax, so use the "interpolation_syntax" setting for that, not this setting.

• "interpolation_syntax" (since 2.3.28): See setInterpolationSyntax(int).
  String value: Must be one of "legacy", "dollar", and "square_bracket" (like [=x]).
  Note that setting the "interpolation_syntax" to "square_bracket" does not change <#if x> to [#if x]; that's tag syntax, so use the "tag_syntax" setting for that, not this setting.

• "naming_convention": See setNamingConvention(int).
  String value: Must be one of "auto_detect", "legacy", and "camel_case".

• "fallback_on_null_loop_variable": See setFallbackOnNullLoopVariable(boolean).
  String value: "true", "false" (also the equivalents: "yes", "no", "t", "f", "y", "n"). Case insensitive.

• "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.

• "recognize_standard_file_extensions": See setRecognizeStandardFileExtensions(boolean).
  String value: "default" (case insensitive) for the default, or "true", "false", yes, etc.

• "template_configurations": See: setTemplateConfigurations(freemarker.cache.TemplateConfigurationFactory).
  String value: Interpreted as an object builder expression, can be null.

• "template_loader": See: setTemplateLoader(TemplateLoader).
  String value: "default" (case insensitive) for the default, or else interpreted as an object builder expression. "null" is also allowed since 2.3.26.

• "template_lookup_strategy": See: setTemplateLookupStrategy(freemarker.cache.TemplateLookupStrategy).
  String value: "default" (case insensitive) for the default, or else interpreted as an object builder expression.

• "template_name_format": See: setTemplateNameFormat(freemarker.cache.TemplateNameFormat).
  String value: "default" (case insensitive) for the default, "default_2_3_0" for TemplateNameFormat.DEFAULT_2_3_0, "default_2_4_0" for TemplateNameFormat.DEFAULT_2_4_0.

• "tab_size": See setTabSize(int).

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. Note that if you use the backward compatible syntax, where there's no parenthesis after the class name, then it will not look for INSTANCE.

• 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. Note that if you have a builder class, you don't actually need a className class (since 2.3.24); after all, classNameBuilder.build() can return any kind of object.

• Currently, the values of arguments and properties can only be one of these:

  • A numerical literal, like 123 or -1.5. The value will be automatically converted to the type of the target (just like in FTL). However, a target type is only available if the number will be a parameter to a method or constructor, not when it's a value (or key) in a List or Map literal. Thus in the last case the type of number will be like in Java language, like 1 is an int, and 1.0 is a double, and 1.0f is a float, etc. In all cases, the standard Java type postfixes can be used ("f", "d", "l"), plus "bd" for BigDecimal and "bi" for BigInteger.
  • 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".
  • A list literal (since 2.3.24) with FTL-like syntax, for example [ 'foo', 2, true ]. If the parameter is expected to be array, the list will be automatically converted to array. The list items can be any kind of expression, like even object builder expressions.
  • A map literal (since 2.3.24) with FTL-like syntax, for example { 'foo': 2, 'bar': true }. The keys and values can be any kind of expression, like even object builder expressions. The resulting Java object will be a Map that keeps the item order (LinkedHashMap as of this writing).
  • A reference to a public static filed, like Configuration.AUTO_DETECT_TAG_SYNTAX or com.example.MyClass.MY_CONSTANT.
  • An object builder expression. That is, object builder expressions can be nested into each other.
• The same kind of expression as for parameters can also be used as top-level expressions (though it's rarely useful, apart from using null).

• 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 following classes can be referred to with simple (unqualified) name instead of fully qualified name: DefaultObjectWrapper, BeansWrapper, SimpleObjectWrapper, Locale, TemplateConfiguration, PathGlobMatcher, FileNameGlobMatcher, PathRegexMatcher, AndMatcher, OrMatcher, NotMatcher, ConditionalTemplateConfigurationFactory, MergingTemplateConfigurationFactory, FirstMatchTemplateConfigurationFactory, HTMLOutputFormat, XMLOutputFormat, RTFOutputFormat, PlainTextOutputFormat, UndefinedOutputFormat, Configuration, DefaultTruncateBuiltinAlgorithm.

• TimeZone objects can be created like TimeZone("UTC"), despite that there's no a such constructor (since 2.3.24).

• TemplateMarkupOutputModel objects can be created like markup(HTMLOutputFormat(), "<h1>Example</h1>") (since 2.3.29). Of course the 1st argument can be any other MarkupOutputFormat too.

• 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.

getSettingNames

public Set<String> getSettingNames(boolean camelCase)

Returns the valid Configuration setting names. Naturally, this includes the Configurable setting names too.

Overrides:

getSettingNames in class Configurable

Parameters:

camelCase - If we want the setting names with camel case naming convention, or with snake case (legacy) naming convention.

Since:

2.3.24

See Also:

Configurable.getSettingNames(boolean)

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

doAutoImportsAndIncludes

protected void doAutoImportsAndIncludes(Environment env)
                                 throws TemplateException,
IOException

Description copied from class: Configurable

Executes the auto-imports and auto-includes for the main template of this environment. This is not meant to be called or overridden by code outside of FreeMarker.

Overrides:

doAutoImportsAndIncludes in class Configurable

Throws:

TemplateException

IOException

getVersionNumber

@Deprecated
public static String getVersionNumber()

Deprecated.

Use getVersion() instead.

Returns FreeMarker version number string.

getVersion

public static Version getVersion()

Returns FreeMarker version information, most importantly the major.minor.micro version numbers; do NOT use this as the value of the incompatible_improvements setting (as the parameter to Configuration(Version)), as then your application can break when you upgrade FreeMarker! Use a constant value, like VERSION_2_3_28, to protect your application from fixes/changes that aren't entirely backward compatible. Fixes and features that are backward compatible are always enabled. 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.

Starting from 2.3.33, Version.getBuildDate() will return null, as we don't store the build date anymore, to make the build reproducible.

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

Same as getSupportedBuiltInNames(int) with argument getNamingConvention().

Since:

2.3.20

getSupportedBuiltInNames

public Set<String> getSupportedBuiltInNames(int namingConvention)

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.

Parameters:

namingConvention - One of AUTO_DETECT_NAMING_CONVENTION, LEGACY_NAMING_CONVENTION, and CAMEL_CASE_NAMING_CONVENTION. If it's AUTO_DETECT_NAMING_CONVENTION then the union of the names in all the naming conventions is returned.

Since:

2.3.24

getSupportedBuiltInDirectiveNames

public Set getSupportedBuiltInDirectiveNames()

Same as getSupportedBuiltInDirectiveNames(int) with argument getNamingConvention().

Since:

2.3.21

getSupportedBuiltInDirectiveNames

public Set<String> getSupportedBuiltInDirectiveNames(int namingConvention)

Returns the names of the directives that are predefined by FreeMarker. These are the things that you call like <#directiveName ...>.

Parameters:

namingConvention - One of AUTO_DETECT_NAMING_CONVENTION, LEGACY_NAMING_CONVENTION, and CAMEL_CASE_NAMING_CONVENTION. If it's AUTO_DETECT_NAMING_CONVENTION then the union of the names in all the naming conventions is returned.

Since:

2.3.24