public class Configuration extends Configurable implements java.lang.Cloneable, ParserConfiguration
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 (seeConfiguration(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.
Configurable.SettingValueAssignmentException, Configurable.UnknownSettingException
Modifier and Type | Field and 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 java.lang.String |
AUTO_ESCAPING_POLICY_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
AUTO_ESCAPING_POLICY_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
AUTO_ESCAPING_POLICY_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
AUTO_IMPORT_KEY
Deprecated.
Use
Configurable.AUTO_IMPORT_KEY_SNAKE_CASE instead. |
static java.lang.String |
AUTO_IMPORT_KEY_CAMEL_CASE
Deprecated.
Use
Configurable.AUTO_IMPORT_KEY_CAMEL_CASE instead. |
static java.lang.String |
AUTO_IMPORT_KEY_SNAKE_CASE
Deprecated.
Use
Configurable.AUTO_IMPORT_KEY_SNAKE_CASE instead. |
static java.lang.String |
AUTO_INCLUDE_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
AUTO_INCLUDE_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
AUTO_INCLUDE_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
CACHE_STORAGE_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
CACHE_STORAGE_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
CACHE_STORAGE_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static int |
CAMEL_CASE_NAMING_CONVENTION |
static java.lang.String |
DEFAULT_ENCODING_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
DEFAULT_ENCODING_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
DEFAULT_ENCODING_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.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 java.lang.String |
FALLBACK_ON_NULL_LOOP_VARIABLE_KEY
Alias to the
..._SNAKE_CASE variation. |
static java.lang.String |
FALLBACK_ON_NULL_LOOP_VARIABLE_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
FALLBACK_ON_NULL_LOOP_VARIABLE_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
INCOMPATIBLE_ENHANCEMENTS
Deprecated.
Use
INCOMPATIBLE_IMPROVEMENTS_KEY instead. |
static java.lang.String |
INCOMPATIBLE_IMPROVEMENTS
Deprecated.
Use
INCOMPATIBLE_IMPROVEMENTS_KEY instead. |
static java.lang.String |
INCOMPATIBLE_IMPROVEMENTS_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
INCOMPATIBLE_IMPROVEMENTS_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
INCOMPATIBLE_IMPROVEMENTS_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
INTERPOLATION_SYNTAX_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
INTERPOLATION_SYNTAX_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.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 java.lang.String |
LOCALIZED_LOOKUP_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
LOCALIZED_LOOKUP_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
LOCALIZED_LOOKUP_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
NAMING_CONVENTION_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
NAMING_CONVENTION_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
NAMING_CONVENTION_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
OUTPUT_FORMAT_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
OUTPUT_FORMAT_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.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 java.lang.String |
RECOGNIZE_STANDARD_FILE_EXTENSIONS_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
RECOGNIZE_STANDARD_FILE_EXTENSIONS_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
RECOGNIZE_STANDARD_FILE_EXTENSIONS_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
REGISTERED_CUSTOM_OUTPUT_FORMATS_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
REGISTERED_CUSTOM_OUTPUT_FORMATS_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.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 java.lang.String |
STRICT_SYNTAX_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
STRICT_SYNTAX_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
STRICT_SYNTAX_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
TAB_SIZE_KEY
Alias to the
..._SNAKE_CASE variation. |
static java.lang.String |
TAB_SIZE_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
TAB_SIZE_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
TAG_SYNTAX_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
TAG_SYNTAX_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
TAG_SYNTAX_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
TEMPLATE_CONFIGURATIONS_KEY
Alias to the
..._SNAKE_CASE variation. |
static java.lang.String |
TEMPLATE_CONFIGURATIONS_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
TEMPLATE_CONFIGURATIONS_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
TEMPLATE_LOADER_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
TEMPLATE_LOADER_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
TEMPLATE_LOADER_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
TEMPLATE_LOOKUP_STRATEGY_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
TEMPLATE_LOOKUP_STRATEGY_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
TEMPLATE_LOOKUP_STRATEGY_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
TEMPLATE_NAME_FORMAT_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
TEMPLATE_NAME_FORMAT_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
TEMPLATE_NAME_FORMAT_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
TEMPLATE_UPDATE_DELAY_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
TEMPLATE_UPDATE_DELAY_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.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 java.lang.String |
WHITESPACE_STRIPPING_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
WHITESPACE_STRIPPING_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
WHITESPACE_STRIPPING_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
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 and Description |
---|
Configuration()
Deprecated.
Use
Configuration(Version) instead. Note that the version can be still modified later with
setIncompatibleImprovements(Version) (or
Configurable.setSettings(Properties) ). |
Configuration(Version incompatibleImprovements)
Creates a new instance and sets which of the non-backward-compatible bugfixes/improvements should be enabled.
|
Modifier and Type | Method and 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. |
java.lang.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 java.lang.String |
getCorrectedNameForUnknownSetting(java.lang.String name) |
static Configuration |
getDefaultConfiguration()
Deprecated.
The usage of the static singleton (the "default")
Configuration instance can easily cause erroneous, unpredictable
behavior. This is because multiple independent software components may use
FreeMarker internally inside the same application, so they will interfere
because of the common Configuration instance. Each such component
should use its own private Configuration object instead, that it
typically creates with new Configuration() when the component
is initialized. |
java.lang.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.
|
java.lang.String |
getEncoding(java.util.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) . |
java.lang.String |
getIncompatibleEnhancements()
Deprecated.
Use
getIncompatibleImprovements() instead. |
Version |
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(java.lang.String name)
Returns the output format for a name.
|
int |
getParsedIncompatibleEnhancements()
Deprecated.
Use
getIncompatibleImprovements() instead. |
boolean |
getRecognizeStandardFileExtensions()
Getter pair of
setRecognizeStandardFileExtensions(boolean) . |
java.util.Collection<? extends OutputFormat> |
getRegisteredCustomOutputFormats()
Getter pair of
setRegisteredCustomOutputFormats(Collection) . |
java.util.Set<java.lang.String> |
getSettingNames(boolean camelCase)
Returns the valid
Configuration setting names. |
TemplateModel |
getSharedVariable(java.lang.String name)
Gets a shared variable.
|
java.util.Set |
getSharedVariableNames()
Returns the set containing the names of all defined shared sharedVariables.
|
boolean |
getStrictSyntaxMode()
The getter pair of
setStrictSyntaxMode(boolean) . |
java.util.Set |
getSupportedBuiltInDirectiveNames()
Same as
getSupportedBuiltInDirectiveNames(int) with argument getNamingConvention() . |
java.util.Set<java.lang.String> |
getSupportedBuiltInDirectiveNames(int namingConvention)
Returns the names of the directives that are predefined by FreeMarker.
|
java.util.Set |
getSupportedBuiltInNames()
Same as
getSupportedBuiltInNames(int) with argument getNamingConvention() . |
java.util.Set<java.lang.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(java.lang.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(java.lang.String name,
java.util.Locale locale)
Shorthand for
getTemplate(name, locale, null, null, true, false) . |
Template |
getTemplate(java.lang.String name,
java.util.Locale locale,
java.lang.Object customLookupCondition,
java.lang.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(java.lang.String name,
java.util.Locale locale,
java.lang.String encoding)
Shorthand for
getTemplate(name, locale, null, encoding, true, false) . |
Template |
getTemplate(java.lang.String name,
java.util.Locale locale,
java.lang.String encoding,
boolean parseAsFTL)
Shorthand for
getTemplate(name, locale, null, encoding, parseAsFTL, false) . |
Template |
getTemplate(java.lang.String name,
java.util.Locale locale,
java.lang.String encoding,
boolean parseAsFTL,
boolean ignoreMissing)
|
Template |
getTemplate(java.lang.String name,
java.lang.String encoding)
Shorthand for
getTemplate(name, null, null, encoding, true, false) . |
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 java.lang.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(java.lang.String name)
|
void |
removeTemplateFromCache(java.lang.String name,
java.util.Locale locale)
|
void |
removeTemplateFromCache(java.lang.String name,
java.util.Locale locale,
java.lang.Object customLookupCondition,
java.lang.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(java.lang.String name,
java.util.Locale locale,
java.lang.String encoding)
Equivalent to
removeTemplateFromCache(name, locale, null, encoding, true) . |
void |
removeTemplateFromCache(java.lang.String name,
java.util.Locale locale,
java.lang.String encoding,
boolean parse)
Equivalent to
removeTemplateFromCache(name, locale, null, encoding, parse) . |
void |
removeTemplateFromCache(java.lang.String name,
java.lang.String encoding)
|
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(java.lang.Class resourceLoaderClass,
java.lang.String basePackagePath)
Sets the class whose
Class.getResource(String) method will be used to load templates, from the inside the
package specified. |
void |
setClassLoaderForTemplateLoading(java.lang.ClassLoader classLoader,
java.lang.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.
See more here... . |
void |
setDefaultEncoding(java.lang.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(java.io.File dir)
Sets the file system directory from which to load templates.
|
void |
setEncoding(java.util.Locale locale,
java.lang.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(java.lang.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(java.util.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 object wrapper used to wrap objects to
TemplateModel -s. |
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(java.util.Collection<? extends OutputFormat> registeredCustomOutputFormats)
Sets the custom output formats that can be referred by their unique name (
OutputFormat.getName() ) from
templates. |
void |
setServletContextForTemplateLoading(java.lang.Object servletContext,
java.lang.String path)
Sets the servlet context from which to load templates.
|
void |
setSetting(java.lang.String name,
java.lang.String value)
Sets a FreeMarker setting by a name and string value.
|
void |
setSharedVariable(java.lang.String name,
java.lang.Object value)
Adds shared variable to the configuration; It uses
Configurable.getObjectWrapper() to wrap the
value , so it's important that the object wrapper is set before this. |
void |
setSharedVariable(java.lang.String name,
TemplateModel tm)
Adds a shared variable to the configuration.
|
void |
setSharedVariables(java.util.Map<java.lang.String,?> map)
Replaces all shared variables (removes all previously added ones).
|
void |
setSharedVaribles(java.util.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(java.util.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() |
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
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
getArithmeticEngine
public static final java.lang.String DEFAULT_ENCODING_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String DEFAULT_ENCODING_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String DEFAULT_ENCODING_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String LOCALIZED_LOOKUP_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String LOCALIZED_LOOKUP_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String LOCALIZED_LOOKUP_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String STRICT_SYNTAX_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String STRICT_SYNTAX_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String STRICT_SYNTAX_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String WHITESPACE_STRIPPING_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String WHITESPACE_STRIPPING_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String WHITESPACE_STRIPPING_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String OUTPUT_FORMAT_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.24public static final java.lang.String OUTPUT_FORMAT_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.24public static final java.lang.String OUTPUT_FORMAT_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String RECOGNIZE_STANDARD_FILE_EXTENSIONS_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.24public static final java.lang.String RECOGNIZE_STANDARD_FILE_EXTENSIONS_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.24public static final java.lang.String RECOGNIZE_STANDARD_FILE_EXTENSIONS_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String REGISTERED_CUSTOM_OUTPUT_FORMATS_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.24public static final java.lang.String REGISTERED_CUSTOM_OUTPUT_FORMATS_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.24public static final java.lang.String REGISTERED_CUSTOM_OUTPUT_FORMATS_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String AUTO_ESCAPING_POLICY_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.24public static final java.lang.String AUTO_ESCAPING_POLICY_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.24public static final java.lang.String AUTO_ESCAPING_POLICY_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String CACHE_STORAGE_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String CACHE_STORAGE_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String CACHE_STORAGE_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String TEMPLATE_UPDATE_DELAY_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String TEMPLATE_UPDATE_DELAY_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String TEMPLATE_UPDATE_DELAY_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String AUTO_IMPORT_KEY_SNAKE_CASE
Configurable.AUTO_IMPORT_KEY_SNAKE_CASE
instead.like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String AUTO_IMPORT_KEY_CAMEL_CASE
Configurable.AUTO_IMPORT_KEY_CAMEL_CASE
instead.likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String AUTO_IMPORT_KEY
Configurable.AUTO_IMPORT_KEY_SNAKE_CASE
instead...._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String AUTO_INCLUDE_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String AUTO_INCLUDE_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String AUTO_INCLUDE_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String TAG_SYNTAX_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String TAG_SYNTAX_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String TAG_SYNTAX_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String INTERPOLATION_SYNTAX_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.28public static final java.lang.String INTERPOLATION_SYNTAX_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.28public static final java.lang.String INTERPOLATION_SYNTAX_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String NAMING_CONVENTION_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String NAMING_CONVENTION_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String NAMING_CONVENTION_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String TAB_SIZE_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.25public static final java.lang.String TAB_SIZE_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.25public static final java.lang.String TAB_SIZE_KEY
..._SNAKE_CASE
variation. @since 2.3.25public static final java.lang.String TEMPLATE_LOADER_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String TEMPLATE_LOADER_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String TEMPLATE_LOADER_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String TEMPLATE_LOOKUP_STRATEGY_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String TEMPLATE_LOOKUP_STRATEGY_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String TEMPLATE_LOOKUP_STRATEGY_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String TEMPLATE_NAME_FORMAT_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String TEMPLATE_NAME_FORMAT_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String TEMPLATE_NAME_FORMAT_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String TEMPLATE_CONFIGURATIONS_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.24public static final java.lang.String TEMPLATE_CONFIGURATIONS_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.24public static final java.lang.String TEMPLATE_CONFIGURATIONS_KEY
..._SNAKE_CASE
variation. @since 2.3.24public static final java.lang.String INCOMPATIBLE_IMPROVEMENTS_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String INCOMPATIBLE_IMPROVEMENTS_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String INCOMPATIBLE_IMPROVEMENTS_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.@Deprecated public static final java.lang.String INCOMPATIBLE_IMPROVEMENTS
INCOMPATIBLE_IMPROVEMENTS_KEY
instead.@Deprecated public static final java.lang.String INCOMPATIBLE_ENHANCEMENTS
INCOMPATIBLE_IMPROVEMENTS_KEY
instead.public static final java.lang.String FALLBACK_ON_NULL_LOOP_VARIABLE_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.29public static final java.lang.String FALLBACK_ON_NULL_LOOP_VARIABLE_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.29public static final java.lang.String FALLBACK_ON_NULL_LOOP_VARIABLE_KEY
..._SNAKE_CASE
variation. @since 2.3.25public static final int AUTO_DETECT_TAG_SYNTAX
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.public static final int ANGLE_BRACKET_TAG_SYNTAX
<#if x><@foo /></#if>
public static final int SQUARE_BRACKET_TAG_SYNTAX
[#if x][@foo /][/#if]
.
It does not change ${x}
to [=x]
; that's square bracket interpolation
syntax (SQUARE_BRACKET_INTERPOLATION_SYNTAX
).public static final int LEGACY_INTERPOLATION_SYNTAX
${expression}
and the deprecated #{expression; numFormat}
@since 2.3.28public static final int DOLLAR_INTERPOLATION_SYNTAX
${expression}
only (not #{expression; numFormat}
) @since 2.3.28public 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
).public static final int AUTO_DETECT_NAMING_CONVENTION
public static final int LEGACY_NAMING_CONVENTION
public static final int CAMEL_CASE_NAMING_CONVENTION
public static final int DISABLE_AUTO_ESCAPING_POLICY
OutputFormat
is. Note that a <#ftl auto_esc=true>
in the template will override this.public static final int ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY
MarkupOutputFormat.isAutoEscapedByDefault()
is
true
.public static final int ENABLE_IF_SUPPORTED_AUTO_ESCAPING_POLICY
OutputFormat
supports it.public static final Version VERSION_2_3_0
incompatible improvements break-point
)public static final Version VERSION_2_3_19
incompatible improvements break-point
)public static final Version VERSION_2_3_20
incompatible improvements break-point
)public static final Version VERSION_2_3_21
incompatible improvements break-point
)public static final Version VERSION_2_3_22
incompatible improvements break-point
)public static final Version VERSION_2_3_23
incompatible improvements break-point
)public static final Version VERSION_2_3_24
incompatible improvements break-point
)public static final Version VERSION_2_3_25
incompatible improvements break-point
)public static final Version VERSION_2_3_26
incompatible improvements break-point
)public static final Version VERSION_2_3_27
incompatible improvements break-point
)public static final Version VERSION_2_3_28
incompatible improvements break-point
)public static final Version VERSION_2_3_29
incompatible improvements break-point
)public static final Version VERSION_2_3_30
incompatible improvements break-point
)public static final Version VERSION_2_3_31
incompatible improvements break-point
)public static final Version VERSION_2_3_32
incompatible improvements break-point
)public static final Version DEFAULT_INCOMPATIBLE_IMPROVEMENTS
getIncompatibleImprovements()
, currently VERSION_2_3_0
.@Deprecated public static final java.lang.String DEFAULT_INCOMPATIBLE_ENHANCEMENTS
DEFAULT_INCOMPATIBLE_IMPROVEMENTS
instead.@Deprecated public static final int PARSED_DEFAULT_INCOMPATIBLE_ENHANCEMENTS
DEFAULT_INCOMPATIBLE_IMPROVEMENTS
instead.@Deprecated public Configuration()
Configuration(Version)
instead. Note that the version can be still modified later with
setIncompatibleImprovements(Version)
(or
Configurable.setSettings(Properties)
).public Configuration(Version incompatibleImprovements)
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_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.)
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 wont bring back the old behavior anymore. Information about that will be present here.
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.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.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):
SimpleDate
-s, now they come back as
java.util.Date
-s instead.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).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).
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.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):
BeansWrapper
and DefaultObjectWrapper
now exposes Java 8 default methods (and the bean
properties they define); see BeansWrapper.BeansWrapper(Version)
.
2.3.27 (or higher):
BeansWrapper
and DefaultObjectWrapper
now prefers the non-indexed JavaBean property
read method over the indexed read method when Java 8 exposes both;
see BeansWrapper.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"
.
java.lang.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
.public java.lang.Object clone()
clone
in class Configurable
public void loadBuiltInEncodingMap()
clearEncodingMap()
and then did multiple setEncoding(Locale, String)
calls.
It assumes the usual character encodings for most languages.
The previous content of the encoding map will be lost.
This default map currently contains the following mappings:
ar | ISO-8859-6 |
be | ISO-8859-5 |
bg | ISO-8859-5 |
ca | ISO-8859-1 |
cs | ISO-8859-2 |
da | ISO-8859-1 |
de | ISO-8859-1 |
el | ISO-8859-7 |
en | ISO-8859-1 |
es | ISO-8859-1 |
et | ISO-8859-1 |
fi | ISO-8859-1 |
fr | ISO-8859-1 |
hr | ISO-8859-2 |
hu | ISO-8859-2 |
is | ISO-8859-1 |
it | ISO-8859-1 |
iw | ISO-8859-8 |
ja | Shift_JIS |
ko | EUC-KR |
lt | ISO-8859-2 |
lv | ISO-8859-2 |
mk | ISO-8859-5 |
nl | ISO-8859-1 |
no | ISO-8859-1 |
pl | ISO-8859-2 |
pt | ISO-8859-1 |
ro | ISO-8859-2 |
ru | ISO-8859-5 |
sh | ISO-8859-5 |
sk | ISO-8859-2 |
sl | ISO-8859-2 |
sq | ISO-8859-2 |
sr | ISO-8859-5 |
sv | ISO-8859-1 |
tr | ISO-8859-9 |
uk | ISO-8859-5 |
zh | GB2312 |
zh_TW | Big5 |
public void clearEncodingMap()
@Deprecated public static Configuration getDefaultConfiguration()
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.@Deprecated public static void setDefaultConfiguration(Configuration config)
Configuration
instance can
easily lead to erroneous, unpredictable behaviour.
See more here...
.getDefaultConfiguration()
.public void setTemplateLoader(TemplateLoader templateLoader)
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
.)
public void unsetTemplateLoader()
incompatibe_improvements
setting later, the default will also change as appropriate. Also
isTemplateLoaderExplicitlySet()
will return false
.public boolean isTemplateLoaderExplicitlySet()
setTemplateLoader(TemplateLoader)
(or equivalent) was already called on this instance.public TemplateLoader getTemplateLoader()
setTemplateLoader(TemplateLoader)
.public void setTemplateLookupStrategy(TemplateLookupStrategy templateLookupStrategy)
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
.public void unsetTemplateLookupStrategy()
incompatibe_improvements
setting later, the default will also change as appropriate. Also
isTemplateLookupStrategyExplicitlySet()
will return false
.public boolean isTemplateLookupStrategyExplicitlySet()
setTemplateLookupStrategy(TemplateLookupStrategy)
(or equivalent) was already called on this
instance.public TemplateLookupStrategy getTemplateLookupStrategy()
setTemplateLookupStrategy(TemplateLookupStrategy)
.public void setTemplateNameFormat(TemplateNameFormat templateNameFormat)
TemplateNameFormat.DEFAULT_2_3_0
, while the
recommended value for new projects is TemplateNameFormat.DEFAULT_2_4_0
.public void unsetTemplateNameFormat()
incompatibe_improvements
setting later, the default will also change as appropriate. Also
isTemplateNameFormatExplicitlySet()
will return false
.public boolean isTemplateNameFormatExplicitlySet()
setTemplateNameFormat(TemplateNameFormat)
(or equivalent) was already called on this instance.public TemplateNameFormat getTemplateNameFormat()
setTemplateNameFormat(TemplateNameFormat)
.public void setTemplateConfigurations(TemplateConfigurationFactory templateConfigurations)
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.
public TemplateConfigurationFactory getTemplateConfigurations()
setTemplateConfigurations(TemplateConfigurationFactory)
.public void setCacheStorage(CacheStorage cacheStorage)
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.
public void unsetCacheStorage()
incompatibe_improvements
setting later, the default will also change as appropriate. Also
isCacheStorageExplicitlySet()
will return false
.public boolean isCacheStorageExplicitlySet()
setCacheStorage(CacheStorage)
(or equivalent) was already called on this instance.public CacheStorage getCacheStorage()
setCacheStorage(CacheStorage)
.public void setDirectoryForTemplateLoading(java.io.File dir) throws java.io.IOException
setTemplateLoader(new FileTemplateLoader(dir))
, so see
FileTemplateLoader.FileTemplateLoader(File)
for more details.
Note that FreeMarker can load templates from non-file-system sources too. See
setTemplateLoader(TemplateLoader)
from more details.
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.
java.io.IOException
public void setServletContextForTemplateLoading(java.lang.Object servletContext, java.lang.String path)
setTemplateLoader(new WebappTemplateLoader(sctxt, path))
or setTemplateLoader(new WebappTemplateLoader(sctxt))
if path
was
null
, so see freemarker.cache.WebappTemplateLoader
for more details.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.)path
- the path relative to the ServletContext.setTemplateLoader(TemplateLoader)
public void setClassForTemplateLoading(java.lang.Class resourceLoaderClass, java.lang.String basePackagePath)
Class.getResource(String)
method will be used to load templates, from the inside the
package specified. See ClassTemplateLoader.ClassTemplateLoader(Class, String)
for more details.basePackagePath
- Separate steps with "/"
, not "."
, and note that it matters if this starts with
/
or not. See ClassTemplateLoader.ClassTemplateLoader(Class, String)
for more details.setClassLoaderForTemplateLoading(ClassLoader, String)
,
setTemplateLoader(TemplateLoader)
public void setClassLoaderForTemplateLoading(java.lang.ClassLoader classLoader, java.lang.String basePackagePath)
ClassLoader
whose ClassLoader.getResource(String)
method will be used to load templates,
from the inside the package specified. See ClassTemplateLoader.ClassTemplateLoader(Class, String)
for
more details.basePackagePath
- Separate steps with "/"
, not "."
. See
ClassTemplateLoader.ClassTemplateLoader(Class, String)
for more details.setClassForTemplateLoading(Class, String)
,
setTemplateLoader(TemplateLoader)
@Deprecated public void setTemplateUpdateDelay(int seconds)
setTemplateUpdateDelayMilliseconds(long)
instead, because the time granularity of this method
is often misunderstood to be milliseconds.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.
public void setTemplateUpdateDelayMilliseconds(long millis)
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.
public long getTemplateUpdateDelayMilliseconds()
setTemplateUpdateDelayMilliseconds(long)
.@Deprecated public void setStrictSyntaxMode(boolean b)
true
(the default) value will be supported sometimes in the future.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).
public void setObjectWrapper(ObjectWrapper objectWrapper)
Configurable
TemplateModel
-s.
The default is ObjectWrapper.DEFAULT_WRAPPER
.setObjectWrapper
in class Configurable
public void unsetObjectWrapper()
incompatibe_improvements
setting later, the default will also change as appropriate. Also
isObjectWrapperExplicitlySet()
will return false
.public boolean isObjectWrapperExplicitlySet()
setObjectWrapper(ObjectWrapper)
(or equivalent) was already called on this instance.public void setLocale(java.util.Locale locale)
Configurable
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.setLocale
in class Configurable
getTemplate(String, Locale)
public void unsetLocale()
public boolean isLocaleExplicitlySet()
setLocale(Locale)
(or equivalent) was already called on this instance, or it just holds the
default value.public void setTimeZone(java.util.TimeZone timeZone)
Configurable
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)
!
setTimeZone
in class Configurable
Configurable.setSQLDateAndTimeTimeZone(TimeZone)
public void unsetTimeZone()
public boolean isTimeZoneExplicitlySet()
setTimeZone(TimeZone)
(or equivalent) was already called on this instance, or it just holds the
default value.public void setTemplateExceptionHandler(TemplateExceptionHandler templateExceptionHandler)
Configurable
TemplateExceptionHandler.DEBUG_HANDLER
. The recommended values are:
TemplateExceptionHandler.RETHROW_HANDLER
TemplateExceptionHandler.HTML_DEBUG_HANDLER
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).
public void unsetTemplateExceptionHandler()
incompatibe_improvements
setting later, the default will also change as appropriate. Also
isTemplateExceptionHandlerExplicitlySet()
will return false
.public boolean isTemplateExceptionHandlerExplicitlySet()
setTemplateExceptionHandler(TemplateExceptionHandler)
(or equivalent) was already called on
this instance.public void setAttemptExceptionReporter(AttemptExceptionReporter attemptExceptionReporter)
Configurable
#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.
setAttemptExceptionReporter
in class Configurable
public void unsetAttemptExceptionReporter()
incompatibe_improvements
setting later, the default will also change as appropriate. Also
isAttemptExceptionReporterExplicitlySet()
will return false
.public boolean isAttemptExceptionReporterExplicitlySet()
setAttemptExceptionReporter(AttemptExceptionReporter)
(or equivalent) was already called on
this instance.public void setLogTemplateExceptions(boolean value)
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.setLogTemplateExceptions
in class Configurable
public void unsetLogTemplateExceptions()
incompatibe_improvements
setting later, the default will also change as appropriate. Also
isTemplateExceptionHandlerExplicitlySet()
will return false
.public boolean isLogTemplateExceptionsExplicitlySet()
setLogTemplateExceptions(boolean)
(or equivalent) was already called on this instance.public void setWrapUncheckedExceptions(boolean value)
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.setWrapUncheckedExceptions
in class Configurable
public void unsetWrapUncheckedExceptions()
public boolean isWrapUncheckedExceptionsExplicitlySet()
setWrapUncheckedExceptions(boolean)
(or equivalent) was already called on this instance.public boolean getStrictSyntaxMode()
setStrictSyntaxMode(boolean)
.getStrictSyntaxMode
in interface ParserConfiguration
public void setIncompatibleImprovements(Version incompatibleImprovements)
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.
java.lang.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
.public Version getIncompatibleImprovements()
ParserConfiguration
getIncompatibleImprovements
in interface ParserConfiguration
null
.setIncompatibleImprovements(Version)
@Deprecated public void setIncompatibleEnhancements(java.lang.String version)
Configuration(Version)
, or
as last chance, setIncompatibleImprovements(Version)
instead.@Deprecated public java.lang.String getIncompatibleEnhancements()
getIncompatibleImprovements()
instead.@Deprecated public int getParsedIncompatibleEnhancements()
getIncompatibleImprovements()
instead.public void setWhitespaceStripping(boolean b)
public boolean getWhitespaceStripping()
getWhitespaceStripping
in interface ParserConfiguration
setWhitespaceStripping(boolean)
public void setAutoEscapingPolicy(int autoEscapingPolicy)
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:
${...}
, they will be
first converted to string (according the formatting settings and locale), then they are escaped just like
string values.
TemplateMarkupOutputModel
-s, they aren't escaped again (they are already escaped).
MarkupOutputFormat
.
That's the case for the default output format, UndefinedOutputFormat
, and also for
PlainTextOutputFormat
.
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)
.
autoEscapingPolicy
- One of the ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY
,
ENABLE_IF_SUPPORTED_AUTO_ESCAPING_POLICY
, and DISABLE_AUTO_ESCAPING_POLICY
constants.TemplateConfiguration.setAutoEscapingPolicy(int)
,
setOutputFormat(OutputFormat)
,
TemplateConfiguration.setOutputFormat(OutputFormat)
public int getAutoEscapingPolicy()
setAutoEscapingPolicy(int)
getAutoEscapingPolicy
in interface ParserConfiguration
public void setOutputFormat(OutputFormat outputFormat)
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.
outputFormat
- Not null
; use UndefinedOutputFormat.INSTANCE
instead.setRegisteredCustomOutputFormats(Collection)
,
setTemplateConfigurations(TemplateConfigurationFactory)
,
setRecognizeStandardFileExtensions(boolean)
,
setAutoEscapingPolicy(int)
public OutputFormat getOutputFormat()
setOutputFormat(OutputFormat)
getOutputFormat
in interface ParserConfiguration
public boolean isOutputFormatExplicitlySet()
setOutputFormat(OutputFormat)
(or equivalent) was already called on this instance.public void unsetOutputFormat()
incompatibe_improvements
setting later, the default will also change as appropriate. Also
isOutputFormatExplicitlySet()
will return false
.public OutputFormat getOutputFormat(java.lang.String name) throws UnregisteredOutputFormatException
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.null
.UnregisteredOutputFormatException
- If there's no output format registered with the given name.java.lang.IllegalArgumentException
- If the usage of {
and }
in the name is syntactically wrong, or if not all
OutputFormat
-s are MarkupOutputFormat
-s in the ...{...}
expression.public void setRegisteredCustomOutputFormats(java.util.Collection<? extends OutputFormat> registeredCustomOutputFormats)
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.
registeredCustomOutputFormats
- The collection of the OutputFormat
-s, each must be different and has a unique name (
OutputFormat.getName()
) within this collection.java.lang.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()
.public java.util.Collection<? extends OutputFormat> getRegisteredCustomOutputFormats()
setRegisteredCustomOutputFormats(Collection)
.public void setRecognizeStandardFileExtensions(boolean recognizeStandardFileExtensions)
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)
.
public void unsetRecognizeStandardFileExtensions()
incompatibe_improvements
setting later, the default will also change as appropriate. Also
isRecognizeStandardFileExtensionsExplicitlySet()
will return false
.public boolean isRecognizeStandardFileExtensionsExplicitlySet()
setRecognizeStandardFileExtensions(boolean)
(or equivalent) was already called on this
instance.public boolean getRecognizeStandardFileExtensions()
setRecognizeStandardFileExtensions(boolean)
.getRecognizeStandardFileExtensions
in interface ParserConfiguration
public void setCFormat(CFormat cFormat)
Configurable
?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"
.
setCFormat
in class Configurable
public void unsetCFormat()
incompatibe_improvements
setting later, the default will also change as appropriate. Also
isCFormatExplicitlySet()
will return false
.public boolean isCFormatExplicitlySet()
setCFormat(CFormat)
(or equivalent) was already called on this instance.public void setTagSyntax(int tagSyntax)
<#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.
setInterpolationSyntax(int)
public int getTagSyntax()
setTagSyntax(int)
.getTagSyntax
in interface ParserConfiguration
public void setInterpolationSyntax(int interpolationSyntax)
${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.
setTagSyntax(int)
public int getInterpolationSyntax()
setInterpolationSyntax(int)
.getInterpolationSyntax
in interface ParserConfiguration
public void setNamingConvention(int namingConvention)
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.
namingConvention
- One of the AUTO_DETECT_NAMING_CONVENTION
or LEGACY_NAMING_CONVENTION
CAMEL_CASE_NAMING_CONVENTION
.java.lang.IllegalArgumentException
- If the parameter isn't one of the valid constants.public int getNamingConvention()
setNamingConvention(int)
.getNamingConvention
in interface ParserConfiguration
public void setTabSize(int tabSize)
Template.getSource(int, int, int, int)
, otherwise they will be replaced with
the appropriate number of spaces.tabSize
- At least 1, at most 256.public int getTabSize()
setTabSize(int)
.getTabSize
in interface ParserConfiguration
public boolean getFallbackOnNullLoopVariable()
setFallbackOnNullLoopVariable(boolean)
.public void setFallbackOnNullLoopVariable(boolean fallbackOnNullLoopVariable)
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.
public Template getTemplate(java.lang.String name) throws TemplateNotFoundException, MalformedTemplateNameException, ParseException, java.io.IOException
This is a shorthand for getTemplate(name, null, null, null, true, false)
; see more details there.
See Configuration
for an example of basic usage.
TemplateNotFoundException
MalformedTemplateNameException
ParseException
java.io.IOException
public Template getTemplate(java.lang.String name, java.util.Locale locale) throws TemplateNotFoundException, MalformedTemplateNameException, ParseException, java.io.IOException
getTemplate(name, locale, null, null, true, false)
.TemplateNotFoundException
MalformedTemplateNameException
ParseException
java.io.IOException
public Template getTemplate(java.lang.String name, java.lang.String encoding) throws TemplateNotFoundException, MalformedTemplateNameException, ParseException, java.io.IOException
getTemplate(name, null, null, encoding, true, false)
.TemplateNotFoundException
MalformedTemplateNameException
ParseException
java.io.IOException
public Template getTemplate(java.lang.String name, java.util.Locale locale, java.lang.String encoding) throws TemplateNotFoundException, MalformedTemplateNameException, ParseException, java.io.IOException
getTemplate(name, locale, null, encoding, true, false)
.TemplateNotFoundException
MalformedTemplateNameException
ParseException
java.io.IOException
public Template getTemplate(java.lang.String name, java.util.Locale locale, java.lang.String encoding, boolean parseAsFTL) throws TemplateNotFoundException, MalformedTemplateNameException, ParseException, java.io.IOException
getTemplate(name, locale, null, encoding, parseAsFTL, false)
.TemplateNotFoundException
MalformedTemplateNameException
ParseException
java.io.IOException
public Template getTemplate(java.lang.String name, java.util.Locale locale, java.lang.String encoding, boolean parseAsFTL, boolean ignoreMissing) throws TemplateNotFoundException, MalformedTemplateNameException, ParseException, java.io.IOException
TemplateNotFoundException
MalformedTemplateNameException
ParseException
java.io.IOException
public Template getTemplate(java.lang.String name, java.util.Locale locale, java.lang.Object customLookupCondition, java.lang.String encoding, boolean parseAsFTL, boolean ignoreMissing) throws TemplateNotFoundException, MalformedTemplateNameException, ParseException, java.io.IOException
This method is thread-safe.
See Configuration
for an example of basic usage.
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.null
when the ignoreMissing
parameter is true
.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
.java.io.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.public void setDefaultEncoding(java.lang.String encoding)
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="...">
encoding
- The name of the charset, such as "UTF-8"
or "ISO-8859-1"
public java.lang.String getDefaultEncoding()
public void unsetDefaultEncoding()
public boolean isDefaultEncodingExplicitlySet()
setDefaultEncoding(String)
(or equivalent) was already called on this instance, or it just holds the
default value.public java.lang.String getEncoding(java.util.Locale locale)
setEncoding(Locale, String)
or loadBuiltInEncodingMap()
.locale
- Shouldn't be null
, though for backward compatibility it's accepted when the locale to
encoding Map
(see earlier) is empty.public void setEncoding(java.util.Locale locale, java.lang.String encoding)
setDefaultEncoding(java.lang.String)
.clearEncodingMap()
,
loadBuiltInEncodingMap()
public void setSharedVariable(java.lang.String name, TemplateModel tm)
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.
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.setAllSharedVariables(freemarker.template.TemplateHashModelEx)
,
setSharedVariable(String,Object)
public java.util.Set getSharedVariableNames()
public void setSharedVariable(java.lang.String name, java.lang.Object value) throws TemplateModelException
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.
TemplateModelException
- If some of the variables couldn't be wrapped via Configurable.getObjectWrapper()
.setSharedVaribles(Map)
,
setSharedVariable(String,TemplateModel)
,
setAllSharedVariables(TemplateHashModelEx)
public void setSharedVariables(java.util.Map<java.lang.String,?> map) throws TemplateModelException
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)
.
TemplateModelException
- If some of the variables couldn't be wrapped via Configurable.getObjectWrapper()
.public void setSharedVaribles(java.util.Map map) throws TemplateModelException
setSharedVariables(Map)
instead.setSharedVariables(Map)
, but with typo in the name.TemplateModelException
public void setAllSharedVariables(TemplateHashModelEx hash) throws TemplateModelException
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.
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.TemplateModelException
setSharedVaribles(Map)
,
setSharedVariable(String,Object)
,
setSharedVariable(String,TemplateModel)
public TemplateModel getSharedVariable(java.lang.String name)
public void clearSharedVariables()
public void clearTemplateCache()
getTemplate
calls.
This method is thread-safe and can be called while the engine processes templates.
public void removeTemplateFromCache(java.lang.String name) throws java.io.IOException
removeTemplateFromCache(name, thisCfg.getLocale(), null, thisCfg.getEncoding(thisCfg.getLocale()), true)
.java.io.IOException
public void removeTemplateFromCache(java.lang.String name, java.util.Locale locale) throws java.io.IOException
java.io.IOException
public void removeTemplateFromCache(java.lang.String name, java.lang.String encoding) throws java.io.IOException
java.io.IOException
public void removeTemplateFromCache(java.lang.String name, java.util.Locale locale, java.lang.String encoding) throws java.io.IOException
removeTemplateFromCache(name, locale, null, encoding, true)
.java.io.IOException
public void removeTemplateFromCache(java.lang.String name, java.util.Locale locale, java.lang.String encoding, boolean parse) throws java.io.IOException
removeTemplateFromCache(name, locale, null, encoding, parse)
.java.io.IOException
public void removeTemplateFromCache(java.lang.String name, java.util.Locale locale, java.lang.Object customLookupCondition, java.lang.String encoding, boolean parse) throws java.io.IOException
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.
java.io.IOException
public boolean getLocalizedLookup()
setLocalizedLookup(boolean)
.
This method is thread-safe and can be called while the engine works.
public void setLocalizedLookup(boolean localizedLookup)
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.
public void setSetting(java.lang.String name, java.lang.String value) throws TemplateException
Configurable
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):
"unrestricted"
:
Use TemplateClassResolver.UNRESTRICTED_RESOLVER
"safer"
:
Use TemplateClassResolver.SAFER_RESOLVER
"allows_nothing"
(or "allowsNothing"
):
Use TemplateClassResolver.ALLOWS_NOTHING_RESOLVER
Something that contains colon will use
OptInTemplateClassResolver
and is expected to
store comma separated values (possibly quoted) segmented
with "allowed_classes:"
(or "allowedClasses:"
) and/or
"trusted_templates:"
(or "trustedTemplates:"
). Examples of valid values:
Setting value | Meaning |
---|---|
allowed_classes: com.example.C1, com.example.C2,
trusted_templates: lib/*, safe.ftl
|
Only allow instantiating the com.example.C1 and
com.example.C2 classes. But, allow templates
within the lib/ directory (like
lib/foo/bar.ftl ) and template safe.ftl
(that does not match foo/safe.ftl , only
exactly safe.ftl ) to instantiate anything
that TemplateClassResolver.SAFER_RESOLVER allows.
|
allowed_classes: com.example.C1, com.example.C2
| Only allow instantiating the com.example.C1 and
com.example.C2 classes. There are no
trusted templates.
|
trusted_templates: lib/*, safe.ftl
|
Do not allow instantiating any classes, except in
templates inside lib/ or in template
safe.ftl .
|
For more details see OptInTemplateClassResolver
.
Otherwise if the value contains dot, it's interpreted as 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
"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:
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.
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 these'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:
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
.true
or false
null
"Line 1\nLine 2"
or r"C:\temp"
.
[ '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.
{ '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).
Configuration.AUTO_DETECT_TAG_SYNTAX
or
com.example.MyClass.MY_CONSTANT
.
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.
setSetting
in class Configurable
name
- the name of the setting.value
- the string that describes the new value of the setting.Configurable.UnknownSettingException
- if the name is wrong.TemplateException
- if the new value of the setting can't be set for any other reasons.public java.util.Set<java.lang.String> getSettingNames(boolean camelCase)
Configuration
setting names. Naturally, this includes the Configurable
setting
names too.getSettingNames
in class Configurable
camelCase
- If we want the setting names with camel case naming convention, or with snake case (legacy) naming
convention.Configurable.getSettingNames(boolean)
protected java.lang.String getCorrectedNameForUnknownSetting(java.lang.String name)
getCorrectedNameForUnknownSetting
in class Configurable
name
- The wrong namenull
if there's no known correctionprotected void doAutoImportsAndIncludes(Environment env) throws TemplateException, java.io.IOException
Configurable
doAutoImportsAndIncludes
in class Configurable
TemplateException
java.io.IOException
@Deprecated public static java.lang.String getVersionNumber()
getVersion()
instead.public static Version getVersion()
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:
public static ObjectWrapper getDefaultObjectWrapper(Version incompatibleImprovements)
setIncompatibleImprovements(Version)
public java.util.Set getSupportedBuiltInNames()
getSupportedBuiltInNames(int)
with argument getNamingConvention()
.public java.util.Set<java.lang.String> getSupportedBuiltInNames(int namingConvention)
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.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.public java.util.Set getSupportedBuiltInDirectiveNames()
getSupportedBuiltInDirectiveNames(int)
with argument getNamingConvention()
.public java.util.Set<java.lang.String> getSupportedBuiltInDirectiveNames(int namingConvention)
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.