public class Configurable
extends java.lang.Object
Configuration
,
Template
, and Environment
classes.
It provides settings that are common to each of them. FreeMarker
uses a three-level setting hierarchy - the return value of every setting
getter method on Configurable
objects inherits its value from its parent
Configurable
object, unless explicitly overridden by a call to a
corresponding setter method on the object itself. The parent of an
Environment
object is a Template
object, the
parent of a Template
object is a Configuration
object.Modifier and Type | Class and Description |
---|---|
static class |
Configurable.SettingValueAssignmentException
The setting name was recognized, but its value couldn't be parsed or the setting couldn't be set for some
other reason.
|
static class |
Configurable.UnknownSettingException
The setting name was not recognized.
|
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
API_BUILTIN_ENABLED_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
API_BUILTIN_ENABLED_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
API_BUILTIN_ENABLED_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
ARITHMETIC_ENGINE_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
ARITHMETIC_ENGINE_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
ARITHMETIC_ENGINE_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
ATTEMPT_EXCEPTION_REPORTER_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
ATTEMPT_EXCEPTION_REPORTER_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
ATTEMPT_EXCEPTION_REPORTER_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
AUTO_FLUSH_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
AUTO_FLUSH_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
AUTO_FLUSH_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
AUTO_IMPORT_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
AUTO_IMPORT_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
AUTO_IMPORT_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
AUTO_INCLUDE_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
AUTO_INCLUDE_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
AUTO_INCLUDE_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
BOOLEAN_FORMAT_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
BOOLEAN_FORMAT_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
BOOLEAN_FORMAT_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
C_FORMAT_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
C_FORMAT_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
C_FORMAT_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
CLASSIC_COMPATIBLE_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
CLASSIC_COMPATIBLE_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
CLASSIC_COMPATIBLE_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
CUSTOM_DATE_FORMATS_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
CUSTOM_DATE_FORMATS_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
CUSTOM_DATE_FORMATS_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
CUSTOM_NUMBER_FORMATS_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
CUSTOM_NUMBER_FORMATS_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
CUSTOM_NUMBER_FORMATS_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
DATE_FORMAT_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
DATE_FORMAT_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
DATE_FORMAT_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
DATETIME_FORMAT_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
DATETIME_FORMAT_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
DATETIME_FORMAT_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
LAZY_AUTO_IMPORTS_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
LAZY_AUTO_IMPORTS_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
LAZY_AUTO_IMPORTS_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
LAZY_IMPORTS_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
LAZY_IMPORTS_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
LAZY_IMPORTS_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
LOCALE_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
LOCALE_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
LOCALE_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
LOG_TEMPLATE_EXCEPTIONS_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
LOG_TEMPLATE_EXCEPTIONS_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
LOG_TEMPLATE_EXCEPTIONS_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
NEW_BUILTIN_CLASS_RESOLVER_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
NEW_BUILTIN_CLASS_RESOLVER_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
NEW_BUILTIN_CLASS_RESOLVER_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
NUMBER_FORMAT_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
NUMBER_FORMAT_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
NUMBER_FORMAT_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
OBJECT_WRAPPER_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
OBJECT_WRAPPER_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
OBJECT_WRAPPER_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
OUTPUT_ENCODING_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
OUTPUT_ENCODING_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
OUTPUT_ENCODING_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
SHOW_ERROR_TIPS_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
SHOW_ERROR_TIPS_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
SHOW_ERROR_TIPS_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
SQL_DATE_AND_TIME_TIME_ZONE_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
SQL_DATE_AND_TIME_TIME_ZONE_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
SQL_DATE_AND_TIME_TIME_ZONE_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
STRICT_BEAN_MODELS
Deprecated.
Use
STRICT_BEAN_MODELS_KEY instead. |
static java.lang.String |
STRICT_BEAN_MODELS_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
STRICT_BEAN_MODELS_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
STRICT_BEAN_MODELS_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
TEMPLATE_EXCEPTION_HANDLER_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
TEMPLATE_EXCEPTION_HANDLER_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
TEMPLATE_EXCEPTION_HANDLER_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
TIME_FORMAT_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
TIME_FORMAT_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
TIME_FORMAT_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
TIME_ZONE_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
TIME_ZONE_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
TIME_ZONE_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
TRUNCATE_BUILTIN_ALGORITHM_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
TRUNCATE_BUILTIN_ALGORITHM_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
TRUNCATE_BUILTIN_ALGORITHM_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
URL_ESCAPING_CHARSET_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
URL_ESCAPING_CHARSET_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
URL_ESCAPING_CHARSET_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
static java.lang.String |
WRAP_UNCHECKED_EXCEPTIONS_KEY
Alias to the
..._SNAKE_CASE variation due to backward compatibility constraints. |
static java.lang.String |
WRAP_UNCHECKED_EXCEPTIONS_KEY_CAMEL_CASE
Modern, camel case (
likeThis ) variation of the setting name. |
static java.lang.String |
WRAP_UNCHECKED_EXCEPTIONS_KEY_SNAKE_CASE
Legacy, snake case (
like_this ) variation of the setting name. |
Modifier | Constructor and Description |
---|---|
|
Configurable()
Deprecated.
This shouldn't even be public; don't use it.
|
|
Configurable(Configurable parent)
Creates a new instance.
|
protected |
Configurable(Version incompatibleImprovements)
Intended to be called from inside FreeMarker only.
|
Modifier and Type | Method and Description |
---|---|
void |
addAutoImport(java.lang.String namespaceVarName,
java.lang.String templateName)
Adds an invisible
#import templateName as namespaceVarName at the beginning of the
main template (that's the top-level template that wasn't included/imported from another template). |
void |
addAutoInclude(java.lang.String templateName)
Adds an invisible
#include templateName at the beginning of the main template (that's the
top-level template that wasn't included/imported from another template). |
protected java.lang.Object |
clone() |
protected void |
doAutoImportsAndIncludes(Environment env)
Executes the auto-imports and auto-includes for the main template of this environment.
|
ArithmeticEngine |
getArithmeticEngine()
The getter pair of
setArithmeticEngine(ArithmeticEngine) . |
AttemptExceptionReporter |
getAttemptExceptionReporter()
The getter pair of
setAttemptExceptionReporter(AttemptExceptionReporter) . |
boolean |
getAutoFlush()
|
java.util.Map<java.lang.String,java.lang.String> |
getAutoImports()
Getter pair of
setAutoImports(Map) ; do not modify the returned Map ! To be consistent with other
setting getters, if this setting was set directly on this Configurable object, this simply returns that
value, otherwise it returns the value from the parent Configurable . |
java.util.Map<java.lang.String,java.lang.String> |
getAutoImportsWithoutFallback()
|
java.util.List<java.lang.String> |
getAutoIncludes()
Getter pair of
setAutoIncludes(List) ; do not modify the returned List ! To be consistent with
other setting getters, if this setting was set directly on this Configurable object, this simply returns
that value, otherwise it returns the value from the parent Configurable . |
java.util.List<java.lang.String> |
getAutoIncludesWithoutFallback()
|
java.lang.String |
getBooleanFormat()
The getter pair of
setBooleanFormat(String) . |
CFormat |
getCFormat()
Getter pair of
setCFormat(CFormat) . |
int |
getClassicCompatibleAsInt() |
protected java.lang.String |
getCorrectedNameForUnknownSetting(java.lang.String name) |
java.lang.Object |
getCustomAttribute(java.lang.String name)
Retrieves a named custom attribute for this configurable.
|
java.lang.String[] |
getCustomAttributeNames()
Returns an array with names of all custom attributes defined directly
on this configurable.
|
TemplateDateFormatFactory |
getCustomDateFormat(java.lang.String name)
Gets the custom name format registered for the name.
|
java.util.Map<java.lang.String,? extends TemplateDateFormatFactory> |
getCustomDateFormats()
Getter pair of
setCustomDateFormats(Map) ; do not modify the returned Map ! To be consistent with
other setting getters, if this setting was set directly on this Configurable object, this simply returns
that value, otherwise it returns the value from the parent Configurable . |
java.util.Map<java.lang.String,? extends TemplateDateFormatFactory> |
getCustomDateFormatsWithoutFallback()
Like
getCustomDateFormats() , but doesn't fall back to the parent Configurable , nor does it
provide a non-null default when called as the method of a Configuration . |
TemplateNumberFormatFactory |
getCustomNumberFormat(java.lang.String name)
Gets the custom name format registered for the name.
|
java.util.Map<java.lang.String,? extends TemplateNumberFormatFactory> |
getCustomNumberFormats()
Getter pair of
setCustomNumberFormats(Map) ; do not modify the returned Map ! To be consistent
with other setting getters, if this setting was set directly on this Configurable object, this simply
returns that value, otherwise it returns the value from the parent Configurable . |
java.util.Map<java.lang.String,? extends TemplateNumberFormatFactory> |
getCustomNumberFormatsWithoutFallback()
Like
getCustomNumberFormats() , but doesn't fall back to the parent Configurable . |
java.lang.String |
getDateFormat()
The getter pair of
setDateFormat(String) . |
java.lang.String |
getDateTimeFormat()
The getter pair of
setDateTimeFormat(String) . |
protected Environment |
getEnvironment() |
java.lang.Boolean |
getLazyAutoImports()
The getter pair of
setLazyAutoImports(Boolean) . |
boolean |
getLazyImports()
The getter pair of
setLazyImports(boolean) . |
java.util.Locale |
getLocale()
Getter pair of
setLocale(Locale) . |
boolean |
getLogTemplateExceptions()
|
TemplateClassResolver |
getNewBuiltinClassResolver()
Retrieves the
TemplateClassResolver used
to resolve classes when "SomeClassName"?new is called in a template. |
java.lang.String |
getNumberFormat()
Getter pair of
setNumberFormat(String) . |
ObjectWrapper |
getObjectWrapper()
The getter pair of
setObjectWrapper(ObjectWrapper) . |
java.lang.String |
getOutputEncoding()
Getter pair of
setOutputEncoding(String) . |
Configurable |
getParent()
Returns the parent
Configurable object of this object. |
java.lang.String |
getSetting(java.lang.String key)
Deprecated.
It's not possible in general to convert setting values to string,
and thus it's impossible to ensure that
setSetting(String, String) will work with
the returned value correctly. |
java.util.Set<java.lang.String> |
getSettingNames(boolean camelCase)
Returns the valid setting names that aren't
Configuration -only. |
java.util.Map |
getSettings()
Deprecated.
This method was always defective, and certainly it always
will be. Don't use it. (Simply, it's hardly possible in general to
convert setting values to text in a way that ensures that
setSettings(Properties) will work with them correctly.) |
boolean |
getShowErrorTips()
|
java.util.TimeZone |
getSQLDateAndTimeTimeZone()
The getter pair of
setSQLDateAndTimeTimeZone(TimeZone) . |
TemplateExceptionHandler |
getTemplateExceptionHandler()
The getter pair of
setTemplateExceptionHandler(TemplateExceptionHandler) . |
java.lang.String |
getTimeFormat()
The getter pair of
setTimeFormat(String) . |
java.util.TimeZone |
getTimeZone()
The getter pair of
setTimeZone(TimeZone) . |
TruncateBuiltinAlgorithm |
getTruncateBuiltinAlgorithm()
|
java.lang.String |
getURLEscapingCharset() |
boolean |
getWrapUncheckedExceptions()
The getter pair of
setWrapUncheckedExceptions(boolean) . |
boolean |
hasCustomFormats()
Tells if this configurable object or its parent defines any custom formats.
|
protected TemplateException |
invalidSettingValueException(java.lang.String name,
java.lang.String value) |
boolean |
isAPIBuiltinEnabled()
|
boolean |
isAPIBuiltinEnabledSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isArithmeticEngineSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isAttemptExceptionReporterSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isAutoFlushSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isAutoImportsSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isAutoIncludesSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isBooleanFormatSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isCFormatSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isClassicCompatible()
Returns whether the engine runs in the "Classic Compatibile" mode.
|
boolean |
isClassicCompatibleSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isCustomDateFormatsSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isCustomNumberFormatsSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isDateFormatSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isDateTimeFormatSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isLazyAutoImportsSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isLazyImportsSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isLocaleSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isLogTemplateExceptionsSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isNewBuiltinClassResolverSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isNumberFormatSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isObjectWrapperSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isOutputEncodingSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isShowErrorTipsSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isSQLDateAndTimeTimeZoneSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isTemplateExceptionHandlerSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isTimeFormatSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isTimeZoneSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isTruncateBuiltinAlgorithmSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isURLEscapingCharsetSet()
Tells if this setting is set directly in this object or its value is coming from the
parent . |
boolean |
isWrapUncheckedExceptionsSet() |
protected java.util.HashMap |
parseAsImportList(java.lang.String text) |
protected java.util.ArrayList |
parseAsList(java.lang.String text) |
protected java.util.ArrayList |
parseAsSegmentedList(java.lang.String text) |
void |
removeAutoImport(java.lang.String namespaceVarName)
Removes an auto-import from this
Configurable level (not from the parents or children);
see addAutoImport(String, String) . |
void |
removeAutoInclude(java.lang.String templateName)
Removes the auto-include from this
Configurable level (not from the parents or children); see
addAutoInclude(String) . |
void |
removeCustomAttribute(java.lang.String name)
Removes a named custom attribute for this configurable.
|
void |
setAPIBuiltinEnabled(boolean value)
Specifies if
?api can be used in templates. |
void |
setArithmeticEngine(ArithmeticEngine arithmeticEngine)
Sets the arithmetic engine used to perform arithmetic operations.
|
void |
setAttemptExceptionReporter(AttemptExceptionReporter attemptExceptionReporter)
Specifies how exceptions handled (and hence suppressed) by an
#attempt blocks will be logged or otherwise
reported. |
void |
setAutoFlush(boolean autoFlush)
Sets whether the output
Writer is automatically flushed at
the end of Template.process(Object, Writer) (and its
overloads). |
void |
setAutoImports(java.util.Map map)
Removes all auto-imports, then calls
addAutoImport(String, String) for each Map -entry (the entry
key is the namespaceVarName ). |
void |
setAutoIncludes(java.util.List templateNames)
Removes all auto-includes, then calls
addAutoInclude(String) for each List items. |
void |
setBooleanFormat(java.lang.String booleanFormat)
The string value for the boolean
true and false values, usually intended for human consumption
(not for a computer language), separated with comma. |
void |
setCFormat(CFormat cFormat)
Sets the format (usually a computer language) used for
?c , ?cn , and for the
"c" ("computer" before 2.3.32) number_format , and the
"c" boolean_format . |
void |
setClassicCompatible(boolean classicCompatibility)
Toggles the "Classic Compatible" mode.
|
void |
setClassicCompatibleAsInt(int classicCompatibility)
Same as
setClassicCompatible(boolean) , but allows some extra values. |
void |
setCustomAttribute(java.lang.String name,
java.lang.Object value)
Sets a named custom attribute for this configurable.
|
void |
setCustomDateFormats(java.util.Map<java.lang.String,? extends TemplateDateFormatFactory> customDateFormats)
Associates names with formatter factories, which then can be referred by the
date_format , time_format , and datetime_format settings with values starting with @name . |
void |
setCustomNumberFormats(java.util.Map<java.lang.String,? extends TemplateNumberFormatFactory> customNumberFormats)
Associates names with formatter factories, which then can be referred by the
number_format setting with values starting with @name . |
void |
setDateFormat(java.lang.String dateFormat)
Sets the format used to convert
Date -s that are date-only (no time part) values to string-s,
also the format that someString?date will use to parse strings. |
void |
setDateTimeFormat(java.lang.String dateTimeFormat)
Sets the format used to convert
Date -s that are date-time (timestamp) values to string-s,
also the format that someString?datetime will use to parse strings. |
void |
setLazyAutoImports(java.lang.Boolean lazyAutoImports)
Specifies if auto-imports will be
lazy imports . |
void |
setLazyImports(boolean lazyImports)
Specifies if
<#import ...> (and Environment.importLib(String, String) ) should delay the loading
and processing of the imported templates until the content of the imported namespace is actually accessed. |
void |
setLocale(java.util.Locale locale)
Sets the locale used for number and date formatting (among others), also the locale used for searching
localized template variations when no locale was explicitly requested.
|
void |
setLogTemplateExceptions(boolean value)
Specifies if
TemplateException -s thrown by template processing are logged by FreeMarker or not. |
void |
setNewBuiltinClassResolver(TemplateClassResolver newBuiltinClassResolver)
Sets the
TemplateClassResolver that is used when the
new built-in is called in a template. |
void |
setNumberFormat(java.lang.String numberFormat)
Sets the number format used to convert numbers to strings.
|
void |
setObjectWrapper(ObjectWrapper objectWrapper)
Sets the object wrapper used to wrap objects to
TemplateModel -s. |
void |
setOutputEncoding(java.lang.String outputEncoding)
Informs FreeMarker about the charset used for the output.
|
void |
setSetting(java.lang.String name,
java.lang.String value)
Sets a FreeMarker setting by a name and string value.
|
void |
setSettings(java.io.InputStream propsIn)
Reads a setting list (key and element pairs) from the input stream.
|
void |
setSettings(java.util.Properties props)
Set the settings stored in a
Properties object. |
void |
setShowErrorTips(boolean showTips)
Sets if tips should be shown in error messages of errors arising during template processing.
|
void |
setSQLDateAndTimeTimeZone(java.util.TimeZone tz)
Sets the time zone used when dealing with
java.sql.Date and
java.sql.Time values. |
void |
setStrictBeanModels(boolean strict)
Deprecated.
Set this on the
ObjectWrapper itself. |
void |
setTemplateExceptionHandler(TemplateExceptionHandler templateExceptionHandler)
Sets the exception handler used to handle exceptions occurring inside templates.
|
void |
setTimeFormat(java.lang.String timeFormat)
Sets the format used to convert
Date -s that are time (no date part) values to string-s, also
the format that someString?time will use to parse strings. |
void |
setTimeZone(java.util.TimeZone timeZone)
Sets the time zone to use when formatting date/time values.
|
protected TemplateException |
settingValueAssignmentException(java.lang.String name,
java.lang.String value,
java.lang.Throwable cause) |
void |
setTruncateBuiltinAlgorithm(TruncateBuiltinAlgorithm truncateBuiltinAlgorithm)
Specifies the algorithm used for
?truncate . |
void |
setURLEscapingCharset(java.lang.String urlEscapingCharset)
Sets the URL escaping (URL encoding, percentage encoding) charset.
|
void |
setWrapUncheckedExceptions(boolean wrapUncheckedExceptions)
Specifies if unchecked exceptions thrown during expression evaluation or during executing custom directives (and
transform) will be wrapped into
TemplateException -s, or will bubble up to the caller of
Template.process(Object, Writer, ObjectWrapper) as is. |
protected TemplateException |
unknownSettingException(java.lang.String name)
Creates the exception that should be thrown when a setting name isn't recognized.
|
public static final java.lang.String LOCALE_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String LOCALE_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String LOCALE_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String C_FORMAT_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String C_FORMAT_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String C_FORMAT_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String NUMBER_FORMAT_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String NUMBER_FORMAT_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String NUMBER_FORMAT_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String CUSTOM_NUMBER_FORMATS_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String CUSTOM_NUMBER_FORMATS_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String CUSTOM_NUMBER_FORMATS_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String TIME_FORMAT_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String TIME_FORMAT_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String TIME_FORMAT_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String DATE_FORMAT_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String DATE_FORMAT_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String DATE_FORMAT_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String CUSTOM_DATE_FORMATS_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String CUSTOM_DATE_FORMATS_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String CUSTOM_DATE_FORMATS_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String DATETIME_FORMAT_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String DATETIME_FORMAT_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String DATETIME_FORMAT_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String TIME_ZONE_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String TIME_ZONE_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String TIME_ZONE_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String SQL_DATE_AND_TIME_TIME_ZONE_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String SQL_DATE_AND_TIME_TIME_ZONE_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String SQL_DATE_AND_TIME_TIME_ZONE_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String CLASSIC_COMPATIBLE_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String CLASSIC_COMPATIBLE_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String CLASSIC_COMPATIBLE_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String TEMPLATE_EXCEPTION_HANDLER_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String TEMPLATE_EXCEPTION_HANDLER_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String TEMPLATE_EXCEPTION_HANDLER_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String ATTEMPT_EXCEPTION_REPORTER_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.27public static final java.lang.String ATTEMPT_EXCEPTION_REPORTER_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.27public static final java.lang.String ATTEMPT_EXCEPTION_REPORTER_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String ARITHMETIC_ENGINE_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String ARITHMETIC_ENGINE_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String ARITHMETIC_ENGINE_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String OBJECT_WRAPPER_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String OBJECT_WRAPPER_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String OBJECT_WRAPPER_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String BOOLEAN_FORMAT_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String BOOLEAN_FORMAT_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String BOOLEAN_FORMAT_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String OUTPUT_ENCODING_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String OUTPUT_ENCODING_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String OUTPUT_ENCODING_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String URL_ESCAPING_CHARSET_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String URL_ESCAPING_CHARSET_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String URL_ESCAPING_CHARSET_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String STRICT_BEAN_MODELS_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String STRICT_BEAN_MODELS_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String STRICT_BEAN_MODELS_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints. @since 2.3.22public static final java.lang.String AUTO_FLUSH_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String AUTO_FLUSH_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String AUTO_FLUSH_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints. @since 2.3.17public static final java.lang.String NEW_BUILTIN_CLASS_RESOLVER_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String NEW_BUILTIN_CLASS_RESOLVER_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String NEW_BUILTIN_CLASS_RESOLVER_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints. @since 2.3.17public static final java.lang.String SHOW_ERROR_TIPS_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String SHOW_ERROR_TIPS_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String SHOW_ERROR_TIPS_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints. @since 2.3.21public static final java.lang.String API_BUILTIN_ENABLED_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String API_BUILTIN_ENABLED_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String API_BUILTIN_ENABLED_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints. @since 2.3.22public static final java.lang.String TRUNCATE_BUILTIN_ALGORITHM_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.29public static final java.lang.String TRUNCATE_BUILTIN_ALGORITHM_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.29public static final java.lang.String TRUNCATE_BUILTIN_ALGORITHM_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String LOG_TEMPLATE_EXCEPTIONS_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.23public static final java.lang.String LOG_TEMPLATE_EXCEPTIONS_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.23public static final java.lang.String LOG_TEMPLATE_EXCEPTIONS_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints. @since 2.3.22public static final java.lang.String WRAP_UNCHECKED_EXCEPTIONS_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.27public static final java.lang.String WRAP_UNCHECKED_EXCEPTIONS_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.27public static final java.lang.String WRAP_UNCHECKED_EXCEPTIONS_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints. @since 2.3.27public static final java.lang.String LAZY_IMPORTS_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.25public static final java.lang.String LAZY_IMPORTS_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.25public static final java.lang.String LAZY_IMPORTS_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String LAZY_AUTO_IMPORTS_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.25public static final java.lang.String LAZY_AUTO_IMPORTS_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.25public static final java.lang.String LAZY_AUTO_IMPORTS_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String AUTO_IMPORT_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.25public static final java.lang.String AUTO_IMPORT_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.25public static final java.lang.String AUTO_IMPORT_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.public static final java.lang.String AUTO_INCLUDE_KEY_SNAKE_CASE
like_this
) variation of the setting name. @since 2.3.25public static final java.lang.String AUTO_INCLUDE_KEY_CAMEL_CASE
likeThis
) variation of the setting name. @since 2.3.25public static final java.lang.String AUTO_INCLUDE_KEY
..._SNAKE_CASE
variation due to backward compatibility constraints.@Deprecated public static final java.lang.String STRICT_BEAN_MODELS
STRICT_BEAN_MODELS_KEY
instead.@Deprecated public Configurable()
protected Configurable(Version incompatibleImprovements)
Configuration
constructor.public Configurable(Configurable parent)
Configurable
directly, but its subclasses.protected java.lang.Object clone() throws java.lang.CloneNotSupportedException
clone
in class java.lang.Object
java.lang.CloneNotSupportedException
public final Configurable getParent()
Configurable
object of this object. The parent stores the default setting values for
this Configurable
. For example, the parent of a Template
object is a
Configuration
object, so values not specified on Template
-level are get from the
Configuration
object.
Note on the parent of Environment
: If you set incompatible_improvements
to at least 2.3.22, it will be always the "main" Template
, that is, the
template for whose processing the Environment
was created. With lower incompatible_improvements
,
the current parent can temporary change during template execution, for example when your are inside an
#include
-d template (among others). Thus, don't build on which Template
the parent of
Environment
is during template execution, unless you set incompatible_improvements
to 2.3.22 or
higher.
Configurable
object, or null
if this is the root Configurable
object
(i.e, if it's the Configuration
object).public void setClassicCompatible(boolean classicCompatibility)
isClassicCompatible()
.public void setClassicCompatibleAsInt(int classicCompatibility)
setClassicCompatible(boolean)
, but allows some extra values.classicCompatibility
- 0
means false
, 1
means true
,
2
means true
but with emulating bugs in early 2.x classic-compatibility mode. Currently
2
affects how booleans are converted to string; with 1
it's always "true"
/""
,
but with 2
it's "true"
/"false"
for values wrapped by BeansWrapper
as then
Boolean.toString()
prevails. Note that someBoolean?string
will always consistently format the
boolean according the boolean_format
setting, just like in FreeMarker 2.3 and later.public boolean isClassicCompatible()
public int getClassicCompatibleAsInt()
public boolean isClassicCompatibleSet()
parent
.public void setLocale(java.util.Locale locale)
Configuration
level it
defaults to the default locale of system (of the JVM), for server-side application usually you should set it
explicitly in the Configuration
to use the preferred locale of your application instead.public java.util.Locale getLocale()
setLocale(Locale)
. Not null
.public boolean isCFormatSet()
parent
.public void setCFormat(CFormat cFormat)
?c
, ?cn
, and for the
"c"
("computer"
before 2.3.32) number_format
, and the
"c"
boolean_format
.
The default value depends on incompatible_improvements
.
If that's 2.3.32 or higher, then it's "JavaScript or JSON"
,
otherwise it's "legacy"
.
public CFormat getCFormat()
setCFormat(CFormat)
. Not null
.public boolean isLocaleSet()
parent
.public void setTimeZone(java.util.TimeZone timeZone)
TimeZone.getDefault()
), regardless of the "locale" FreeMarker setting,
so in a server application you probably want to set it explicitly in the Environment
to match the
preferred time zone of target audience (like the Web page visitor).
If you or the templates set the time zone, you should probably also set
setSQLDateAndTimeTimeZone(TimeZone)
!
setSQLDateAndTimeTimeZone(TimeZone)
public java.util.TimeZone getTimeZone()
setTimeZone(TimeZone)
.public boolean isTimeZoneSet()
parent
.public void setSQLDateAndTimeTimeZone(java.util.TimeZone tz)
java.sql.Date
and
java.sql.Time
values. It defaults to null
for backward compatibility, but in most
applications this should be set to the JVM default time zone (server default time zone), because that's what
most JDBC drivers will use when constructing the java.sql.Date
and
java.sql.Time
values. If this setting is null
, FreeMarker will use the value of
(getTimeZone()
) for java.sql.Date
and java.sql.Time
values,
which often gives bad results.
This setting doesn't influence the formatting of other kind of values (like of
java.sql.Timestamp
or plain java.util.Date
values).
To decide what value you need, a few things has to be understood:
Date
and its subclasses store (milliseconds since
the epoch). Obviously, this is impossible to do. So JDBC just chooses a physical time which, when rendered
with the JVM default time zone, will give the same field values as those stored
in the database. (Actually, you can give JDBC a calendar, and so it can use other time zones too, but most
application won't care using those overloads.) For example, assume that the system time zone is GMT+02:00.
Then, 2014-07-12 in the database will be translated to physical time 2014-07-11 22:00:00 UTC, because that
rendered in GMT+02:00 gives 2014-07-12 00:00:00. Similarly, 11:57:00 in the database will be translated to
physical time 1970-01-01 09:57:00 UTC. Thus, the physical time stored in the returned value depends on the
default system time zone of the JDBC client, not just on the content of the database. (This used to be the
default behavior of ORM-s, like Hibernate, too.)
time_zone
FreeMarker configuration setting sets the time zone used for the
template output. For example, when a web page visitor has a preferred time zone, the web application framework
may calls Environment.setTimeZone(TimeZone)
with that time zone. Thus, the visitor will
see java.sql.Timestamp
and plain java.util.Date
values as
they look in his own time zone. While
this is desirable for those types, as they meant to represent physical points on the time line, this is not
necessarily desirable for date-only and time-only values. When sql_date_and_time_time_zone
is
null
, time_zone
is used for rendering all kind of date/time/dateTime values, including
java.sql.Date
and java.sql.Time
, and then if, for example,
time_zone
is GMT+00:00, the
values from the earlier examples will be shown as 2014-07-11 (one day off) and 09:57:00 (2 hours off). While
those are the time zone correct renderings, those values are probably meant to be shown "as is".
java.sql.Timestamp
values as well. Timestamps in databases refer to a point on
the physical time line, and thus doesn't have the inherent problem of date-only and time-only values.
FreeMarker assumes that the JDBC driver converts time stamps coming from the database so that they store
the distance from the epoch (1970-01-01 00:00:00 UTC), as requested by the Date
API.
Then time stamps can be safely rendered in different time zones, and thus need no special treatment.
tz
- Maybe null
, in which case java.sql.Date
and
java.sql.Time
values will be formatted in the time zone returned by
getTimeZone()
.
(Note that since null
is an allowed value for this setting, it will not cause
getSQLDateAndTimeTimeZone()
to fall back to the parent configuration.)setTimeZone(TimeZone)
public java.util.TimeZone getSQLDateAndTimeTimeZone()
setSQLDateAndTimeTimeZone(TimeZone)
.null
if the value of getTimeZone()
should be used for formatting
java.sql.Date
and java.sql.Time
values, otherwise the time zone
that should be used to format the values of those two types.public boolean isSQLDateAndTimeTimeZoneSet()
parent
.public void setNumberFormat(java.lang.String numberFormat)
"number"
: The number format returned by NumberFormat.getNumberInstance(Locale)
. This is the
default."c"
(recognized since 2.3.32): The number format used by FTL's c
built-in (like in
someNumber?c
). So with this ${someNumber}
will output the same as
${someNumber?c}
. This should only be used if the template solely generates source code,
configuration file, or other content that's not read by normal users. If the template contains parts that's
read by normal users (like typical a web page), you are not supposed to use this."computer"
: The old (deprecated) name for "c"
. Recognized by all FreeMarker versions."currency"
: The number format returned by NumberFormat.getCurrencyInstance(Locale)
"percent"
: The number format returned by NumberFormat.getPercentInstance(Locale)
DecimalFormat
pattern (like "0.##"
). This syntax is extended by FreeMarker
so that you can specify options like the rounding mode and the symbols used after a 2nd semicolon. For
example, ",000;; roundingMode=halfUp groupingSeparator=_"
will format numbers like ",000"
would, but with half-up rounding mode, and _
as the group separator. See more about "extended Java
decimal format" in the FreeMarker Manual.
@
character followed by a letter then it's interpreted as a custom number
format, but only if either Configuration.getIncompatibleImprovements()
is at least 2.3.24, or
there's any custom formats defined (even if custom date/time/dateTime format). The format of a such string
is "@name"
or "@name parameters"
, where
name
is the key in the Map
set by setCustomNumberFormats(Map)
, and
parameters
is parsed by the custom TemplateNumberFormat
.
Defaults to "number".
public java.lang.String getNumberFormat()
setNumberFormat(String)
.public boolean isNumberFormatSet()
parent
.public java.util.Map<java.lang.String,? extends TemplateNumberFormatFactory> getCustomNumberFormats()
setCustomNumberFormats(Map)
; do not modify the returned Map
! To be consistent
with other setting getters, if this setting was set directly on this Configurable
object, this simply
returns that value, otherwise it returns the value from the parent Configurable
. So beware, the returned
value doesn't reflect the Map
key granularity fallback logic that FreeMarker actually uses for this
setting (for that, use getCustomNumberFormat(String)
). The returned value isn't a snapshot; it may or
may not shows the changes later made to this setting on this Configurable
level (but usually it's well
defined if until what point settings are possibly modified).
The return value is never null
; called on the Configuration
(top) level, it defaults to an empty
Map
.
getCustomNumberFormatsWithoutFallback()
public java.util.Map<java.lang.String,? extends TemplateNumberFormatFactory> getCustomNumberFormatsWithoutFallback()
getCustomNumberFormats()
, but doesn't fall back to the parent Configurable
.public void setCustomNumberFormats(java.util.Map<java.lang.String,? extends TemplateNumberFormatFactory> customNumberFormats)
number_format
setting with values starting with @name
. Beware, if you specify any custom
formats here, an initial @
followed by a letter will have special meaning in number/date/time/datetime
format strings, even if incompatible_improvements
is less
than 2.3.24 (starting with incompatible_improvements
2.3.24
@
always has special meaning).customNumberFormats
- Can't be null
. The name must start with an UNICODE letter, and can only contain UNICODE
letters and digits (not _
).public boolean isCustomNumberFormatsSet()
parent
.public TemplateNumberFormatFactory getCustomNumberFormat(java.lang.String name)
public boolean hasCustomFormats()
public void setBooleanFormat(java.lang.String booleanFormat)
true
and false
values, usually intended for human consumption
(not for a computer language), separated with comma. For example, "yes,no"
. Note that white-space is
significant, so "yes, no"
is WRONG (unless you want that leading space before "no"). Because the proper
way of formatting booleans depends on the context too much, it's probably the best to leave this setting on its
default, which will enforce explicit formatting, like ${aBoolean?string('on', 'off')}
.
For backward compatibility the default is "true,false"
, but using that value is denied for automatic
boolean-to-string conversion, like ${myBoolean}
will fail with it. If you generate the piece of
output for "computer audience" as opposed to "human audience", then you should write
${myBoolean?c}
, which will print true
or false
. If you really want to always
format for computer audience, then it's might be reasonable to set this setting to c
.
Note that automatic boolean-to-string conversion only exists since FreeMarker 2.3.20. Earlier this setting
only influenced the result of myBool?string
.
public java.lang.String getBooleanFormat()
setBooleanFormat(String)
.public boolean isBooleanFormatSet()
parent
.public void setTimeFormat(java.lang.String timeFormat)
Date
-s that are time (no date part) values to string-s, also
the format that someString?time
will use to parse strings.
For the possible values see setDateTimeFormat(String)
.
Defaults to ""
, which is equivalent to "medium"
.
public java.lang.String getTimeFormat()
setTimeFormat(String)
.public boolean isTimeFormatSet()
parent
.public void setDateFormat(java.lang.String dateFormat)
Date
-s that are date-only (no time part) values to string-s,
also the format that someString?date
will use to parse strings.
For the possible values see setDateTimeFormat(String)
.
Defaults to ""
which is equivalent to "medium"
.
public java.lang.String getDateFormat()
setDateFormat(String)
.public boolean isDateFormatSet()
parent
.public void setDateTimeFormat(java.lang.String dateTimeFormat)
Date
-s that are date-time (timestamp) values to string-s,
also the format that someString?datetime
will use to parse strings.
The possible setting values are (the quotation marks aren't part of the value itself):
Patterns accepted by Java's SimpleDateFormat
, for example "dd.MM.yyyy HH:mm:ss"
(where
HH
means 24 hours format) or "MM/dd/yyyy hh:mm:ss a"
(where a
prints AM or PM, if
the current language is English).
"xs"
for XML Schema format, or "iso"
for ISO 8601:2004 format.
These formats allow various additional options, separated with space, like in
"iso m nz"
(or with _
, like in "iso_m_nz"
; this is useful in a case like
lastModified?string.iso_m_nz
). The options and their meanings are:
Accuracy options:
ms
= Milliseconds, always shown with all 3 digits, even if it's all 0-s.
Example: 13:45:05.800
s
= Seconds (fraction seconds are dropped even if non-0), like 13:45:05
m
= Minutes, like 13:45
. This isn't allowed for "xs".
h
= Hours, like 13
. This isn't allowed for "xs".
Neither = Up to millisecond accuracy, but trailing millisecond 0-s are removed, also the whole
milliseconds part if it would be 0 otherwise. Example: 13:45:05.8
Time zone offset visibility options:
fz
= "Force Zone", always show time zone offset (even for for
java.sql.Date
and java.sql.Time
values).
But, because ISO 8601 doesn't allow for dates (means date without time of the day) to
show the zone offset, this option will have no effect in the case of "iso"
with
dates.
nz
= "No Zone", never show time zone offset
Neither = always show time zone offset, except for java.sql.Date
and java.sql.Time
, and for "iso"
date values.
Time zone options:
u
= Use UTC instead of what the time_zone
setting suggests. However,
java.sql.Date
and java.sql.Time
aren't affected
by this (see setSQLDateAndTimeTimeZone(TimeZone)
to understand why)
fu
= "Force UTC", that is, use UTC instead of what the time_zone
or the
sql_date_and_time_time_zone
setting suggests. This also effects
java.sql.Date
and java.sql.Time
values
Neither = Use the time zone suggested by the time_zone
or the
sql_date_and_time_time_zone
configuration setting (setTimeZone(TimeZone)
and
setSQLDateAndTimeTimeZone(TimeZone)
).
The options can be specified in any order.
Options from the same category are mutually exclusive, like using m
and s
together is an error.
The accuracy and time zone offset visibility options don't influence parsing, only formatting. For example, even if you use "iso m nz", "2012-01-01T15:30:05.125+01" will be parsed successfully and with milliseconds accuracy. The time zone options (like "u") influence what time zone is chosen only when parsing a string that doesn't contain time zone offset.
Parsing with "iso"
understands both extend format and basic format, like
20141225T235018
. It doesn't, however, support the parsing of all kind of ISO 8601 strings: if
there's a date part, it must use year, month and day of the month values (not week of the year), and the
day can't be omitted.
The output of "iso"
is deliberately so that it's also a good representation of the value with
XML Schema format, except for 0 and negative years, where it's impossible. Also note that the time zone
offset is omitted for date values in the "iso"
format, while it's preserved for the "xs"
format.
"short"
, "medium"
, "long"
, or "full"
, which that has locale-dependent
meaning defined by the Java platform (see in the documentation of DateFormat
).
For date-time values, you can specify the length of the date and time part independently, be separating
them with _
, like "short_medium"
. ("medium"
means
"medium_medium"
for date-time values.)
Anything that starts with "@"
followed by a letter is interpreted as a custom
date/time/dateTime format, but only if either Configuration.getIncompatibleImprovements()
is at least 2.3.24, or there's any custom formats defined (even if custom number format). The format of
such string is "@name"
or "@name parameters"
, where
name
is the key in the Map
set by setCustomDateFormats(Map)
, and
parameters
is parsed by the custom number format.
Defaults to ""
, which is equivalent to "medium_medium"
.
public java.lang.String getDateTimeFormat()
setDateTimeFormat(String)
.public boolean isDateTimeFormatSet()
parent
.public java.util.Map<java.lang.String,? extends TemplateDateFormatFactory> getCustomDateFormats()
setCustomDateFormats(Map)
; do not modify the returned Map
! To be consistent with
other setting getters, if this setting was set directly on this Configurable
object, this simply returns
that value, otherwise it returns the value from the parent Configurable
. So beware, the returned value
doesn't reflect the Map
key granularity fallback logic that FreeMarker actually uses for this setting
(for that, use getCustomDateFormat(String)
). The returned value isn't a snapshot; it may or may not
shows the changes later made to this setting on this Configurable
level (but usually it's well defined if
until what point settings are possibly modified).
The return value is never null
; called on the Configuration
(top) level, it defaults to an empty
Map
.
getCustomDateFormatsWithoutFallback()
public java.util.Map<java.lang.String,? extends TemplateDateFormatFactory> getCustomDateFormatsWithoutFallback()
getCustomDateFormats()
, but doesn't fall back to the parent Configurable
, nor does it
provide a non-null
default when called as the method of a Configuration
.public void setCustomDateFormats(java.util.Map<java.lang.String,? extends TemplateDateFormatFactory> customDateFormats)
date_format
, time_format
, and datetime_format
settings with values starting with @name
. Beware, if you specify any custom
formats here, an initial @
followed by a letter will have special meaning in number/date/time/datetime
format strings, even if incompatible_improvements
is less
than 2.3.24 (starting with incompatible_improvements
2.3.24
@
always has special meaning).customDateFormats
- Can't be null
. The name must start with an UNICODE letter, and can only contain UNICODE
letters and digits.public boolean isCustomDateFormatsSet()
parent
.public TemplateDateFormatFactory getCustomDateFormat(java.lang.String name)
public void setTemplateExceptionHandler(TemplateExceptionHandler templateExceptionHandler)
TemplateExceptionHandler.DEBUG_HANDLER
. The recommended values are:
TemplateExceptionHandler.RETHROW_HANDLER
TemplateExceptionHandler.HTML_DEBUG_HANDLER
TemplateExceptionHandler.DEBUG_HANDLER
All of these will let the exception propagate further, so that you can catch it around
Template.process(Object, Writer)
for example. The difference is in what they print on the output before
they do that.
Note that the TemplateExceptionHandler
is not meant to be used for generating HTTP error pages.
Neither is it meant to be used to roll back the printed output. These should be solved outside template
processing when the exception raises from Template.process
.
TemplateExceptionHandler
meant to be used if you want to include special content in the template
output, or if you want to suppress certain exceptions. If you suppress an exception, and the
getLogTemplateExceptions()
returns false
, then it's the responsibility of the
TemplateExceptionHandler
to log the exception (if you want it to be logged).
public TemplateExceptionHandler getTemplateExceptionHandler()
setTemplateExceptionHandler(TemplateExceptionHandler)
.public boolean isTemplateExceptionHandlerSet()
parent
.public void setAttemptExceptionReporter(AttemptExceptionReporter attemptExceptionReporter)
#attempt
blocks will be logged or otherwise
reported. The default value is AttemptExceptionReporter.LOG_ERROR_REPORTER
.
Note that #attempt
is not supposed to be a general purpose error handler mechanism, like try
is in Java. It's for decreasing the impact of unexpected errors, by making it possible that only part of the
page is going down, instead of the whole page. But it's still an error, something that someone should fix. So the
error should be reported, not just ignored in a custom AttemptExceptionReporter
-s.
The AttemptExceptionReporter
is invoked regardless of the value of the
log_template_exceptions
setting.
The AttemptExceptionReporter
is not invoked if the TemplateExceptionHandler
has suppressed the
exception.
public AttemptExceptionReporter getAttemptExceptionReporter()
setAttemptExceptionReporter(AttemptExceptionReporter)
.public boolean isAttemptExceptionReporterSet()
parent
.public void setArithmeticEngine(ArithmeticEngine arithmeticEngine)
ArithmeticEngine.BIGDECIMAL_ENGINE
.public ArithmeticEngine getArithmeticEngine()
setArithmeticEngine(ArithmeticEngine)
.public boolean isArithmeticEngineSet()
parent
.public void setObjectWrapper(ObjectWrapper objectWrapper)
TemplateModel
-s.
The default is ObjectWrapper.DEFAULT_WRAPPER
.public ObjectWrapper getObjectWrapper()
setObjectWrapper(ObjectWrapper)
.public boolean isObjectWrapperSet()
parent
.public void setOutputEncoding(java.lang.String outputEncoding)
null
means that the output encoding is not known.
Defaults to null
(unknown).
public java.lang.String getOutputEncoding()
setOutputEncoding(String)
.public boolean isOutputEncodingSet()
parent
.public void setURLEscapingCharset(java.lang.String urlEscapingCharset)
null
, the output encoding
(setOutputEncoding(String)
) will be used for URL escaping.
Defaults to null
.public java.lang.String getURLEscapingCharset()
public boolean isURLEscapingCharsetSet()
parent
.public void setNewBuiltinClassResolver(TemplateClassResolver newBuiltinClassResolver)
TemplateClassResolver
that is used when the
new
built-in is called in a template. That is, when
a template contains the "com.example.SomeClassName"?new
expression, this object will be called to resolve the
"com.example.SomeClassName"
string to a class. The default
value is TemplateClassResolver.UNRESTRICTED_RESOLVER
in
FreeMarker 2.3.x, and TemplateClassResolver.SAFER_RESOLVER
starting from FreeMarker 2.4.0. If you allow users to upload templates,
it's important to use a custom restrictive TemplateClassResolver
.
Note that the MemberAccessPolicy
used by the ObjectWrapper
also influences what constructors
are available. Allowing the resolution of the class here is not enough in itself, as the
MemberAccessPolicy
has to allow exposing the particular constructor you try to call as well.
public TemplateClassResolver getNewBuiltinClassResolver()
TemplateClassResolver
used
to resolve classes when "SomeClassName"?new is called in a template.public boolean isNewBuiltinClassResolverSet()
parent
.public void setAutoFlush(boolean autoFlush)
Writer
is automatically flushed at
the end of Template.process(Object, Writer)
(and its
overloads). The default is true
.
Using false
is needed for example when a Web page is composed
from several boxes (like portlets, GUI panels, etc.) that aren't inserted
with #include (or with similar directives) into a master
FreeMarker template, rather they are all processed with a separate
Template.process(Object, Writer)
call. In a such scenario the
automatic flushes would commit the HTTP response after each box, hence
interfering with full-page buffering, and also possibly decreasing
performance with too frequent and too early response buffer flushes.
public boolean getAutoFlush()
public boolean isAutoFlushSet()
parent
.public void setShowErrorTips(boolean showTips)
true
.public boolean getShowErrorTips()
public boolean isShowErrorTipsSet()
parent
.public void setAPIBuiltinEnabled(boolean value)
?api
can be used in templates. Defaults to false
so that updating FreeMarker won't
decrease the security of existing applications.public boolean isAPIBuiltinEnabled()
public boolean isAPIBuiltinEnabledSet()
parent
.public void setTruncateBuiltinAlgorithm(TruncateBuiltinAlgorithm truncateBuiltinAlgorithm)
?truncate
. Defaults to
DefaultTruncateBuiltinAlgorithm.ASCII_INSTANCE
. Most customization needs can be addressed by
creating a new DefaultTruncateBuiltinAlgorithm
with the proper constructor parameters. Otherwise users
my use their own TruncateBuiltinAlgorithm
implementation.
In case you need to set this with Properties
, or a similar configuration approach that doesn't let you
create the value in Java, see examples at setSetting(String, String)
.
public TruncateBuiltinAlgorithm getTruncateBuiltinAlgorithm()
public boolean isTruncateBuiltinAlgorithmSet()
parent
.public void setLogTemplateExceptions(boolean value)
TemplateException
-s thrown by template processing are logged by FreeMarker or not. The
default is true
for backward compatibility, but that results in logging the exception twice in properly
written applications, because there the TemplateException
thrown by the public FreeMarker API is also
logged by the caller (even if only as the cause exception of a higher level exception). Hence, in modern
applications it should be set to false
. Note that this setting has no effect on the logging of exceptions
caught by #attempt
; by default those are always logged as errors (because those exceptions won't bubble
up to the API caller), however, that can be changed with the attempt_exception_reporter
setting.public boolean getLogTemplateExceptions()
public boolean isLogTemplateExceptionsSet()
parent
.public void setWrapUncheckedExceptions(boolean wrapUncheckedExceptions)
TemplateException
-s, or will bubble up to the caller of
Template.process(Object, Writer, ObjectWrapper)
as is. The default is false
for backward
compatibility (as some applications catch certain unchecked exceptions thrown by the template processing to do
something special), but the recommended value is true
.
When this is true
, the unchecked exceptions will be wrapped into a TemplateException
-s, thus the
exception will include the location in the template (not
just the Java stack trace). Another consequence of the wrapping is that the TemplateExceptionHandler
will
be invoked for the exception (as that only handles TemplateException
-s, it wasn't invoked for unchecked
exceptions). When this setting is false
, unchecked exception will be thrown by
Template.process(Object, Writer, ObjectWrapper)
.
Note that plain Java methods called from templates aren't user defined TemplateMethodModel
-s, and have
always wrapped the thrown exception into TemplateException
, regardless of this setting.public boolean getWrapUncheckedExceptions()
setWrapUncheckedExceptions(boolean)
.public boolean isWrapUncheckedExceptionsSet()
public boolean getLazyImports()
setLazyImports(boolean)
.public void setLazyImports(boolean lazyImports)
<#import ...>
(and Environment.importLib(String, String)
) should delay the loading
and processing of the imported templates until the content of the imported namespace is actually accessed. This
makes the overhead of unused imports negligible. Note that turning on lazy importing isn't entirely
transparent, as accessing global variables (usually created with <#global ...=...>
) that should be
created by the imported template won't trigger the loading and processing of the lazily imported template
(because globals aren't accessed through the namespace variable), so the global variable will just be missing.
In general, you lose the strict control over when the namespace initializing code in the imported template will
be executed, though it shouldn't mater for most well designed imported templates.
Another drawback is that importing a missing or otherwise broken template will be successful, and the problem
will remain hidden until (and if) the namespace content is actually used. Note that the namespace initializing
code will run with the same locale as it was at the point of the
<#import ...>
call (other settings won't be handled specially like that).
The default is false
(and thus imports are eager) for backward compatibility, which can cause
perceivable overhead if you have many imports and only a few of them is actually used.
This setting also affects auto-imports, unless you have set a non-null
value with setLazyAutoImports(Boolean)
.
setLazyAutoImports(Boolean)
public boolean isLazyImportsSet()
parent
.public java.lang.Boolean getLazyAutoImports()
setLazyAutoImports(Boolean)
.public void setLazyAutoImports(java.lang.Boolean lazyAutoImports)
lazy imports
. This is useful to make the overhead of unused
auto-imports negligible. If this is set to null
, getLazyImports()
specifies the behavior of
auto-imports too. The default value is null
.public boolean isLazyAutoImportsSet()
parent
.public void addAutoImport(java.lang.String namespaceVarName, java.lang.String templateName)
#import templateName as namespaceVarName
at the beginning of the
main template (that's the top-level template that wasn't included/imported from another template). While it only
affects the main template directly, as the imports will create a global variable there, the imports will be
visible from the further imported templates too (note that Configuration.getIncompatibleImprovements()
set to 2.3.24 fixes a rarely surfacing bug with that).
It's recommended to set the lazy_auto_imports
setting (setLazyAutoImports(Boolean)
)
to true
when using this, so that auto-imports that are unused in a template won't degrade performance by
unnecessary loading and initializing the imported library.
If the imports aren't lazy, the order of the imports will be the same as the order in which they were added with
this method. (Calling this method with an already added namespaceVarName
will move that to the end
of the auto-import order.)
The auto-import is added directly to the Configurable
on which this method is called (not to the parents
or children), but when the main template is processed, the auto-imports are collected from all the
Configurable
levels, in parent-to-child order: Configuration
, Template
(the main
template), Environment
. If the same namespaceVarName
occurs on multiple levels, the one on the
child level is used, and the clashing import from the parent level is skipped.
If there are also auto-includes (see addAutoInclude(String)
), those will be executed after
the auto-imports.
setAutoImports(Map)
public void removeAutoImport(java.lang.String namespaceVarName)
Configurable
level (not from the parents or children);
see addAutoImport(String, String)
. Does nothing if the auto-import doesn't exist.public void setAutoImports(java.util.Map map)
addAutoImport(String, String)
for each Map
-entry (the entry
key is the namespaceVarName
). The order of the auto-imports will be the same as Map.keySet()
returns the keys (but the order of imports doesn't mater for properly designed libraries anyway).map
- Maps the namespace variable names to the template names; not null
public java.util.Map<java.lang.String,java.lang.String> getAutoImports()
setAutoImports(Map)
; do not modify the returned Map
! To be consistent with other
setting getters, if this setting was set directly on this Configurable
object, this simply returns that
value, otherwise it returns the value from the parent Configurable
. So beware, the returned value doesn't
reflect the Map
key granularity fallback logic that FreeMarker actually uses for this setting. The
returned value is not the same Map
object that was set with setAutoImports(Map)
, only its
content is the same. The returned value isn't a snapshot; it may or may not shows the changes later made to this
setting on this Configurable
level (but usually it's well defined if until what point settings are
possibly modified).
The return value is never null
; called on the Configuration
(top) level, it defaults to an empty
Map
.
getAutoImportsWithoutFallback()
public boolean isAutoImportsSet()
parent
.public java.util.Map<java.lang.String,java.lang.String> getAutoImportsWithoutFallback()
public void addAutoInclude(java.lang.String templateName)
#include templateName
at the beginning of the main template (that's the
top-level template that wasn't included/imported from another template).
The order of the inclusions will be the same as the order in which they were added with this method.
The auto-include is added directly to the Configurable
on which this method is called (not to the parents
or children), but when the main template is processed, the auto-includes are collected from all the
Configurable
levels, in parent-to-child order: Configuration
, Template
(the main
template), Environment
.
If there are also auto-imports (addAutoImport(String, String)
), those imports will be executed before
the auto-includes, hence the namespace variables are accessible for the auto-included templates.
Calling addAutoInclude(String)
with an already added template name will just move that to the end of the
auto-include list (within the same Configurable
level). This works even if the same template name appears
on different Configurable
levels, in which case only the inclusion on the lowest (child) level will be
executed.
setAutoIncludes(List)
public void setAutoIncludes(java.util.List templateNames)
addAutoInclude(String)
for each List
items.
Before incompatible improvements 2.3.25 it doesn't filter
out duplicates from the list if this method was called on a Configuration
instance.
public java.util.List<java.lang.String> getAutoIncludes()
setAutoIncludes(List)
; do not modify the returned List
! To be consistent with
other setting getters, if this setting was set directly on this Configurable
object, this simply returns
that value, otherwise it returns the value from the parent Configurable
. So beware, the returned value
doesn't reflect the List
concatenation logic that FreeMarker actually uses for this setting. The returned
value is not the same List
object that was set with setAutoIncludes(List)
, only its content is
the same (except that duplicate are removed). The returned value isn't a snapshot; it may or may not shows the
changes later made to this setting on this Configurable
level (but usually it's well defined if until
what point settings are possibly modified).
The return value is never null
; called on the Configuration
(top) level, it defaults to an empty
List
.
getAutoIncludesWithoutFallback()
public boolean isAutoIncludesSet()
parent
.public java.util.List<java.lang.String> getAutoIncludesWithoutFallback()
public void removeAutoInclude(java.lang.String templateName)
Configurable
level (not from the parents or children); see
addAutoInclude(String)
. Does nothing if the template is not there.public void setSetting(java.lang.String name, java.lang.String value) throws TemplateException
setObjectWrapper(ObjectWrapper)
. This meant to be used only when you get settings from somewhere
as String
-String
name-value pairs (typically, as a Properties
object). Below you find an
overview of the settings available.
Note: As of FreeMarker 2.3.23, setting names can be written in camel case too. For example, instead of
date_format
you can also use dateFormat
. It's likely that camel case will become to the
recommended convention in the future.
The list of settings commonly supported in all Configurable
subclasses:
"locale"
:
See setLocale(Locale)
.
String value: local codes with the usual format in Java, such as "en_US"
, or since 2.3.26,
"JVM default" (ignoring case) to use the default locale of the Java environment.
"classic_compatible"
:
See setClassicCompatible(boolean)
and setClassicCompatibleAsInt(int)
.
String value: "true"
, "false"
, also since 2.3.20 0
or 1
or 2
.
(Also accepts "yes"
, "no"
, "t"
, "f"
, "y"
, "n"
.)
Case insensitive.
"custom_number_formats"
: See setCustomNumberFormats(Map)
.
String value: Interpreted as an object builder expression.
Example: { "hex": com.example.HexTemplateNumberFormatFactory,
"gps": com.example.GPSTemplateNumberFormatFactory }
"custom_date_formats"
: See setCustomDateFormats(Map)
.
String value: Interpreted as an object builder expression.
Example: { "trade": com.example.TradeTemplateDateFormatFactory,
"log": com.example.LogTemplateDateFormatFactory }
"c_format"
:
See Configuration.setCFormat(CFormat)
.
String value: "default"
(case insensitive) for the default (on Configuration
only), or
one of the predefined values "JavaScript or JSON"
, "JSON"
,
"JavaScript"
, "Java"
, "XS"
, "legacy"
,
or an object builder expression that gives a CFormat
object.
"template_exception_handler"
:
See setTemplateExceptionHandler(TemplateExceptionHandler)
.
String value: If the value contains dot, then it's interpreted as an object builder
expression.
If the value does not contain dot, then it must be one of these predefined values (case insensitive):
"rethrow"
(means TemplateExceptionHandler.RETHROW_HANDLER
),
"debug"
(means TemplateExceptionHandler.DEBUG_HANDLER
),
"html_debug"
(means TemplateExceptionHandler.HTML_DEBUG_HANDLER
),
"ignore"
(means TemplateExceptionHandler.IGNORE_HANDLER
), or
"default"
(only allowed for Configuration
instances) for the default value.
"attempt_exception_reporter"
:
See setAttemptExceptionReporter(AttemptExceptionReporter)
.
String value: If the value contains dot, then it's interpreted as an object builder
expression.
If the value does not contain dot, then it must be one of these predefined values (case insensitive):
"log_error"
(means AttemptExceptionReporter.LOG_ERROR_REPORTER
),
"log_warn"
(means AttemptExceptionReporter.LOG_WARN_REPORTER
), or
"default"
(only allowed for Configuration
instances) for the default value.
"arithmetic_engine"
:
See setArithmeticEngine(ArithmeticEngine)
.
String value: If the value contains dot, then it's interpreted as an object builder
expression.
If the value does not contain dot,
then it must be one of these special values (case insensitive):
"bigdecimal"
, "conservative"
.
"object_wrapper"
:
See setObjectWrapper(ObjectWrapper)
.
String value: If the value contains dot, then it's interpreted as an object builder
expression, with the addition that BeansWrapper
, DefaultObjectWrapper
and
SimpleObjectWrapper
can be referred without package name. For example, these strings are valid
values: "DefaultObjectWrapper(2.3.21, forceLegacyNonListCollections=false, iterableSupport=true)"
,
"BeansWrapper(2.3.21, simpleMapWrapper=true)"
.
If the value does not contain dot, then it must be one of these special values (case insensitive):
"default"
means the default of Configuration
(the default depends on the
Configuration#Configuration(Version) incompatible_improvements
, but a bug existed in 2.3.21 where
that was ignored),
"default_2_3_0"
(means the deprecated ObjectWrapper.DEFAULT_WRAPPER
)
"simple"
(means the deprecated ObjectWrapper.SIMPLE_WRAPPER
),
"beans"
(means the deprecated ObjectWrapper.BEANS_WRAPPER
or BeansWrapperBuilder.build()
),
"jython"
(means ObjectWrapper.DEFAULT_WRAPPER
)
"number_format"
: See setNumberFormat(String)
.
"boolean_format"
: See setBooleanFormat(String)
.
"date_format", "time_format", "datetime_format"
:
See setDateFormat(String)
, setTimeFormat(String)
, setDateTimeFormat(String)
.
"time_zone"
:
See setTimeZone(TimeZone)
.
String value: With the format as TimeZone.getTimeZone(String)
defines it. Also, since 2.3.21
"JVM default"
can be used that will be replaced with the actual JVM default time zone when
setSetting(String, String)
is called.
For example "GMT-8:00"
or "America/Los_Angeles"
If you set this setting, consider setting sql_date_and_time_time_zone
too (see below)!
sql_date_and_time_time_zone
:
See setSQLDateAndTimeTimeZone(TimeZone)
.
Since 2.3.21.
String value: With the format as TimeZone.getTimeZone(String)
defines it. Also,
"JVM default"
can be used that will be replaced with the actual JVM default time zone when
setSetting(String, String)
is called. Also "null"
can be used, which has the same effect
as setSQLDateAndTimeTimeZone(null)
.
"output_encoding"
:
See setOutputEncoding(String)
.
"url_escaping_charset"
:
See setURLEscapingCharset(String)
.
"auto_flush"
:
See setAutoFlush(boolean)
.
Since 2.3.17.
String value: "true"
, "false"
, "y"
, etc.
"auto_import"
:
See setAutoImports(Map)
String value is something like:
/lib/form.ftl as f, /lib/widget as w, "/lib/odd name.ftl" as odd
"auto_include"
: Sets the list of auto-includes.
See setAutoIncludes(List)
String value is something like:
/include/common.ftl, "/include/evil name.ftl"
"lazy_auto_imports"
:
See setLazyAutoImports(Boolean)
.
String value: "true"
, "false"
(also the equivalents: "yes"
, "no"
,
"t"
, "f"
, "y"
, "n"
), case insensitive. Also can be "null"
.
"lazy_imports"
:
See setLazyImports(boolean)
.
String value: "true"
, "false"
(also the equivalents: "yes"
, "no"
,
"t"
, "f"
, "y"
, "n"
), case insensitive.
"new_builtin_class_resolver"
:
See setNewBuiltinClassResolver(TemplateClassResolver)
.
Since 2.3.17.
The value must be one of these (ignore the quotation marks):
"unrestricted"
:
Use TemplateClassResolver.UNRESTRICTED_RESOLVER
"safer"
:
Use TemplateClassResolver.SAFER_RESOLVER
"allows_nothing"
(or "allowsNothing"
):
Use TemplateClassResolver.ALLOWS_NOTHING_RESOLVER
Something that contains colon will use
OptInTemplateClassResolver
and is expected to
store comma separated values (possibly quoted) segmented
with "allowed_classes:"
(or "allowedClasses:"
) and/or
"trusted_templates:"
(or "trustedTemplates:"
). Examples of valid values:
Setting value | Meaning |
---|---|
allowed_classes: com.example.C1, com.example.C2,
trusted_templates: lib/*, safe.ftl
|
Only allow instantiating the com.example.C1 and
com.example.C2 classes. But, allow templates
within the lib/ directory (like
lib/foo/bar.ftl ) and template safe.ftl
(that does not match foo/safe.ftl , only
exactly safe.ftl ) to instantiate anything
that TemplateClassResolver.SAFER_RESOLVER allows.
|
allowed_classes: com.example.C1, com.example.C2
| Only allow instantiating the com.example.C1 and
com.example.C2 classes. There are no
trusted templates.
|
trusted_templates: lib/*, safe.ftl
|
Do not allow instantiating any classes, except in
templates inside lib/ or in template
safe.ftl .
|
For more details see OptInTemplateClassResolver
.
Otherwise if the value contains dot, it's interpreted as an object builder expression.
"show_error_tips"
:
See setShowErrorTips(boolean)
.
Since 2.3.21.
String value: "true"
, "false"
, "y"
, etc.
api_builtin_enabled
:
See setAPIBuiltinEnabled(boolean)
.
Since 2.3.22.
String value: "true"
, "false"
, "y"
, etc.
"truncate_builtin_algorithm"
:
See setTruncateBuiltinAlgorithm(TruncateBuiltinAlgorithm)
.
Since 2.3.19.
String value: An
object builder expression, or one of the predefined values (case insensitive),
ascii
(for DefaultTruncateBuiltinAlgorithm.ASCII_INSTANCE
) and
unicode
(for DefaultTruncateBuiltinAlgorithm.UNICODE_INSTANCE
).
Example object builder expressions:
Use "..."
as terminator (and same as markup terminator), and add space if the
truncation happened on word boundary:
DefaultTruncateBuiltinAlgorithm("...", true)
Use "..."
as terminator, and also a custom HTML for markup terminator, and add space if the
truncation happened on word boundary:
DefaultTruncateBuiltinAlgorithm("...",
markup(HTMLOutputFormat(), "<span class=trunc>...</span>"), true)
Recreate default truncate algorithm, but with not preferring truncation at word boundaries (i.e.,
with wordBoundaryMinLength
1.0):
freemarker.core.DefaultTruncateBuiltinAlgorithm(
DefaultTruncateBuiltinAlgorithm.STANDARD_ASCII_TERMINATOR, null, null,
DefaultTruncateBuiltinAlgorithm.STANDARD_M_TERMINATOR, null, null,
true, 1.0)
Configuration
(a subclass of Configurable
) also understands these:
"auto_escaping"
:
See Configuration.setAutoEscapingPolicy(int)
String value: "enable_if_default"
or "enableIfDefault"
for
Configuration.ENABLE_IF_DEFAULT_AUTO_ESCAPING_POLICY
,
"enable_if_supported"
or "enableIfSupported"
for
Configuration.ENABLE_IF_SUPPORTED_AUTO_ESCAPING_POLICY
"disable"
for Configuration.DISABLE_AUTO_ESCAPING_POLICY
.
"default_encoding"
:
See Configuration.setDefaultEncoding(String)
; since 2.3.26 also accepts value "JVM default"
(not case sensitive) to set the Java environment default value.
As the default value is the system default, which can change
from one server to another, you should always set this!
"localized_lookup"
:
See Configuration.setLocalizedLookup(boolean)
.
String value: "true"
, "false"
(also the equivalents: "yes"
, "no"
,
"t"
, "f"
, "y"
, "n"
).
Case insensitive.
"output_format"
:
See Configuration.setOutputFormat(OutputFormat)
.
String value: "default"
(case insensitive) for the default,
one of undefined
, HTML
, XHTML
, XML
, RTF
, plainText
,
CSS
, JavaScript
, JSON
,
or an object builder expression that gives an OutputFormat
, for example
HTMLOutputFormat
, or com.example.MyOutputFormat()
.
"registered_custom_output_formats"
:
See Configuration.setRegisteredCustomOutputFormats(Collection)
.
String value: an object builder expression that gives a List
of
OutputFormat
-s.
Example: [com.example.MyOutputFormat(), com.example.MyOtherOutputFormat()]
"strict_syntax"
:
See Configuration.setStrictSyntaxMode(boolean)
. Deprecated.
String value: "true"
, "false"
, yes
, etc.
"whitespace_stripping"
:
See Configuration.setWhitespaceStripping(boolean)
.
String value: "true"
, "false"
, yes
, etc.
"cache_storage"
:
See Configuration.setCacheStorage(freemarker.cache.CacheStorage)
.
String value: If the value contains dot, then it's interpreted as an object builder
expression.
If the value does not contain dot,
then a MruCacheStorage
will be used with the
maximum strong and soft sizes specified with the setting value. Examples
of valid setting values:
Setting value | max. strong size | max. soft size |
---|---|---|
"strong:50, soft:500" | 50 | 500 |
"strong:100, soft" | 100 | Integer.MAX_VALUE
|
"strong:100" | 100 | 0 |
"soft:100" | 0 | 100 |
"strong" | Integer.MAX_VALUE | 0 |
"soft" | 0 | Integer.MAX_VALUE
|
The value is not case sensitive. The order of soft and strong entries is not significant.
"template_update_delay"
:
Template update delay in seconds (not in milliseconds) if no unit is specified; see
Configuration.setTemplateUpdateDelayMilliseconds(long)
for more.
String value: Valid positive integer, optionally followed by a time unit (recommended). The default
unit is seconds. It's strongly recommended to specify the unit for clarity, like in "500 ms" or "30 s".
Supported units are: "s" (seconds), "ms" (milliseconds), "m" (minutes), "h" (hours). The whitespace between
the unit and the number is optional. Units are only supported since 2.3.23.
"tag_syntax"
:
See Configuration.setTagSyntax(int)
.
String value: Must be one of
"auto_detect"
, "angle_bracket"
, and "square_bracket"
(like [#if x]
).
Note that setting the "tagSyntax"
to "square_bracket"
does not change
${x}
to [=...]
; that's interpolation syntax, so use the
"interpolation_syntax"
setting for that, not this setting.
"interpolation_syntax"
(since 2.3.28):
See Configuration.setInterpolationSyntax(int)
.
String value: Must be one of
"legacy"
, "dollar"
, and "square_bracket"
(like [=x]
).
Note that setting the "interpolation_syntax"
to "square_bracket"
does not
change <#if x>
to [#if x]
; that's tag syntax, so use the
"tag_syntax"
setting for that, not this setting.
"naming_convention"
:
See Configuration.setNamingConvention(int)
.
String value: Must be one of
"auto_detect"
, "legacy"
, and "camel_case"
.
"fallback_on_null_loop_variable"
:
See Configuration.setFallbackOnNullLoopVariable(boolean)
.
String value: "true"
, "false"
(also the equivalents: "yes"
, "no"
,
"t"
, "f"
, "y"
, "n"
).
Case insensitive.
"incompatible_improvements"
:
See Configuration.setIncompatibleImprovements(Version)
.
String value: version number like 2.3.20
.
"incompatible_enhancements"
:
See: Configuration.setIncompatibleEnhancements(String)
.
This setting name is deprecated, use "incompatible_improvements"
instead.
"recognize_standard_file_extensions"
:
See Configuration.setRecognizeStandardFileExtensions(boolean)
.
String value: "default"
(case insensitive) for the default, or "true"
, "false"
,
yes
, etc.
"template_configurations"
:
See: Configuration.setTemplateConfigurations(freemarker.cache.TemplateConfigurationFactory)
.
String value: Interpreted as an object builder expression,
can be null
.
"template_loader"
:
See: Configuration.setTemplateLoader(TemplateLoader)
.
String value: "default"
(case insensitive) for the default, or else interpreted as an
object builder expression. "null"
is also allowed since 2.3.26.
"template_lookup_strategy"
:
See: Configuration.setTemplateLookupStrategy(freemarker.cache.TemplateLookupStrategy)
.
String value: "default"
(case insensitive) for the default, or else interpreted as an
object builder expression.
"template_name_format"
:
See: Configuration.setTemplateNameFormat(freemarker.cache.TemplateNameFormat)
.
String value: "default"
(case insensitive) for the default, "default_2_3_0"
for TemplateNameFormat.DEFAULT_2_3_0
, "default_2_4_0"
for
TemplateNameFormat.DEFAULT_2_4_0
.
"tab_size"
:
See Configuration.setTabSize(int)
.
Regarding object builder expressions (used by the setting values where it was indicated):
Before FreeMarker 2.3.21 it had to be a fully qualified class name, and nothing else.
Since 2.3.21, the generic syntax is: className(constrArg1, constrArg2, ... constrArgN, propName1=propValue1, propName2=propValue2, ... propNameN=propValueN), where className is the fully qualified class name of the instance to create (except if we have builder class or INSTANCE field around, but see that later), constrArg-s are the values of constructor arguments, and propName=propValue-s set JavaBean properties (like x=1 means setX(1)) on the created instance. You can have any number of constructor arguments and property setters, including 0. Constructor arguments must precede any property setters.
If you have no constructor arguments and property setters, and the className class has
a public static INSTANCE
field, the value of that filed will be the value of the expression, and
the constructor won't be called. Note that if you use the backward compatible
syntax, where these's no parenthesis after the class name, then it will not look for INSTANCE
.
If there exists a class named classNameBuilder, then that class will be instantiated instead with the given constructor arguments, and the JavaBean properties of that builder instance will be set. After that, the public build() method of the instance will be called, whose return value will be the value of the whole expression. (The builder class and the build() method is simply found by name, there's no special interface to implement.) Note that if you use the backward compatible syntax, where these's no parenthesis after the class name, then it will not look for builder class. Note that if you have a builder class, you don't actually need a className class (since 2.3.24); after all, classNameBuilder.build() can return any kind of object.
Currently, the values of arguments and properties can only be one of these:
123
or -1.5
. The value will be automatically converted to
the type of the target (just like in FTL). However, a target type is only available if the number will
be a parameter to a method or constructor, not when it's a value (or key) in a List
or
Map
literal. Thus in the last case the type of number will be like in Java language, like
1
is an int
, and 1.0
is a double
, and 1.0f
is a float
,
etc. In all cases, the standard Java type postfixes can be used ("f", "d", "l"), plus "bd" for
BigDecimal
and "bi" for BigInteger
.true
or false
null
"Line 1\nLine 2"
or r"C:\temp"
.
[ 'foo', 2, true ]
.
If the parameter is expected to be array, the list will be automatically converted to array.
The list items can be any kind of expression, like even object builder expressions.
{ 'foo': 2, 'bar': true }
.
The keys and values can be any kind of expression, like even object builder expressions.
The resulting Java object will be a Map
that keeps the item order (LinkedHashMap
as
of this writing).
Configuration.AUTO_DETECT_TAG_SYNTAX
or
com.example.MyClass.MY_CONSTANT
.
null
).
The top-level object builder expressions may omit ()
. In that case, for backward compatibility,
the INSTANCE
field and the builder class is not searched, so the instance will be always
created with its parameterless constructor. (This behavior will possibly change in 2.4.) The ()
can't be omitted for nested expressions.
The following classes can be referred to with simple (unqualified) name instead of fully qualified name:
DefaultObjectWrapper
, BeansWrapper
, SimpleObjectWrapper
, Locale
,
TemplateConfiguration
, PathGlobMatcher
, FileNameGlobMatcher
, PathRegexMatcher
,
AndMatcher
, OrMatcher
, NotMatcher
, ConditionalTemplateConfigurationFactory
,
MergingTemplateConfigurationFactory
, FirstMatchTemplateConfigurationFactory
,
HTMLOutputFormat
, XMLOutputFormat
, RTFOutputFormat
, PlainTextOutputFormat
,
UndefinedOutputFormat
, Configuration
, DefaultTruncateBuiltinAlgorithm
.
TimeZone
objects can be created like TimeZone("UTC")
, despite that there's no a such
constructor (since 2.3.24).
TemplateMarkupOutputModel
objects can be created like
markup(HTMLOutputFormat(), "<h1>Example</h1>")
(since 2.3.29). Of course the 1st argument can be
any other MarkupOutputFormat
too.
The classes and methods that the expression meant to access must be all public.
name
- the name of the setting.value
- the string that describes the new value of the setting.Configurable.UnknownSettingException
- if the name is wrong.TemplateException
- if the new value of the setting can't be set for any other reasons.public java.util.Set<java.lang.String> getSettingNames(boolean camelCase)
Configuration
-only.camelCase
- If we want the setting names with camel case naming convention, or with snake case (legacy) naming
convention.Configuration.getSettingNames(boolean)
@Deprecated public void setStrictBeanModels(boolean strict)
ObjectWrapper
itself.@Deprecated public java.lang.String getSetting(java.lang.String key)
setSetting(String, String)
will work with
the returned value correctly.key
- the setting key. Can be any of standard XXX_KEY
constants, or a custom key.@Deprecated public java.util.Map getSettings()
setSettings(Properties)
will work with them correctly.)Map
of the
settings. So it actually should return a Properties
object,
but it doesn't by mistake. The returned Map
is read-only,
but it will reflect the further configuration changes (aliasing effect).protected Environment getEnvironment()
protected TemplateException unknownSettingException(java.lang.String name)
protected java.lang.String getCorrectedNameForUnknownSetting(java.lang.String name)
name
- The wrong namenull
if there's no known correctionprotected TemplateException settingValueAssignmentException(java.lang.String name, java.lang.String value, java.lang.Throwable cause)
protected TemplateException invalidSettingValueException(java.lang.String name, java.lang.String value)
public void setSettings(java.util.Properties props) throws TemplateException
Properties
object.TemplateException
- if the Properties
object contains
invalid keys, or invalid setting values, or any other error occurs
while changing the settings.public void setSettings(java.io.InputStream propsIn) throws TemplateException, java.io.IOException
.properties
format.TemplateException
- if the stream contains
invalid keys, or invalid setting values, or any other error occurs
while changing the settings.java.io.IOException
- if an error occurred when reading from the input stream.public void setCustomAttribute(java.lang.String name, java.lang.Object value)
name
- the name of the custom attributevalue
- the value of the custom attribute. You can set the value to
null, however note that there is a semantic difference between an
attribute set to null and an attribute that is not present, see
removeCustomAttribute(String)
.public java.lang.String[] getCustomAttributeNames()
public void removeCustomAttribute(java.lang.String name)
getCustomAttribute(String)
will return
null, while if you remove the attribute, it will return the value of
the attribute in the parent configurable (if there is a parent
configurable, that is).name
- the name of the custom attributepublic java.lang.Object getCustomAttribute(java.lang.String name)
name
- the name of the custom attributeString
, or a List
, or a
Map
, ...etc., not a FreeMarker specific class).protected void doAutoImportsAndIncludes(Environment env) throws TemplateException, java.io.IOException
TemplateException
java.io.IOException
protected java.util.ArrayList parseAsList(java.lang.String text) throws ParseException
ParseException
protected java.util.ArrayList parseAsSegmentedList(java.lang.String text) throws ParseException
ParseException
protected java.util.HashMap parseAsImportList(java.lang.String text) throws ParseException
ParseException