Class Configuration
- java.lang.Object
-
- freemarker.core.Configurable
-
- freemarker.template.Configuration
-
- All Implemented Interfaces:
Cloneable
public class Configuration extends Configurable implements Cloneable
The main entry point into the FreeMarker API; encapsulates the configuration settings of FreeMarker, also serves as a central template-loading and caching service.This class is meant to be used in a singleton pattern. That is, you create an instance of this at the beginning of the application life-cycle, set its
configuration settings
there (either with the setter methods likesetTemplateLoader(TemplateLoader)
or by loading a.properties
file), and then use that single instance everywhere in your application. Frequently re-creatingConfiguration
is a typical and grave mistake from performance standpoint, as theConfiguration
holds the template cache, and often also the class introspection cache, which then will be lost. (Note that, naturally, having multiple long-lived instances, like one per component that internally uses FreeMarker is fine.)The basic usage pattern is like:
// Where the application is initialized; in general you do this ONLY ONCE in the application life-cycle! Configuration cfg = new Configuration(VERSION_X_Y_Z)); // Where X, Y, Z enables the not-100%-backward-compatible fixes introduced in // FreeMarker version X.Y.Z and earlier (see
Configuration(Version)
). cfg.setSomeSetting(...); cfg.setOtherSetting(...); ... // Later, whenever the application needs a template (so you may do this a lot, and from multiple threads):Template
myTemplate = cfg.getTemplate
("myTemplate.html"); myTemplate.process
(dataModel, out);A couple of settings that you should not leave on its default value are:
template_loader
: The default value is deprecated and in fact quite useless. (For the most common cases you can use the convenience methods,setDirectoryForTemplateLoading(File)
andsetClassForTemplateLoading(Class, String)
andsetClassLoaderForTemplateLoading(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 isTemplateExceptionHandler.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 theConfiguration
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, likegetTemplate(String)
, are thread-safe.
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from class freemarker.core.Configurable
Configurable.SettingValueAssignmentException, Configurable.UnknownSettingException
-
-
Field Summary
Fields Modifier and Type Field Description static int
ANGLE_BRACKET_TAG_SYNTAX
static int
AUTO_DETECT_NAMING_CONVENTION
static int
AUTO_DETECT_TAG_SYNTAX
static String
AUTO_IMPORT_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
AUTO_IMPORT_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
AUTO_IMPORT_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
AUTO_INCLUDE_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
AUTO_INCLUDE_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
AUTO_INCLUDE_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
CACHE_STORAGE_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
CACHE_STORAGE_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
CACHE_STORAGE_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static int
CAMEL_CASE_NAMING_CONVENTION
static String
DEFAULT_ENCODING_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
DEFAULT_ENCODING_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
DEFAULT_ENCODING_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
DEFAULT_INCOMPATIBLE_ENHANCEMENTS
Deprecated.UseDEFAULT_INCOMPATIBLE_IMPROVEMENTS
instead.static Version
DEFAULT_INCOMPATIBLE_IMPROVEMENTS
The default ofgetIncompatibleImprovements()
, currentlyVERSION_2_3_0
.static String
INCOMPATIBLE_ENHANCEMENTS
Deprecated.UseINCOMPATIBLE_IMPROVEMENTS_KEY
instead.static String
INCOMPATIBLE_IMPROVEMENTS
Deprecated.UseINCOMPATIBLE_IMPROVEMENTS_KEY
instead.static String
INCOMPATIBLE_IMPROVEMENTS_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
INCOMPATIBLE_IMPROVEMENTS_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
INCOMPATIBLE_IMPROVEMENTS_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static int
LEGACY_NAMING_CONVENTION
static String
LOCALIZED_LOOKUP_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
LOCALIZED_LOOKUP_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
LOCALIZED_LOOKUP_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
NAMING_CONVENTION_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
NAMING_CONVENTION_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
NAMING_CONVENTION_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static int
PARSED_DEFAULT_INCOMPATIBLE_ENHANCEMENTS
Deprecated.UseDEFAULT_INCOMPATIBLE_IMPROVEMENTS
instead.static int
SQUARE_BRACKET_TAG_SYNTAX
static String
STRICT_SYNTAX_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
STRICT_SYNTAX_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
STRICT_SYNTAX_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
TAG_SYNTAX_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
TAG_SYNTAX_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
TAG_SYNTAX_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
TEMPLATE_LOADER_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
TEMPLATE_LOADER_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
TEMPLATE_LOADER_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
TEMPLATE_LOOKUP_STRATEGY_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
TEMPLATE_LOOKUP_STRATEGY_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
TEMPLATE_LOOKUP_STRATEGY_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
TEMPLATE_NAME_FORMAT_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
TEMPLATE_NAME_FORMAT_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
TEMPLATE_NAME_FORMAT_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
TEMPLATE_UPDATE_DELAY_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
TEMPLATE_UPDATE_DELAY_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
TEMPLATE_UPDATE_DELAY_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static Version
VERSION_2_3_0
FreeMarker version 2.3.0 (anincompatible improvements break-point
)static Version
VERSION_2_3_19
FreeMarker version 2.3.19 (anincompatible improvements break-point
)static Version
VERSION_2_3_20
FreeMarker version 2.3.20 (anincompatible improvements break-point
)static Version
VERSION_2_3_21
FreeMarker version 2.3.21 (anincompatible improvements break-point
)static Version
VERSION_2_3_22
FreeMarker version 2.3.22 (anincompatible improvements break-point
)static Version
VERSION_2_3_23
FreeMarker version 2.3.23 (anincompatible improvements break-point
)static String
WHITESPACE_STRIPPING_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
WHITESPACE_STRIPPING_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
WHITESPACE_STRIPPING_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.-
Fields inherited from class freemarker.core.Configurable
API_BUILTIN_ENABLED_KEY, API_BUILTIN_ENABLED_KEY_CAMEL_CASE, API_BUILTIN_ENABLED_KEY_SNAKE_CASE, ARITHMETIC_ENGINE_KEY, ARITHMETIC_ENGINE_KEY_CAMEL_CASE, ARITHMETIC_ENGINE_KEY_SNAKE_CASE, 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, CLASSIC_COMPATIBLE_KEY, CLASSIC_COMPATIBLE_KEY_CAMEL_CASE, CLASSIC_COMPATIBLE_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, 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, URL_ESCAPING_CHARSET_KEY, URL_ESCAPING_CHARSET_KEY_CAMEL_CASE, URL_ESCAPING_CHARSET_KEY_SNAKE_CASE
-
-
Constructor Summary
Constructors Constructor Description Configuration()
Deprecated.UseConfiguration(Version)
instead.Configuration(Version incompatibleImprovements)
Creates a new instance and sets which of the non-backward-compatible bugfixes/improvements should be enabled.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
addAutoImport(String namespaceVarName, String templateName)
Adds an invisible#import templateName as namespaceVarName
at the beginning of all templates.void
addAutoInclude(String templateName)
Adds an invisible#include templateName as namespaceVarName
at the beginning of all templates.void
clearEncodingMap()
Clears language-to-encoding map.void
clearSharedVariables()
Removes all shared sharedVariables, except the predefined ones (compress, html_escape, etc.).void
clearTemplateCache()
Removes all entries from the template cache, thus forcing reloading of templates on subsequentgetTemplate
calls.Object
clone()
protected void
doAutoImportsAndIncludes(Environment env)
CacheStorage
getCacheStorage()
The getter pair ofsetCacheStorage(CacheStorage)
.protected String
getCorrectedNameForUnknownSetting(String name)
static Configuration
getDefaultConfiguration()
Deprecated.The usage of the static singleton (the "default")Configuration
instance can easily cause erroneous, unpredictable behavior.String
getDefaultEncoding()
Gets the default encoding for converting bytes to characters when reading template files in a locale for which no explicit encoding was specified.static ObjectWrapper
getDefaultObjectWrapper(Version incompatibleImprovements)
Returns the default object wrapper for a given "incompatible_improvements" version.String
getEncoding(Locale locale)
Gets the preferred character encoding for the given locale, or the default encoding if no encoding is set explicitly for the specified locale.String
getIncompatibleEnhancements()
Deprecated.UsegetIncompatibleImprovements()
instead.Version
getIncompatibleImprovements()
boolean
getLocalizedLookup()
The getter pair ofsetLocalizedLookup(boolean)
.int
getNamingConvention()
The getter pair ofsetNamingConvention(int)
.int
getParsedIncompatibleEnhancements()
Deprecated.UsegetIncompatibleImprovements()
instead.TemplateModel
getSharedVariable(String name)
Gets a shared variable.Set
getSharedVariableNames()
Returns the set containing the names of all defined shared sharedVariables.boolean
getStrictSyntaxMode()
The getter pair ofsetStrictSyntaxMode(boolean)
.Set
getSupportedBuiltInDirectiveNames()
Returns the names of the directives that are predefined by FreeMarker.Set
getSupportedBuiltInNames()
Returns the names of the supported "built-ins".int
getTagSyntax()
The getter pair ofsetTagSyntax(int)
.Template
getTemplate(String name)
Retrieves the template with the given name from the template cache, loading it into the cache first if it's missing/staled.Template
getTemplate(String name, String encoding)
Shorthand forgetTemplate(name, null, null, encoding, true, false)
.Template
getTemplate(String name, Locale locale)
Shorthand forgetTemplate(name, locale, null, null, true, false)
.Template
getTemplate(String name, Locale locale, Object customLookupCondition, String encoding, boolean parseAsFTL, boolean ignoreMissing)
Retrieves the template with the given name (and according the specified further parameters) from the template cache, loading it into the cache first if it's missing/staled.Template
getTemplate(String name, Locale locale, String encoding)
Shorthand forgetTemplate(name, locale, null, encoding, true, false)
.Template
getTemplate(String name, Locale locale, String encoding, boolean parseAsFTL)
Shorthand forgetTemplate(name, locale, null, encoding, parseAsFTL, false)
.Template
getTemplate(String name, Locale locale, String encoding, boolean parseAsFTL, boolean ignoreMissing)
TemplateLoader
getTemplateLoader()
The getter pair ofsetTemplateLoader(TemplateLoader)
.TemplateLookupStrategy
getTemplateLookupStrategy()
The getter pair ofsetTemplateLookupStrategy(TemplateLookupStrategy)
.TemplateNameFormat
getTemplateNameFormat()
The getter pair ofsetTemplateNameFormat(TemplateNameFormat)
.long
getTemplateUpdateDelayMilliseconds()
The getter pair ofsetTemplateUpdateDelayMilliseconds(long)
.static Version
getVersion()
Returns the FreeMarker version information, most importantly the major.minor.micro version numbers.static String
getVersionNumber()
Deprecated.UsegetVersion()
instead.boolean
getWhitespaceStripping()
Gets whether the FTL parser will try to remove superfluous white-space around certain FTL tags.boolean
isCacheStorageExplicitlySet()
Tells ifsetCacheStorage(CacheStorage)
(or equivalent) was already called on this instance.boolean
isLogTemplateExceptionsExplicitlySet()
Tells ifsetLogTemplateExceptions(boolean)
(or equivalent) was already called on this instance.boolean
isObjectWrapperExplicitlySet()
Tells ifsetObjectWrapper(ObjectWrapper)
(or equivalent) was already called on this instance.boolean
isTemplateExceptionHandlerExplicitlySet()
Tells ifsetTemplateExceptionHandler(TemplateExceptionHandler)
(or equivalent) was already called on this instance.boolean
isTemplateLoaderExplicitlySet()
Tells ifsetTemplateLoader(TemplateLoader)
(or equivalent) was already called on this instance.boolean
isTemplateLookupStrategyExplicitlySet()
Tells ifsetTemplateLookupStrategy(TemplateLookupStrategy)
(or equivalent) was already called on this instance.boolean
isTemplateNameFormatExplicitlySet()
Tells ifsetTemplateNameFormat(TemplateNameFormat)
(or equivalent) was already called on this instance.void
loadBuiltInEncodingMap()
Loads a preset language-to-encoding map, similarly as if you have calledclearEncodingMap()
and then did multiplesetEncoding(Locale, String)
calls.void
removeAutoImport(String namespaceVarName)
Removes an auto-import; seeaddAutoImport(String, String)
.void
removeAutoInclude(String templateName)
Removes a template from the auto-include list; seeaddAutoInclude(String)
.void
removeTemplateFromCache(String name)
Equivalent to removeTemplateFromCache(name, thisCfg.getLocale(), thisCfg.getEncoding(thisCfg.getLocale()), true).void
removeTemplateFromCache(String name, String encoding)
Equivalent to removeTemplateFromCache(name, thisCfg.getLocale(), encoding, true).void
removeTemplateFromCache(String name, Locale locale)
Equivalent to removeTemplateFromCache(name, locale, thisCfg.getEncoding(locale), true).void
removeTemplateFromCache(String name, Locale locale, String encoding)
Equivalent to removeTemplateFromCache(name, locale, encoding, true).void
removeTemplateFromCache(String name, Locale locale, String encoding, boolean parse)
Removes a template from the template cache, hence forcing the re-loading of it when it's next time requested.void
setAllSharedVariables(TemplateHashModelEx hash)
Adds all object in the hash as shared variable to the configuration; it's like doing severalsetSharedVariable(String, Object)
calls, one for each hash entry.void
setAutoImports(Map map)
Removes all auto-imports, then callsaddAutoImport(String, String)
for eachMap
-entry (the entry key is thenamespaceVarName
).void
setAutoIncludes(List templateNames)
Removes all auto-includes, then callsaddAutoInclude(String)
for eachList
items.void
setCacheStorage(CacheStorage cacheStorage)
Sets theCacheStorage
used for cachingTemplate
-s; the earlier content of the template cache will be dropt.void
setClassForTemplateLoading(Class resourceLoaderClass, String basePackagePath)
Sets the class whoseClass.getResource(String)
method will be used to load templates, from the inside the package specified.void
setClassLoaderForTemplateLoading(ClassLoader classLoader, String basePackagePath)
Sets theClassLoader
whoseClassLoader.getResource(String)
method will be used to load templates, from the inside the package specified.static void
setDefaultConfiguration(Configuration config)
Deprecated.Using the "default"Configuration
instance can easily lead to erroneous, unpredictable behaviour.void
setDefaultEncoding(String encoding)
Sets the charset used for decoding byte sequences to character sequences when reading template files in a locale for which no explicit encoding was specified viasetEncoding(Locale, String)
.void
setDirectoryForTemplateLoading(File dir)
Sets the file system directory from which to load templates.void
setEncoding(Locale locale, String encoding)
Sets the character set encoding to use for templates of a given locale.void
setIncompatibleEnhancements(String version)
Deprecated.UseConfiguration(Version)
, or as last chance,setIncompatibleImprovements(Version)
instead.void
setIncompatibleImprovements(Version incompatibleImprovements)
UseConfiguration(Version)
instead if possible; see the meaning of the parameter there.void
setLocalizedLookup(boolean localizedLookup)
Enables/disables localized template lookup.void
setLogTemplateExceptions(boolean value)
Specifies ifTemplateException
-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 toTemplateModel
-s.void
setServletContextForTemplateLoading(Object servletContext, String path)
Sets the servlet context from which to load templates.void
setSetting(String name, String value)
Sets a FreeMarker setting by a name and string value.void
setSharedVariable(String name, TemplateModel tm)
Adds a shared variable to the configuration.void
setSharedVariable(String name, Object value)
Adds shared variable to the configuration; It usesConfigurable.getObjectWrapper()
to wrap thevalue
, so it's important that the object wrapper is set before this.void
setSharedVaribles(Map map)
Replaces all shared variables (removes all previously added ones).void
setStrictSyntaxMode(boolean b)
Deprecated.Onlytrue
(the default) value will be supported sometimes in the future.void
setTagSyntax(int tagSyntax)
Determines the syntax of the template files (angle bracket VS square bracket) that has no#ftl
in it.void
setTemplateExceptionHandler(TemplateExceptionHandler templateExceptionHandler)
Sets the exception handler used to handle exceptions occurring inside templates.void
setTemplateLoader(TemplateLoader templateLoader)
Sets aTemplateLoader
that is used to look up and load templates; as a side effect the template cache will be emptied.void
setTemplateLookupStrategy(TemplateLookupStrategy templateLookupStrategy)
Sets aTemplateLookupStrategy
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.UsesetTemplateUpdateDelayMilliseconds(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" exists than the cached one.void
setWhitespaceStripping(boolean b)
Sets whether the FTL parser will try to remove superfluous white-space around certain FTL tags.void
unsetCacheStorage()
Resets the setting to its default, as it was never set.void
unsetLogTemplateExceptions()
Resets the setting to its default, as it was never set.void
unsetObjectWrapper()
Resets the setting to its default, as it was never set.void
unsetTemplateExceptionHandler()
Resets the setting to its default, as it was never set.void
unsetTemplateLoader()
Resets the setting to its default, as it was never set.void
unsetTemplateLookupStrategy()
Resets the setting to its default, as it was never set.void
unsetTemplateNameFormat()
Resets the setting to its default, as it was never set.-
Methods inherited from class freemarker.core.Configurable
getArithmeticEngine, getAutoFlush, getBooleanFormat, getClassicCompatibleAsInt, getCustomAttribute, getCustomAttributeNames, getDateFormat, getDateTimeFormat, getEnvironment, getLocale, getLogTemplateExceptions, getNewBuiltinClassResolver, getNumberFormat, getObjectWrapper, getOutputEncoding, getParent, getSetting, getSettings, getShowErrorTips, getSQLDateAndTimeTimeZone, getTemplateExceptionHandler, getTimeFormat, getTimeZone, getURLEscapingCharset, invalidSettingValueException, isAPIBuiltinEnabled, isClassicCompatible, parseAsImportList, parseAsList, parseAsSegmentedList, removeCustomAttribute, setAPIBuiltinEnabled, setArithmeticEngine, setAutoFlush, setBooleanFormat, setClassicCompatible, setClassicCompatibleAsInt, setCustomAttribute, setDateFormat, setDateTimeFormat, setLocale, setNewBuiltinClassResolver, setNumberFormat, setOutputEncoding, setSettings, setSettings, setShowErrorTips, setSQLDateAndTimeTimeZone, setStrictBeanModels, setTimeFormat, setTimeZone, settingValueAssignmentException, setURLEscapingCharset, unknownSettingException
-
-
-
-
Field Detail
-
DEFAULT_ENCODING_KEY_SNAKE_CASE
public static final String DEFAULT_ENCODING_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
DEFAULT_ENCODING_KEY_CAMEL_CASE
public static final String DEFAULT_ENCODING_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
DEFAULT_ENCODING_KEY
public static final String DEFAULT_ENCODING_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
LOCALIZED_LOOKUP_KEY_SNAKE_CASE
public static final String LOCALIZED_LOOKUP_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
LOCALIZED_LOOKUP_KEY_CAMEL_CASE
public static final String LOCALIZED_LOOKUP_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
LOCALIZED_LOOKUP_KEY
public static final String LOCALIZED_LOOKUP_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
STRICT_SYNTAX_KEY_SNAKE_CASE
public static final String STRICT_SYNTAX_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
STRICT_SYNTAX_KEY_CAMEL_CASE
public static final String STRICT_SYNTAX_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
STRICT_SYNTAX_KEY
public static final String STRICT_SYNTAX_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
WHITESPACE_STRIPPING_KEY_SNAKE_CASE
public static final String WHITESPACE_STRIPPING_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
WHITESPACE_STRIPPING_KEY_CAMEL_CASE
public static final String WHITESPACE_STRIPPING_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
WHITESPACE_STRIPPING_KEY
public static final String WHITESPACE_STRIPPING_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
CACHE_STORAGE_KEY_SNAKE_CASE
public static final String CACHE_STORAGE_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
CACHE_STORAGE_KEY_CAMEL_CASE
public static final String CACHE_STORAGE_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
CACHE_STORAGE_KEY
public static final String CACHE_STORAGE_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
TEMPLATE_UPDATE_DELAY_KEY_SNAKE_CASE
public static final String TEMPLATE_UPDATE_DELAY_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
TEMPLATE_UPDATE_DELAY_KEY_CAMEL_CASE
public static final String TEMPLATE_UPDATE_DELAY_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
TEMPLATE_UPDATE_DELAY_KEY
public static final String TEMPLATE_UPDATE_DELAY_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
AUTO_IMPORT_KEY_SNAKE_CASE
public static final String AUTO_IMPORT_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
AUTO_IMPORT_KEY_CAMEL_CASE
public static final String AUTO_IMPORT_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
AUTO_IMPORT_KEY
public static final String AUTO_IMPORT_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
AUTO_INCLUDE_KEY_SNAKE_CASE
public static final String AUTO_INCLUDE_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
AUTO_INCLUDE_KEY_CAMEL_CASE
public static final String AUTO_INCLUDE_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
AUTO_INCLUDE_KEY
public static final String AUTO_INCLUDE_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
TAG_SYNTAX_KEY_SNAKE_CASE
public static final String TAG_SYNTAX_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
TAG_SYNTAX_KEY_CAMEL_CASE
public static final String TAG_SYNTAX_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
TAG_SYNTAX_KEY
public static final String TAG_SYNTAX_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
NAMING_CONVENTION_KEY_SNAKE_CASE
public static final String NAMING_CONVENTION_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
NAMING_CONVENTION_KEY_CAMEL_CASE
public static final String NAMING_CONVENTION_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
NAMING_CONVENTION_KEY
public static final String NAMING_CONVENTION_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
TEMPLATE_LOADER_KEY_SNAKE_CASE
public static final String TEMPLATE_LOADER_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
TEMPLATE_LOADER_KEY_CAMEL_CASE
public static final String TEMPLATE_LOADER_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
TEMPLATE_LOADER_KEY
public static final String TEMPLATE_LOADER_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
TEMPLATE_LOOKUP_STRATEGY_KEY_SNAKE_CASE
public static final String TEMPLATE_LOOKUP_STRATEGY_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
TEMPLATE_LOOKUP_STRATEGY_KEY_CAMEL_CASE
public static final String TEMPLATE_LOOKUP_STRATEGY_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
TEMPLATE_LOOKUP_STRATEGY_KEY
public static final String TEMPLATE_LOOKUP_STRATEGY_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
TEMPLATE_NAME_FORMAT_KEY_SNAKE_CASE
public static final String TEMPLATE_NAME_FORMAT_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
TEMPLATE_NAME_FORMAT_KEY_CAMEL_CASE
public static final String TEMPLATE_NAME_FORMAT_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
TEMPLATE_NAME_FORMAT_KEY
public static final String TEMPLATE_NAME_FORMAT_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
INCOMPATIBLE_IMPROVEMENTS_KEY_SNAKE_CASE
public static final String INCOMPATIBLE_IMPROVEMENTS_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
INCOMPATIBLE_IMPROVEMENTS_KEY_CAMEL_CASE
public static final String INCOMPATIBLE_IMPROVEMENTS_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
INCOMPATIBLE_IMPROVEMENTS_KEY
public static final String INCOMPATIBLE_IMPROVEMENTS_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
INCOMPATIBLE_IMPROVEMENTS
public static final String INCOMPATIBLE_IMPROVEMENTS
Deprecated.UseINCOMPATIBLE_IMPROVEMENTS_KEY
instead.- See Also:
- Constant Field Values
-
INCOMPATIBLE_ENHANCEMENTS
public static final String INCOMPATIBLE_ENHANCEMENTS
Deprecated.UseINCOMPATIBLE_IMPROVEMENTS_KEY
instead.- See Also:
- Constant Field Values
-
AUTO_DETECT_TAG_SYNTAX
public static final int AUTO_DETECT_TAG_SYNTAX
- See Also:
- Constant Field Values
-
ANGLE_BRACKET_TAG_SYNTAX
public static final int ANGLE_BRACKET_TAG_SYNTAX
- See Also:
- Constant Field Values
-
SQUARE_BRACKET_TAG_SYNTAX
public static final int SQUARE_BRACKET_TAG_SYNTAX
- See Also:
- Constant Field Values
-
AUTO_DETECT_NAMING_CONVENTION
public static final int AUTO_DETECT_NAMING_CONVENTION
- See Also:
- Constant Field Values
-
LEGACY_NAMING_CONVENTION
public static final int LEGACY_NAMING_CONVENTION
- See Also:
- Constant Field Values
-
CAMEL_CASE_NAMING_CONVENTION
public static final int CAMEL_CASE_NAMING_CONVENTION
- See Also:
- Constant Field Values
-
VERSION_2_3_0
public static final Version VERSION_2_3_0
FreeMarker version 2.3.0 (anincompatible improvements break-point
)
-
VERSION_2_3_19
public static final Version VERSION_2_3_19
FreeMarker version 2.3.19 (anincompatible improvements break-point
)
-
VERSION_2_3_20
public static final Version VERSION_2_3_20
FreeMarker version 2.3.20 (anincompatible improvements break-point
)
-
VERSION_2_3_21
public static final Version VERSION_2_3_21
FreeMarker version 2.3.21 (anincompatible improvements break-point
)
-
VERSION_2_3_22
public static final Version VERSION_2_3_22
FreeMarker version 2.3.22 (anincompatible improvements break-point
)
-
VERSION_2_3_23
public static final Version VERSION_2_3_23
FreeMarker version 2.3.23 (anincompatible improvements break-point
)
-
DEFAULT_INCOMPATIBLE_IMPROVEMENTS
public static final Version DEFAULT_INCOMPATIBLE_IMPROVEMENTS
The default ofgetIncompatibleImprovements()
, currentlyVERSION_2_3_0
.
-
DEFAULT_INCOMPATIBLE_ENHANCEMENTS
public static final String DEFAULT_INCOMPATIBLE_ENHANCEMENTS
Deprecated.UseDEFAULT_INCOMPATIBLE_IMPROVEMENTS
instead.
-
PARSED_DEFAULT_INCOMPATIBLE_ENHANCEMENTS
public static final int PARSED_DEFAULT_INCOMPATIBLE_ENHANCEMENTS
Deprecated.UseDEFAULT_INCOMPATIBLE_IMPROVEMENTS
instead.
-
-
Constructor Detail
-
Configuration
public Configuration()
Deprecated.UseConfiguration(Version)
instead. Note that the version can be still modified later withsetIncompatibleImprovements(Version)
(orConfigurable.setSettings(Properties)
).
-
Configuration
public Configuration(Version incompatibleImprovements)
Creates a new instance and sets which of the non-backward-compatible bugfixes/improvements should be enabled. Note that the specified versions corresponds to theincompatible_improvements
configuration setting, and can be changed later, withsetIncompatibleImprovements(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 FreeMarker version that you are actually using. In older projects it's also usually better to keep this high, however you better check the changes activated (find them below), at least 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 always 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.
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 older projects. This is the default in the FreeMarker 2.3.x series.
2.3.19 (or higher): Bug fix: Wrong
#
tags were printed as static text instead of causing parsing error when there was no correct#
or@
tag earlier in the same template.2.3.20 (or higher):
?html
will escape apostrophe-quotes just like?xhtml
does. Utilizing this is highly recommended, because otherwise if interpolations are used inside attribute values that use apostrophe-quotation (<foo bar='${val}'>) instead of plain quotation mark (<foo bar="${val}">), they might produce HTML/XML that's not well-formed. Note that?html
didn't do this because long ago there was no cross-browser way of doing this, but it's not a concern anymore.2.3.21 (or higher):
The default of the
object_wrapper
setting (Configurable.getObjectWrapper()
) changes fromObjectWrapper.DEFAULT_WRAPPER
to another almost identicalDefaultObjectWrapper
singleton, returned byDefaultObjectWrapperBuilder.build()
. The new default object wrapper's "incompatible improvements" version is set to the same as of theConfiguration
. SeeBeansWrapper(Version)
for further details. Furthermore, the new default object wrapper doesn't allow changing its settings; setter methods throwIllegalStateException
). (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 otherBeansWrapper
-s created withBeansWrapperBuilder
, which has an impact asBeansWrapper.clearClassIntrospecitonCache()
will be disallowed; see more about it there.The
?iso_...
built-ins won't show the time zone offset forTime
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 usingmyTime?string.iso_fz
(and its other variants).?is_enumerable
correctly returnsfalse
for Java methods get from Java objects that are wrapped withBeansWrapper
and its subclasses, likeDefaultObjectWrapper
. Although method values implementTemplateSequenceModel
(because of a historical design quirk inBeansWrapper
), 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 whatDecimalFormat
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 ofhash[key]
and how maps work in Java.In most cases (where FreeMarker is able to do that), for
TemplateLoader
-s that useURLConnection
,URLConnection#setUseCaches(boolean)
will called withfalse
, so that only FreeMarker will do caching, not the URL scheme's handler. SeeURLTemplateLoader.setURLConnectionUsesCaches(Boolean)
for more details.The default of the
template_loader
setting (getTemplateLoader()
) changes tonull
, which means that FreeMarker will not find any templates. Earlier the default was aFileTemplateLoader
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 thetemplate_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 (likehits[10..]
).Empty ranges return
Constants.EMPTY_SEQUENCE
instead of an emptySimpleSequence
. This is in theory backward compatible, as the API only promises to give something that implementsTemplateSequenceModel
.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 withincompatibleImprovements
2.3.22; check them out atDefaultObjectWrapper(Version)
. It's important to know that if you set theobject_wrapper
setting (to an other value than"default"
), rather than leaving it on its default value, theobject_wrapper
won't inherit theincompatibleImprovements
of theConfiguration
. In that case, if you want the 2.3.22 improvements ofDefaultObjectWrapper
, you have to set it in theDefaultObjectWrapper
object itself too! (Note that it's OK to use aDefaultObjectWrapper
with a differentincompatibleImprovements
version number than that of theConfiguration
, 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 withincompatible_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 setincompatible_improvement
to 2.3.23 (whileConfigurable.getParent()
) ofEnvironment
keeps the changed behavior shown in the next point).#include
and#nested
doesn't change the parentTemplate
(seeConfigurable.getParent()
) of theEnvironment
anymore to theTemplate
that's included or whose namespace#nested
"returns" to. Thus, the parent ofEnvironment
will be now always the mainTemplate
. (The mainTemplate
is theTemplate
whoseprocess
orcreateProcessingEnvironment
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 onTemplate
objects, and almost nobody does that. Also note that macro calls have never changed theEnvironment
parent to theTemplate
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 JSPPageContext
API) and later read back with the JSPPageContext
API (typically in a custom JSP tag), might come back as FreeMarkerTemplateModel
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 useDefaultObjectWrapper
orSimpleObjectWrapper
(or a subclass of them):- FTL date/time/date-time values may came back as
SimpleDate
-s, now they come back asjava.util.Date
-s instead. - FTL sequence values may came back as
SimpleSequence
-s, now they come back asList
-s as expected. This at least stands assuming that theobject_wrapper
configuration setting is a subclass ofBeansWrapper
(such asDefaultObjectWrapper
, 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 theObjectWrapper
implementation). - FTL hash values may came back as
SimpleHash
-es, now they come back asMap
-s as expected (again, assuming that the object wrapper is a subclass ofBeansWrapper
, like preferablyDefaultObjectWrapper
, which is also the default). - FTL collection values may came back as
SimpleCollection
-s, now they come back asCollection
-s as expected (again, assuming that the object wrapper is a subclass ofBeansWrapper
, like preferablyDefaultObjectWrapper
).
- FTL date/time/date-time values may came back as
Initial
"["
in theTemplatePath
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.)
- Throws:
IllegalArgumentException
- IfincompatibleImmprovements
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 isnull
.- Since:
- 2.3.21
-
-
Method Detail
-
clone
public Object clone()
- Overrides:
clone
in classConfigurable
-
loadBuiltInEncodingMap
public void loadBuiltInEncodingMap()
Loads a preset language-to-encoding map, similarly as if you have calledclearEncodingMap()
and then did multiplesetEncoding(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
-
clearEncodingMap
public void clearEncodingMap()
Clears language-to-encoding map.
-
getDefaultConfiguration
public static Configuration getDefaultConfiguration()
Deprecated.The usage of the static singleton (the "default")Configuration
instance can easily cause erroneous, unpredictable behavior. This is because multiple independent software components may use FreeMarker internally inside the same application, so they will interfere because of the commonConfiguration
instance. Each such component should use its own privateConfiguration
object instead, that it typically creates withnew Configuration()
when the component is initialized.Returns the default (singleton) Configuration object. Note that you can create as many separate configurations as you wish; this global instance is provided for convenience, or when you have no reason to use a separate instance.
-
setDefaultConfiguration
public static void setDefaultConfiguration(Configuration config)
Deprecated.Using the "default"Configuration
instance can easily lead to erroneous, unpredictable behaviour. See morehere...
.Sets the Configuration object that will be retrieved from future calls togetDefaultConfiguration()
.
-
setTemplateLoader
public void setTemplateLoader(TemplateLoader templateLoader)
Sets aTemplateLoader
that is used to look up and load templates; as a side effect the template cache will be emptied. By providing your ownTemplateLoader
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)
, andsetServletContextForTemplateLoading(Object, String)
.You can chain several
TemplateLoader
-s together withMultiTemplateLoader
.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 isnull
.)
-
unsetTemplateLoader
public void unsetTemplateLoader()
Resets the setting to its default, as it was never set. This means that when you change theincompatibe_improvements
setting later, the default will also change as appropriate. AlsoisTemplateLoaderExplicitlySet()
will returnfalse
.- Since:
- 2.3.22
-
isTemplateLoaderExplicitlySet
public boolean isTemplateLoaderExplicitlySet()
Tells ifsetTemplateLoader(TemplateLoader)
(or equivalent) was already called on this instance.- Since:
- 2.3.22
-
getTemplateLoader
public TemplateLoader getTemplateLoader()
The getter pair ofsetTemplateLoader(TemplateLoader)
.
-
setTemplateLookupStrategy
public void setTemplateLookupStrategy(TemplateLookupStrategy templateLookupStrategy)
Sets aTemplateLookupStrategy
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 isTemplateLookupStrategy.DEFAULT_2_3_0
.- Since:
- 2.3.22
-
unsetTemplateLookupStrategy
public void unsetTemplateLookupStrategy()
Resets the setting to its default, as it was never set. This means that when you change theincompatibe_improvements
setting later, the default will also change as appropriate. AlsoisTemplateLookupStrategyExplicitlySet()
will returnfalse
.- Since:
- 2.3.22
-
isTemplateLookupStrategyExplicitlySet
public boolean isTemplateLookupStrategyExplicitlySet()
Tells ifsetTemplateLookupStrategy(TemplateLookupStrategy)
(or equivalent) was already called on this instance.- Since:
- 2.3.22
-
getTemplateLookupStrategy
public TemplateLookupStrategy getTemplateLookupStrategy()
The getter pair ofsetTemplateLookupStrategy(TemplateLookupStrategy)
.
-
setTemplateNameFormat
public void setTemplateNameFormat(TemplateNameFormat templateNameFormat)
Sets the template name format used. The default isTemplateNameFormat.DEFAULT_2_3_0
, while the recommended value for new projects isTemplateNameFormat.DEFAULT_2_4_0
.- Since:
- 2.3.22
-
unsetTemplateNameFormat
public void unsetTemplateNameFormat()
Resets the setting to its default, as it was never set. This means that when you change theincompatibe_improvements
setting later, the default will also change as appropriate. AlsoisTemplateNameFormatExplicitlySet()
will returnfalse
.- Since:
- 2.3.22
-
isTemplateNameFormatExplicitlySet
public boolean isTemplateNameFormatExplicitlySet()
Tells ifsetTemplateNameFormat(TemplateNameFormat)
(or equivalent) was already called on this instance.- Since:
- 2.3.22
-
getTemplateNameFormat
public TemplateNameFormat getTemplateNameFormat()
The getter pair ofsetTemplateNameFormat(TemplateNameFormat)
.
-
setCacheStorage
public void setCacheStorage(CacheStorage cacheStorage)
Sets theCacheStorage
used for cachingTemplate
-s; the earlier content of the template cache will be dropt. The default is aSoftCacheStorage
. If the total size of theTemplate
objects is significant but most templates are used rarely, using aMruCacheStorage
instead might be advisable. If you don't want caching at all, useNullCacheStorage
(you can't usenull
).Note that setting the cache storage will re-create the template cache, so all its content will be lost.
-
unsetCacheStorage
public void unsetCacheStorage()
Resets the setting to its default, as it was never set. This means that when you change theincompatibe_improvements
setting later, the default will also change as appropriate. AlsoisCacheStorageExplicitlySet()
will returnfalse
.- Since:
- 2.3.22
-
isCacheStorageExplicitlySet
public boolean isCacheStorageExplicitlySet()
Tells ifsetCacheStorage(CacheStorage)
(or equivalent) was already called on this instance.- Since:
- 2.3.22
-
getCacheStorage
public CacheStorage getCacheStorage()
The getter pair ofsetCacheStorage(CacheStorage)
.- Since:
- 2.3.20
-
setDirectoryForTemplateLoading
public void setDirectoryForTemplateLoading(File dir) throws IOException
Sets the file system directory from which to load templates. This is equivalent tosetTemplateLoader(new FileTemplateLoader(dir))
, so seeFileTemplateLoader(File)
for more details. Note that FreeMarker can load templates from non-file-system sources too. SeesetTemplateLoader(TemplateLoader)
from more details.- Throws:
IOException
-
setServletContextForTemplateLoading
public void setServletContextForTemplateLoading(Object servletContext, String path)
Sets the servlet context from which to load templates. This is equivalent tosetTemplateLoader(new WebappTemplateLoader(sctxt, path))
orsetTemplateLoader(new WebappTemplateLoader(sctxt))
ifpath
wasnull
, so seefreemarker.cache.WebappTemplateLoader
for more details.- Parameters:
servletContext
- thejavax.servlet.ServletContext
object. (The declared type isObject
to prevent class loading error when using FreeMarker in an environment where there's no servlet classes available.)path
- the path relative to the ServletContext.- See Also:
setTemplateLoader(TemplateLoader)
-
setClassForTemplateLoading
public void setClassForTemplateLoading(Class resourceLoaderClass, String basePackagePath)
Sets the class whoseClass.getResource(String)
method will be used to load templates, from the inside the package specified. SeeClassTemplateLoader(Class, String)
for more details.- Parameters:
basePackagePath
- Separate steps with"/"
, not"."
, and note that it matters if this starts with/
or not. SeeClassTemplateLoader(Class, String)
for more details.- See Also:
setClassLoaderForTemplateLoading(ClassLoader, String)
,setTemplateLoader(TemplateLoader)
-
setClassLoaderForTemplateLoading
public void setClassLoaderForTemplateLoading(ClassLoader classLoader, String basePackagePath)
Sets theClassLoader
whoseClassLoader.getResource(String)
method will be used to load templates, from the inside the package specified. SeeClassTemplateLoader(Class, String)
for more details.- Parameters:
basePackagePath
- Separate steps with"/"
, not"."
. SeeClassTemplateLoader(Class, String)
for more details.- Since:
- 2.3.22
- See Also:
setClassForTemplateLoading(Class, String)
,setTemplateLoader(TemplateLoader)
-
setTemplateUpdateDelay
public void setTemplateUpdateDelay(int seconds)
Deprecated.UsesetTemplateUpdateDelayMilliseconds(long)
instead, because the time granularity of this method is often misunderstood to be milliseconds.Sets the time in seconds that must elapse before checking whether there is a newer version of a template "file" than the cached one.Historical note: Despite what the API documentation said earlier, this method is not thread-safe. While it works well on most hardware, it's not guaranteed that FreeMarker will see the update in all threads, and theoretically it's also possible that it will see a value that's a binary mixture of the new and the old one.
-
setTemplateUpdateDelayMilliseconds
public void setTemplateUpdateDelayMilliseconds(long millis)
Sets the time in milliseconds that must elapse before checking whether there is a newer version of a template "file" exists than the cached one. Defaults to 5000 ms.When you get a template via
getTemplate(String)
(or some of its overloads). FreeMarker will try to get the template from the template cache. If the template is found, and at least this amount of time was elapsed since the template last modification date was checked, FreeMarker will re-check the last modification date (this could mean I/O), possibly reloading the template and updating the cache as a consequence (can mean even more I/O). ThegetTemplate(String)
(or some of its overloads) call will only return after this all is done, so it will return the fresh template.- Since:
- 2.3.23
-
getTemplateUpdateDelayMilliseconds
public long getTemplateUpdateDelayMilliseconds()
The getter pair ofsetTemplateUpdateDelayMilliseconds(long)
.- Since:
- 2.3.23
-
setStrictSyntaxMode
public void setStrictSyntaxMode(boolean b)
Deprecated.Onlytrue
(the default) value will be supported sometimes in the future.Sets whether directives such asif
,else
, etc must be written as#if
,#else
, etc. Defaults totrue
.When this is
true
, any tag not starting with <# or </# or <@ or </@ is considered as plain text and will go to the output as is. Tag starting with <# or </# must be valid FTL tag, or else the template is invalid (i.e. <#noSuchDirective> is an error).
-
setObjectWrapper
public void setObjectWrapper(ObjectWrapper objectWrapper)
Description copied from class:Configurable
Sets the object wrapper used to wrap objects toTemplateModel
-s. The default isObjectWrapper.DEFAULT_WRAPPER
.- Overrides:
setObjectWrapper
in classConfigurable
-
unsetObjectWrapper
public void unsetObjectWrapper()
Resets the setting to its default, as it was never set. This means that when you change theincompatibe_improvements
setting later, the default will also change as appropriate. AlsoisObjectWrapperExplicitlySet()
will returnfalse
.- Since:
- 2.3.22
-
isObjectWrapperExplicitlySet
public boolean isObjectWrapperExplicitlySet()
Tells ifsetObjectWrapper(ObjectWrapper)
(or equivalent) was already called on this instance.- Since:
- 2.3.22
-
setTemplateExceptionHandler
public void setTemplateExceptionHandler(TemplateExceptionHandler templateExceptionHandler)
Description copied from class:Configurable
Sets the exception handler used to handle exceptions occurring inside templates. The default isTemplateExceptionHandler.DEBUG_HANDLER
. The recommended values are:- In production systems:
TemplateExceptionHandler.RETHROW_HANDLER
- During development of HTML templates:
TemplateExceptionHandler.HTML_DEBUG_HANDLER
- During development of non-HTML templates:
TemplateExceptionHandler.DEBUG_HANDLER
All of these will let the exception propagate further, so that you can catch it around
Template.process(Object, Writer)
for example. The difference is in what they print on the output before they do that.Note that the
TemplateExceptionHandler
is not meant to be used for generating HTTP error pages. Neither is it meant to be used to roll back the printed output. These should be solved outside template processing when the exception raises fromTemplate.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.- Overrides:
setTemplateExceptionHandler
in classConfigurable
- In production systems:
-
unsetTemplateExceptionHandler
public void unsetTemplateExceptionHandler()
Resets the setting to its default, as it was never set. This means that when you change theincompatibe_improvements
setting later, the default will also change as appropriate. AlsoisTemplateExceptionHandlerExplicitlySet()
will returnfalse
.- Since:
- 2.3.22
-
isTemplateExceptionHandlerExplicitlySet
public boolean isTemplateExceptionHandlerExplicitlySet()
Tells ifsetTemplateExceptionHandler(TemplateExceptionHandler)
(or equivalent) was already called on this instance.- Since:
- 2.3.22
-
setLogTemplateExceptions
public void setLogTemplateExceptions(boolean value)
Description copied from class:Configurable
Specifies ifTemplateException
-s thrown by template processing are logged by FreeMarker or not. The default istrue
for backward compatibility, but that results in logging the exception twice in properly written applications, because there theTemplateException
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 tofalse
. Note that this setting has no effect on the logging of exceptions caught by#attempt
; those are always logged, no mater what (because those exceptions won't bubble up until the API caller).- Overrides:
setLogTemplateExceptions
in classConfigurable
- Since:
- 2.3.22
-
unsetLogTemplateExceptions
public void unsetLogTemplateExceptions()
Resets the setting to its default, as it was never set. This means that when you change theincompatibe_improvements
setting later, the default will also change as appropriate. AlsoisTemplateExceptionHandlerExplicitlySet()
will returnfalse
.- Since:
- 2.3.22
-
isLogTemplateExceptionsExplicitlySet
public boolean isLogTemplateExceptionsExplicitlySet()
Tells ifsetLogTemplateExceptions(boolean)
(or equivalent) was already called on this instance.- Since:
- 2.3.22
-
getStrictSyntaxMode
public boolean getStrictSyntaxMode()
The getter pair ofsetStrictSyntaxMode(boolean)
.
-
setIncompatibleImprovements
public void setIncompatibleImprovements(Version incompatibleImprovements)
UseConfiguration(Version)
instead if possible; see the meaning of the parameter there. If the default value of a setting depends on theincompatibleImprovements
and the value of that setting was never set in thisConfiguration
object through the public API, its value will be set to the default value appropriate for the newincompatibleImprovements
. (This adjustment of a setting value doesn't count as setting that setting, so settingincompatibleImprovements
for multiple times also works as expected.) Note that if thetemplate_loader
have to be changed because of this, the template cache will be emptied.- Throws:
IllegalArgumentException
- IfincompatibleImmprovements
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 isnull
.- Since:
- 2.3.20
-
getIncompatibleImprovements
public Version getIncompatibleImprovements()
- Returns:
- Never
null
. - Since:
- 2.3.20
- See Also:
setIncompatibleImprovements(Version)
-
setIncompatibleEnhancements
public void setIncompatibleEnhancements(String version)
Deprecated.UseConfiguration(Version)
, or as last chance,setIncompatibleImprovements(Version)
instead.
-
getIncompatibleEnhancements
public String getIncompatibleEnhancements()
Deprecated.UsegetIncompatibleImprovements()
instead.
-
getParsedIncompatibleEnhancements
public int getParsedIncompatibleEnhancements()
Deprecated.UsegetIncompatibleImprovements()
instead.
-
setWhitespaceStripping
public void setWhitespaceStripping(boolean b)
Sets whether the FTL parser will try to remove superfluous white-space around certain FTL tags.
-
getWhitespaceStripping
public boolean getWhitespaceStripping()
Gets whether the FTL parser will try to remove superfluous white-space around certain FTL tags.- See Also:
setWhitespaceStripping(boolean)
-
setTagSyntax
public void setTagSyntax(int tagSyntax)
Determines the syntax of the template files (angle bracket VS square bracket) that has no#ftl
in it. ThetagSyntax
parameter must be one of:AUTO_DETECT_TAG_SYNTAX
: use the syntax of the first FreeMarker tag (can be anything, like #list, #include, user defined, etc.)ANGLE_BRACKET_TAG_SYNTAX
: use the angle bracket syntax (the normal syntax)SQUARE_BRACKET_TAG_SYNTAX
: use the square bracket syntax
In FreeMarker 2.3.x
ANGLE_BRACKET_TAG_SYNTAX
is the default for better backward compatibility. Starting from 2.4.xAUTO_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 theftl
directive determines the syntax.
-
getTagSyntax
public int getTagSyntax()
The getter pair ofsetTagSyntax(int)
.
-
setNamingConvention
public void setNamingConvention(int namingConvention)
Sets the naming convention used for the identifiers that are part of the template language. The available naming conventions are legacy (directive (tag) names are all-lower-caselikethis
, others are snake caselike_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
VSelseif
), 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 fors?upperCase
ors?upper_case
it's relevant, but fors?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 theLEGACY_NAMING_CONVENTION
syntax, regardless of this setting. As they aren't exempt from the naming convention consistency enforcement, generally, you can't use strictCAMEL_CASE_NAMING_CONVENTION
tags mixed with non-strict tags.- Parameters:
namingConvention
- One of theAUTO_DETECT_NAMING_CONVENTION
orLEGACY_NAMING_CONVENTION
CAMEL_CASE_NAMING_CONVENTION
.- Throws:
IllegalArgumentException
- If the parameter isn't one of the valid constants.- Since:
- 2.3.23
-
getNamingConvention
public int getNamingConvention()
The getter pair ofsetNamingConvention(int)
.- Since:
- 2.3.23
-
getTemplate
public Template getTemplate(String name) throws TemplateNotFoundException, MalformedTemplateNameException, ParseException, IOException
Retrieves the template with the given name from the template cache, loading it into the cache first if it's missing/staled.This is a shorthand for
getTemplate(name, null, null, null, true, false)
; see more details there.See
Configuration
for an example of basic usage.
-
getTemplate
public Template getTemplate(String name, Locale locale) throws TemplateNotFoundException, MalformedTemplateNameException, ParseException, IOException
Shorthand forgetTemplate(name, locale, null, null, true, false)
.
-
getTemplate
public Template getTemplate(String name, String encoding) throws TemplateNotFoundException, MalformedTemplateNameException, ParseException, IOException
Shorthand forgetTemplate(name, null, null, encoding, true, false)
.
-
getTemplate
public Template getTemplate(String name, Locale locale, String encoding) throws TemplateNotFoundException, MalformedTemplateNameException, ParseException, IOException
Shorthand forgetTemplate(name, locale, null, encoding, true, false)
.
-
getTemplate
public Template getTemplate(String name, Locale locale, String encoding, boolean parseAsFTL) throws TemplateNotFoundException, MalformedTemplateNameException, ParseException, IOException
Shorthand forgetTemplate(name, locale, null, encoding, parseAsFTL, false)
.
-
getTemplate
public Template getTemplate(String name, Locale locale, String encoding, boolean parseAsFTL, boolean ignoreMissing) throws TemplateNotFoundException, MalformedTemplateNameException, ParseException, IOException
- Throws:
TemplateNotFoundException
MalformedTemplateNameException
ParseException
IOException
- Since:
- 2.3.21
-
getTemplate
public Template getTemplate(String name, Locale locale, Object customLookupCondition, String encoding, boolean parseAsFTL, boolean ignoreMissing) throws TemplateNotFoundException, MalformedTemplateNameException, ParseException, IOException
Retrieves the template with the given name (and according the specified further parameters) from the template cache, loading it into the cache first if it's missing/staled.This method is thread-safe.
See
Configuration
for an example of basic usage.- Parameters:
name
- The name or path of the template, which is not a real path, but interpreted inside the currentTemplateLoader
. Can't benull
. The exact syntax of the name depends on the underlyingTemplateLoader
, 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 isa/../b/./c.ftl
, then it will be simplified tob/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 whatConfigurable.getLocale()
on the resultingTemplate
will return. This parameter can benull
since 2.3.22, in which case it defaults toConfigurable.getLocale()
(note thatConfigurable.getLocale()
will give the default value, notnull
). This parameter also drives localized template lookup. Assuming that you have specifieden_US
as the locale andmyTemplate.ftl
as the name of the template, and the defaultTemplateLookupStrategy
is used and#setLocalizedLookup(boolean) localized_lookup
istrue
, FreeMarker will first try to retrievemyTemplate_en_US.html
, thenmyTemplate.en.ftl
, and finallymyTemplate.ftl
. Note that that the template's locale will been_US
even if it only findsmyTemplate.ftl
.customLookupCondition
- This value can be used by a customTemplateLookupStrategy
; has no effect with the default one. Can benull
(though it's up to the customTemplateLookupStrategy
if it allows that). This object will be used as part of the cache key, so it must to have a properObject.equals(Object)
andObject.hashCode()
method. It also should have reasonableObject.toString()
, as it's possibly quoted in error messages. The expected type is up to the customTemplateLookupStrategy
. See also:TemplateLookupContext.getCustomLookupCondition()
.encoding
- The charset used to interpret the template source code bytes (if it's read from a binary source). Can benull
since 2.3.22, will default togetEncoding(Locale)
whereLocale
is thelocale
parameter (whenlocale
wasnull
too, the its default value is used instead).parseAsFTL
- Iftrue
, the loaded template is parsed and interpreted normally, as a regular FreeMarker template. Iffalse
, the loaded template is treated as a static text, so${...}
,<#...>
etc. will not have special meaning in it.ignoreMissing
- Iftrue
, the method won't throwTemplateNotFoundException
if the template doesn't exist, instead it returnsnull
. Other kind of exceptions won't be suppressed.- Returns:
- the requested template; maybe
null
when theignoreMissing
parameter istrue
. - Throws:
TemplateNotFoundException
- If the template could not be found. Note that this exception extendsIOException
.MalformedTemplateNameException
- If the template name given was in violation with theTemplateNameFormat
in use. Note that this exception extendsIOException
.ParseException
- (extendsIOException
) if the template is syntactically bad. Note that this exception extendsIOException
.IOException
- If there was some other problem with reading the template "file". Note that the other exceptions extendIOException
, so this should be catched the last.- Since:
- 2.3.22
-
setDefaultEncoding
public void setDefaultEncoding(String encoding)
Sets the charset used for decoding byte sequences to character sequences when reading template files in a locale for which no explicit encoding was specified viasetEncoding(Locale, String)
. Note that by default there is no locale specified for any locale, so the default encoding is always in effect.Defaults to the default system encoding, which can change from one server to another, so you should always set this setting. If you don't know what charset your should chose,
"UTF-8"
is usually a good choice.Note that individual templates may specify their own charset by starting with <#ftl encoding="...">
- Parameters:
encoding
- The name of the charset, such as"UTF-8"
or"ISO-8859-1"
-
getDefaultEncoding
public String getDefaultEncoding()
Gets the default encoding for converting bytes to characters when reading template files in a locale for which no explicit encoding was specified. Defaults to the default system encoding.
-
getEncoding
public String getEncoding(Locale locale)
Gets the preferred character encoding for the given locale, or the default encoding if no encoding is set explicitly for the specified locale. You can associate encodings with locales usingsetEncoding(Locale, String)
orloadBuiltInEncodingMap()
.
-
setEncoding
public void setEncoding(Locale locale, String encoding)
Sets the character set encoding to use for templates of a given locale. If there is no explicit encoding set for some locale, then the default encoding will be used, what you can set withsetDefaultEncoding(java.lang.String)
.- See Also:
clearEncodingMap()
,loadBuiltInEncodingMap()
-
setSharedVariable
public void setSharedVariable(String name, TemplateModel tm)
Adds a shared variable to the configuration. Shared sharedVariables are sharedVariables that are visible as top-level sharedVariables for all templates which use this configuration, if the data model does not contain a variable with the same name.Never use TemplateModel implementation that is not thread-safe for shared sharedVariables, if the configuration is used by multiple threads! It is the typical situation for Servlet based Web sites.
This method is not thread safe; use it with the same restrictions as those that modify setting values.
- Parameters:
name
- the name used to access the data object from your template. If a shared variable with this name already exists, it will replace that.- See Also:
setAllSharedVariables(freemarker.template.TemplateHashModelEx)
,setSharedVariable(String,Object)
-
getSharedVariableNames
public Set getSharedVariableNames()
Returns the set containing the names of all defined shared sharedVariables. The method returns a new Set object on each call that is completely disconnected from the Configuration. That is, modifying the set will have no effect on the Configuration object.
-
setSharedVariable
public void setSharedVariable(String name, Object value) throws TemplateModelException
Adds shared variable to the configuration; It usesConfigurable.getObjectWrapper()
to wrap thevalue
, so it's important that the object wrapper is set before this.This method is not thread safe; use it with the same restrictions as those that modify setting values.
The added value should be thread safe, if you are running templates from multiple threads with this configuration.
- Throws:
TemplateModelException
- If some of the variables couldn't be wrapped viaConfigurable.getObjectWrapper()
.- See Also:
setSharedVaribles(Map)
,setSharedVariable(String,TemplateModel)
,setAllSharedVariables(TemplateHashModelEx)
-
setSharedVaribles
public void setSharedVaribles(Map map) throws TemplateModelException
Replaces all shared variables (removes all previously added ones).The values in the map can be
TemplateModel
-s or plain Java objects which will be immediately converted toTemplateModel
with theObjectWrapper
returned byConfigurable.getObjectWrapper()
. IfsetObjectWrapper(ObjectWrapper)
is called later, this conversion will be re-applied. Thus, ignoring some extra resource usage, it doesn't mater if in what order aresetObjectWrapper(ObjectWrapper)
andsetSharedVaribles(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 theObjectWrapper
must be thread safe. (The standardObjectWrapper
-s of FreeMarker create thread safeTemplateModel
-s.) TheMap
itself need not be thread-safe.This setter method has no getter pair because of the tricky relation ship with
setSharedVariable(String, Object)
.- Throws:
TemplateModelException
- If some of the variables couldn't be wrapped viaConfigurable.getObjectWrapper()
.- Since:
- 2.3.21
-
setAllSharedVariables
public void setAllSharedVariables(TemplateHashModelEx hash) throws TemplateModelException
Adds all object in the hash as shared variable to the configuration; it's like doing severalsetSharedVariable(String, Object)
calls, one for each hash entry. It doesn't remove the already added shared variable before doing this.Never use TemplateModel implementation that is not thread-safe for shared shared variable values, if the configuration is used by multiple threads! It is the typical situation for Servlet based Web sites.
This method is not thread safe; use it with the same restrictions as those that modify setting values.
- Parameters:
hash
- a hash model whose objects will be copied to the configuration with same names as they are given in the hash. If a shared variable with these names already exist, it will be replaced with those from the map.- Throws:
TemplateModelException
- See Also:
setSharedVaribles(Map)
,setSharedVariable(String,Object)
,setSharedVariable(String,TemplateModel)
-
getSharedVariable
public TemplateModel getSharedVariable(String name)
Gets a shared variable. Shared sharedVariables are sharedVariables that are available to all templates. When a template is processed, and an identifier is undefined in the data model, a shared variable object with the same identifier is then looked up in the configuration. There are several predefined sharedVariables that are always available through this method, see the FreeMarker manual for a comprehensive list of them.
-
clearSharedVariables
public void clearSharedVariables()
Removes all shared sharedVariables, except the predefined ones (compress, html_escape, etc.).
-
clearTemplateCache
public void clearTemplateCache()
Removes all entries from the template cache, thus forcing reloading of templates on subsequentgetTemplate
calls.This method is thread-safe and can be called while the engine processes templates.
-
removeTemplateFromCache
public void removeTemplateFromCache(String name) throws IOException
Equivalent to removeTemplateFromCache(name, thisCfg.getLocale(), thisCfg.getEncoding(thisCfg.getLocale()), true).- Throws:
IOException
- Since:
- 2.3.19
-
removeTemplateFromCache
public void removeTemplateFromCache(String name, Locale locale) throws IOException
Equivalent to removeTemplateFromCache(name, locale, thisCfg.getEncoding(locale), true).- Throws:
IOException
- Since:
- 2.3.19
-
removeTemplateFromCache
public void removeTemplateFromCache(String name, String encoding) throws IOException
Equivalent to removeTemplateFromCache(name, thisCfg.getLocale(), encoding, true).- Throws:
IOException
- Since:
- 2.3.19
-
removeTemplateFromCache
public void removeTemplateFromCache(String name, Locale locale, String encoding) throws IOException
Equivalent to removeTemplateFromCache(name, locale, encoding, true).- Throws:
IOException
- Since:
- 2.3.19
-
removeTemplateFromCache
public void removeTemplateFromCache(String name, Locale locale, String encoding, boolean parse) throws IOException
Removes a template from the template cache, hence forcing the re-loading of it when it's next time requested. This is to give the application finer control over cache updating thansetTemplateUpdateDelay(int)
alone does.For the meaning of the parameters, see
getTemplate(String, Locale, String, boolean)
.This method is thread-safe and can be called while the engine processes templates.
- Throws:
IOException
- Since:
- 2.3.19
-
getLocalizedLookup
public boolean getLocalizedLookup()
The getter pair ofsetLocalizedLookup(boolean)
.This method is thread-safe and can be called while the engine works.
-
setLocalizedLookup
public void setLocalizedLookup(boolean localizedLookup)
Enables/disables localized template lookup. Enabled by default.With the default
TemplateLookupStrategy
, localized lookup works like this: Let's say your locale setting isLocale("en", "AU")
, and you callcfg.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 atsetTemplateLookupStrategy(TemplateLookupStrategy)
for a more details. If you need to generate different template names, usesetTemplateLookupStrategy(TemplateLookupStrategy)
with your customTemplateLookupStrategy
.Note that changing the value of this setting causes the template cache to be emptied so that old lookup results won't be reused (since 2.3.22).
Historical note: Despite what the API documentation said earlier, this method is not thread-safe. While setting it can't cause any serious problems, and in fact it works well on most hardware, it's not guaranteed that FreeMarker will see the update in all threads.
-
setSetting
public void setSetting(String name, String value) throws TemplateException
Description copied from class:Configurable
Sets a FreeMarker setting by a name and string value. If you can configure FreeMarker directly with Java (or other programming language), you should use the dedicated setter methods instead (likeConfigurable.setObjectWrapper(ObjectWrapper)
. This meant to be used if you get the settings from somewhere as text. Regardless, below you will find an overview of the settings available no matter how you set them.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 usedateFormat
. 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"
: SeeConfigurable.setLocale(Locale)
.
String value: local codes with the usual format in Java, such as"en_US"
."classic_compatible"
: SeeConfigurable.setClassicCompatible(boolean)
andConfigurable.setClassicCompatibleAsInt(int)
.
String value:"true"
,"false"
, also since 2.3.200
or1
or2
. (Also accepts"yes"
,"no"
,"t"
,"f"
,"y"
,"n"
.) Case insensitive."template_exception_handler"
: SeeConfigurable.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"
(meansTemplateExceptionHandler.RETHROW_HANDLER
),"debug"
(meansTemplateExceptionHandler.DEBUG_HANDLER
),"html_debug"
(meansTemplateExceptionHandler.HTML_DEBUG_HANDLER
),"ignore"
(meansTemplateExceptionHandler.IGNORE_HANDLER
),"default"
(only allowed forConfiguration
instances) for the default."arithmetic_engine"
: SeeConfigurable.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"
: SeeConfigurable.setObjectWrapper(ObjectWrapper)
.
String value: If the value contains dot, then it's interpreted as an object builder expression, with the addition thatBeansWrapper
,DefaultObjectWrapper
andSimpleObjectWrapper
can be referred without package name. For example, these strings are valid values:"DefaultObjectWrapper(2.3.21)"
,"BeansWrapper(2.3.21, simpleMapWrapper=true)"
.
If the value does not contain dot, then it must be one of these special values (case insensitive):"default"
means the default ofConfiguration
(the default depends on theConfiguration#Configuration(Version) incompatible_improvements
, but a bug existed in 2.3.21 where that was ignored),"default_2_3_0"
(means the deprecatedObjectWrapper.DEFAULT_WRAPPER
)"simple"
(means the deprecatedObjectWrapper.SIMPLE_WRAPPER
),"beans"
(means the deprecatedObjectWrapper.BEANS_WRAPPER
orBeansWrapperBuilder.build()
),"jython"
(meansObjectWrapper.DEFAULT_WRAPPER
)"number_format"
: SeeConfigurable.setNumberFormat(String)
."boolean_format"
: SeeConfigurable.setBooleanFormat(String)
."date_format", "time_format", "datetime_format"
: SeeConfigurable.setDateFormat(String)
,Configurable.setTimeFormat(String)
,Configurable.setDateTimeFormat(String)
."time_zone"
: SeeConfigurable.setTimeZone(TimeZone)
.
String value: With the format asTimeZone.getTimeZone(java.lang.String)
defines it. Also, since 2.3.21"JVM default"
can be used that will be replaced with the actual JVM default time zone whenConfigurable.setSetting(String, String)
is called. For example"GMT-8:00"
or"America/Los_Angeles"
If you set this setting, consider settingsql_date_and_time_time_zone
too (see below)!sql_date_and_time_time_zone
: SeeConfigurable.setSQLDateAndTimeTimeZone(TimeZone)
. Since 2.3.21.
String value: With the format asTimeZone.getTimeZone(java.lang.String)
defines it. Also,"JVM default"
can be used that will be replaced with the actual JVM default time zone whenConfigurable.setSetting(String, String)
is called. Also"null"
can be used, which has the same effect assetSQLDateAndTimeTimeZone(null)
."output_encoding"
: SeeConfigurable.setOutputEncoding(String)
."url_escaping_charset"
: SeeConfigurable.setURLEscapingCharset(String)
."auto_flush"
: SeeConfigurable.setAutoFlush(boolean)
. Since 2.3.17.
String value:"true"
,"false"
,"y"
, etc."new_builtin_class_resolver"
: SeeConfigurable.setNewBuiltinClassResolver(TemplateClassResolver)
. Since 2.3.17. The value must be one of these (ignore the quotation marks):"unrestricted"
: UseTemplateClassResolver.UNRESTRICTED_RESOLVER
"safer"
: UseTemplateClassResolver.SAFER_RESOLVER
"allows_nothing"
: UseTemplateClassResolver.ALLOWS_NOTHING_RESOLVER
Something that contains colon will use
OptInTemplateClassResolver
and is expected to store comma separated values (possibly quoted) segmented with"allowed_classes:"
and/or"trusted_templates:"
. Examples of valid values:Setting value Meaning allowed_classes: com.example.C1, com.example.C2, trusted_templates: lib/*, safe.ftl
Only allow instantiating the com.example.C1
andcom.example.C2
classes. But, allow templates within thelib/
directory (likelib/foo/bar.ftl
) and templatesafe.ftl
(that does not matchfoo/safe.ftl
, only exactlysafe.ftl
) to instantiate anything thatTemplateClassResolver.SAFER_RESOLVER
allows.allowed_classes: com.example.C1, com.example.C2
Only allow instantiating the com.example.C1
andcom.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 templatesafe.ftl
.For more details see
OptInTemplateClassResolver
.Otherwise if the value contains dot, it's interpreted as an object builder expression.
"show_error_tips"
: SeeConfigurable.setShowErrorTips(boolean)
. Since 2.3.21.
String value:"true"
,"false"
,"y"
, etc.api_builtin_enabled
: SeeConfigurable.setAPIBuiltinEnabled(boolean)
. Since 2.3.22.
String value:"true"
,"false"
,"y"
, etc.
Configuration
(a subclass ofConfigurable
) also understands these:"auto_import"
: SeesetAutoImports(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. SeesetAutoIncludes(List)
String value is something like:/include/common.ftl, "/include/evil name.ftl"
"default_encoding"
: SeesetDefaultEncoding(String)
.
As the default value is the system default, which can change from one server to another, you should always set this!"localized_lookup"
: SeesetLocalizedLookup(boolean)
.
String value:"true"
,"false"
(also the equivalents:"yes"
,"no"
,"t"
,"f"
,"y"
,"n"
). Case insensitive."strict_syntax"
: SeesetStrictSyntaxMode(boolean)
. Deprecated.
String value:"true"
,"false"
,yes
, etc."whitespace_stripping"
: SeesetWhitespaceStripping(boolean)
.
String value:"true"
,"false"
,yes
, etc."cache_storage"
: SeesetCacheStorage(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 aMruCacheStorage
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; seesetTemplateUpdateDelayMilliseconds(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"
: SeesetTagSyntax(int)
.
String value: Must be one of"auto_detect"
,"angle_bracket"
, and"square_bracket"
."naming_convention"
: SeesetNamingConvention(int)
.
String value: Must be one of"auto_detect"
,"legacy"
, and"camel_case"
."incompatible_improvements"
: SeesetIncompatibleImprovements(Version)
.
String value: version number like2.3.20
."incompatible_enhancements"
: See:setIncompatibleEnhancements(String)
. This setting name is deprecated, use"incompatible_improvements"
instead."template_loader"
: See:setTemplateLoader(TemplateLoader)
.
String value:"default"
(case insensitive) for the default, or else interpreted as an object builder expression."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"
forTemplateNameFormat.DEFAULT_2_3_0
,"default_2_4_0"
forTemplateNameFormat.DEFAULT_2_4_0
.
Regarding object builder expressions (used by the setting values where it was indicated):
Before FreeMarker 2.3.21 it had to be a fully qualified class name, and nothing else.
Since 2.3.21, the generic syntax is: className(constrArg1, constrArg2, ... constrArgN, propName1=propValue1, propName2=propValue2, ... propNameN=propValueN), where className is the fully qualified class name of the instance to create (except if we have builder class or INSTANCE field around, but see that later), constrArg-s are the values of constructor arguments, and propName=propValue-s set JavaBean properties (like x=1 means setX(1)) on the created instance. You can have any number of constructor arguments and property setters, including 0. Constructor arguments must precede any property setters.
- Example: com.example.MyObjectWrapper(1, 2, exposeFields=true, cacheSize=5000) is nearly equivalent with this Java code: obj = new com.example.MyObjectWrapper(1, 2); obj.setExposeFields(true); obj.setCacheSize(5000);
-
If you have no constructor arguments and property setters, and the className class has a public static
INSTANCE
field, the value of that filed will be the value of the expression, and the constructor won't be called. Note that if you use the backward compatible syntax, where these's no parenthesis after the class name, then it will not look forINSTANCE
. -
If there exists a class named classNameBuilder, then that class will be instantiated instead with the given constructor arguments, and the JavaBean properties of that builder instance will be set. After that, the public build() method of the instance will be called, whose return value will be the value of the whole expression. (The builder class and the build() method is simply found by name, there's no special interface to implement.) Note that if you use the backward compatible syntax, where these's no parenthesis after the class name, then it will not look for builder class.
-
Currently, the values of arguments and properties can only be one of these:
- A numerical literal, like
123
or-1.5
. Like in FTL, there are no numerical types, the value will be automatically converted to the type of the target. - A boolean literal:
true
orfalse
- The null literal:
null
- A string literal with FTL syntax, except that it can't contain ${...}-s and
#{...}-s. Examples:
"Line 1\nLine 2"
orr"C:\temp"
. - An object builder expression. That is, object builder expressions can be nested into each other.
- A numerical literal, like
-
The top-level object builder expressions may omit
()
. In that case, for backward compatibility, theINSTANCE
field and the builder class is not searched, so the instance will be always created with its parameterless constructor. (This behavior will possibly change in 2.4.) The()
can't be omitted for nested expressions. -
The classes and methods that the expression meant to access must be all public.
- Overrides:
setSetting
in classConfigurable
- Parameters:
name
- the name of the setting.value
- the string that describes the new value of the setting.- Throws:
Configurable.UnknownSettingException
- if the name is wrong.TemplateException
- if the new value of the setting can't be set for any other reasons.
-
getCorrectedNameForUnknownSetting
protected String getCorrectedNameForUnknownSetting(String name)
- Overrides:
getCorrectedNameForUnknownSetting
in classConfigurable
- Parameters:
name
- The wrong name- Returns:
- The corrected name, or
null
if there's no known correction
-
addAutoImport
public void addAutoImport(String namespaceVarName, String templateName)
Adds an invisible#import templateName as namespaceVarName
at the beginning of all templates. The order of the imports will be the same as the order in which they were added with this method.
-
removeAutoImport
public void removeAutoImport(String namespaceVarName)
Removes an auto-import; seeaddAutoImport(String, String)
. Does nothing if the auto-import doesn't exist.
-
setAutoImports
public void setAutoImports(Map map)
Removes all auto-imports, then callsaddAutoImport(String, String)
for eachMap
-entry (the entry key is thenamespaceVarName
). The order of the auto-imports will be the same asMap.keySet()
returns the keys, thus, it's not the best idea to use aHashMap
(although the order of imports doesn't mater for properly designed libraries).
-
doAutoImportsAndIncludes
protected void doAutoImportsAndIncludes(Environment env) throws TemplateException, IOException
- Overrides:
doAutoImportsAndIncludes
in classConfigurable
- Throws:
TemplateException
IOException
-
addAutoInclude
public void addAutoInclude(String templateName)
Adds an invisible#include templateName as namespaceVarName
at the beginning of all templates. The order of the inclusions will be the same as the order in which they were added with this method.
-
setAutoIncludes
public void setAutoIncludes(List templateNames)
Removes all auto-includes, then callsaddAutoInclude(String)
for eachList
items.
-
removeAutoInclude
public void removeAutoInclude(String templateName)
Removes a template from the auto-include list; seeaddAutoInclude(String)
. Does nothing if the template is not there.
-
getVersionNumber
public static String getVersionNumber()
Deprecated.UsegetVersion()
instead.Returns FreeMarker version number string.
-
getVersion
public static Version getVersion()
Returns the FreeMarker version information, most importantly the major.minor.micro version numbers. On FreeMarker version numbering rules:- For final/stable releases the version number is like major.minor.micro, like 2.3.19. (Historically, when micro was 0 the version strings was like major.minor instead of the proper major.minor.0, but that's not like that anymore.)
- When only the micro version is increased, compatibility with previous versions with the same major.minor is kept. Thus freemarker.jar can be replaced in an existing application without breaking it.
- For non-final/unstable versions (that almost nobody uses), the format is:
- Starting from 2.3.20: major.minor.micro-extraInfo, like 2.3.20-nightly_20130506T123456Z, 2.4.0-RC01. The major.minor.micro always indicates the target we move towards, so 2.3.20-nightly or 2.3.20-M01 is after 2.3.19 and will eventually become to 2.3.20. "PRE", "M" and "RC" (uppercase!) means "preview", "milestone" and "release candidate" respectively, and is always followed by a 2 digit 0-padded counter, like M03 is the 3rd milestone release of a given major.minor.micro.
- Before 2.3.20: The extraInfo wasn't preceded by a "-". Instead of "nightly" there was "mod", where the major.minor.micro part has indicated where are we coming from, so 2.3.19mod (read as: 2.3.19 modified) was after 2.3.19 but before 2.3.20. Also, "pre" and "rc" was lowercase, and was followd by a number without 0-padding.
- Since:
- 2.3.20
-
getDefaultObjectWrapper
public static ObjectWrapper getDefaultObjectWrapper(Version incompatibleImprovements)
Returns the default object wrapper for a given "incompatible_improvements" version.- Since:
- 2.3.21
- See Also:
setIncompatibleImprovements(Version)
-
getSupportedBuiltInNames
public Set getSupportedBuiltInNames()
Returns the names of the supported "built-ins". These are the (expr?builtin_name
-like things). As of this writing, this information doesn't depend on the configuration options, so it could be a static method, but to be future-proof, it's an instance method.
-
-