Class Configurable
- java.lang.Object
-
- freemarker.core.Configurable
-
- Direct Known Subclasses:
Configuration
,Environment
,Template
public class Configurable extends Object
This is a common superclass ofConfiguration
,Template
, andEnvironment
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 onConfigurable
objects inherits its value from its parentConfigurable
object, unless explicitly overridden by a call to a corresponding setter method on the object itself. The parent of anEnvironment
object is aTemplate
object, the parent of aTemplate
object is aConfiguration
object.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class 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.
-
Field Summary
Fields Modifier and Type Field Description static String
API_BUILTIN_ENABLED_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
API_BUILTIN_ENABLED_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
API_BUILTIN_ENABLED_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
ARITHMETIC_ENGINE_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
ARITHMETIC_ENGINE_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
ARITHMETIC_ENGINE_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
AUTO_FLUSH_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
AUTO_FLUSH_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
AUTO_FLUSH_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
BOOLEAN_FORMAT_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
BOOLEAN_FORMAT_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
BOOLEAN_FORMAT_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
CLASSIC_COMPATIBLE_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
CLASSIC_COMPATIBLE_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
CLASSIC_COMPATIBLE_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
DATE_FORMAT_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
DATE_FORMAT_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
DATE_FORMAT_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
DATETIME_FORMAT_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
DATETIME_FORMAT_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
DATETIME_FORMAT_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
LOCALE_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
LOCALE_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
LOCALE_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
LOG_TEMPLATE_EXCEPTIONS_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
LOG_TEMPLATE_EXCEPTIONS_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
LOG_TEMPLATE_EXCEPTIONS_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
NEW_BUILTIN_CLASS_RESOLVER_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
NEW_BUILTIN_CLASS_RESOLVER_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
NEW_BUILTIN_CLASS_RESOLVER_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
NUMBER_FORMAT_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
NUMBER_FORMAT_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
NUMBER_FORMAT_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
OBJECT_WRAPPER_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
OBJECT_WRAPPER_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
OBJECT_WRAPPER_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
OUTPUT_ENCODING_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
OUTPUT_ENCODING_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
OUTPUT_ENCODING_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
SHOW_ERROR_TIPS_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
SHOW_ERROR_TIPS_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
SHOW_ERROR_TIPS_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
SQL_DATE_AND_TIME_TIME_ZONE_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
SQL_DATE_AND_TIME_TIME_ZONE_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
SQL_DATE_AND_TIME_TIME_ZONE_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
STRICT_BEAN_MODELS
Deprecated.UseSTRICT_BEAN_MODELS_KEY
instead.static String
STRICT_BEAN_MODELS_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
STRICT_BEAN_MODELS_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
STRICT_BEAN_MODELS_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
TEMPLATE_EXCEPTION_HANDLER_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
TEMPLATE_EXCEPTION_HANDLER_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
TEMPLATE_EXCEPTION_HANDLER_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
TIME_FORMAT_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
TIME_FORMAT_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
TIME_FORMAT_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
TIME_ZONE_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
TIME_ZONE_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
TIME_ZONE_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.static String
URL_ESCAPING_CHARSET_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.static String
URL_ESCAPING_CHARSET_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name.static String
URL_ESCAPING_CHARSET_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name.
-
Constructor Summary
Constructors Modifier Constructor 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.
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description protected Object
clone()
protected void
doAutoImportsAndIncludes(Environment env)
ArithmeticEngine
getArithmeticEngine()
The getter pair ofsetArithmeticEngine(ArithmeticEngine)
.boolean
getAutoFlush()
String
getBooleanFormat()
The getter pair ofsetBooleanFormat(String)
.int
getClassicCompatibleAsInt()
protected String
getCorrectedNameForUnknownSetting(String name)
Object
getCustomAttribute(String name)
Retrieves a named custom attribute for this configurable.String[]
getCustomAttributeNames()
Returns an array with names of all custom attributes defined directly on this configurable.String
getDateFormat()
The getter pair ofsetDateFormat(String)
.String
getDateTimeFormat()
The getter pair ofsetDateTimeFormat(String)
.protected Environment
getEnvironment()
Locale
getLocale()
Returns the assumed locale when searching for template files with no explicit requested locale.boolean
getLogTemplateExceptions()
TemplateClassResolver
getNewBuiltinClassResolver()
Retrieves theTemplateClassResolver
used to resolve classes when "SomeClassName"?new is called in a template.String
getNumberFormat()
Getter pair ofsetNumberFormat(String)
.ObjectWrapper
getObjectWrapper()
The getter pair ofsetObjectWrapper(ObjectWrapper)
.String
getOutputEncoding()
Configurable
getParent()
Returns the parentConfigurable
object of this object.String
getSetting(String key)
Deprecated.It's not possible in general to convert setting values to string, and thus it's impossible to ensure thatsetSetting(String, String)
will work with the returned value correctly.Map
getSettings()
Deprecated.This method was always defective, and certainly it always will be.boolean
getShowErrorTips()
TimeZone
getSQLDateAndTimeTimeZone()
The getter pair ofsetSQLDateAndTimeTimeZone(TimeZone)
.TemplateExceptionHandler
getTemplateExceptionHandler()
The getter pair ofsetTemplateExceptionHandler(TemplateExceptionHandler)
.String
getTimeFormat()
The getter pair ofsetTimeFormat(String)
.TimeZone
getTimeZone()
The getter pair ofsetTimeZone(TimeZone)
.String
getURLEscapingCharset()
protected TemplateException
invalidSettingValueException(String name, String value)
boolean
isAPIBuiltinEnabled()
boolean
isClassicCompatible()
Returns whether the engine runs in the "Classic Compatibile" mode.protected HashMap
parseAsImportList(String text)
protected ArrayList
parseAsList(String text)
protected ArrayList
parseAsSegmentedList(String text)
void
removeCustomAttribute(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
setAutoFlush(boolean autoFlush)
Sets whether the outputWriter
is automatically flushed at the end ofTemplate.process(Object, Writer)
(and its overloads).void
setBooleanFormat(String booleanFormat)
The string value for the booleantrue
andfalse
values, intended for human audience (not for a computer language), separated with comma.void
setClassicCompatible(boolean classicCompatibility)
Toggles the "Classic Compatible" mode.void
setClassicCompatibleAsInt(int classicCompatibility)
Same assetClassicCompatible(boolean)
, but allows some extra values.void
setCustomAttribute(String name, Object value)
Sets a named custom attribute for this configurable.void
setDateFormat(String dateFormat)
Sets the format used to convertDate
-s to string-s that are date (no time part) values, also the format thatsomeString?date
will use to parse strings.void
setDateTimeFormat(String dateTimeFormat)
Sets the format used to convertDate
-s to string-s that are date-time (timestamp) values, also the format thatsomeString?datetime
will use to parse strings.void
setLocale(Locale locale)
Sets the default 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 ifTemplateException
-s thrown by template processing are logged by FreeMarker or not.void
setNewBuiltinClassResolver(TemplateClassResolver newBuiltinClassResolver)
Sets theTemplateClassResolver
that is used when thenew
built-in is called in a template.void
setNumberFormat(String numberFormat)
Sets the default number format used to convert numbers to strings.void
setObjectWrapper(ObjectWrapper objectWrapper)
Sets the object wrapper used to wrap objects toTemplateModel
-s.void
setOutputEncoding(String outputEncoding)
Informs FreeMarker about the charset used for the output.void
setSetting(String name, String value)
Sets a FreeMarker setting by a name and string value.void
setSettings(InputStream propsIn)
Reads a setting list (key and element pairs) from the input stream.void
setSettings(Properties props)
Set the settings stored in aProperties
object.void
setShowErrorTips(boolean showTips)
Sets if tips should be shown in error messages of errors arising during template processing.void
setSQLDateAndTimeTimeZone(TimeZone tz)
Sets the time zone used when dealing withjava.sql.Date
andjava.sql.Time
values.void
setStrictBeanModels(boolean strict)
void
setTemplateExceptionHandler(TemplateExceptionHandler templateExceptionHandler)
Sets the exception handler used to handle exceptions occurring inside templates.void
setTimeFormat(String timeFormat)
Sets the format used to convertDate
-s to string-s that are time (no date part) values, also the format thatsomeString?time
will use to parse strings.void
setTimeZone(TimeZone timeZone)
Sets the time zone to use when formatting date/time values.protected TemplateException
settingValueAssignmentException(String name, String value, Throwable cause)
void
setURLEscapingCharset(String urlEscapingCharset)
Sets the URL escaping charset.protected TemplateException
unknownSettingException(String name)
Creates the exception that should be thrown when a setting name isn't recognized.
-
-
-
Field Detail
-
LOCALE_KEY_SNAKE_CASE
public static final String LOCALE_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
LOCALE_KEY_CAMEL_CASE
public static final String LOCALE_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
LOCALE_KEY
public static final String LOCALE_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
NUMBER_FORMAT_KEY_SNAKE_CASE
public static final String NUMBER_FORMAT_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
NUMBER_FORMAT_KEY_CAMEL_CASE
public static final String NUMBER_FORMAT_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
NUMBER_FORMAT_KEY
public static final String NUMBER_FORMAT_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
TIME_FORMAT_KEY_SNAKE_CASE
public static final String TIME_FORMAT_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
TIME_FORMAT_KEY_CAMEL_CASE
public static final String TIME_FORMAT_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
TIME_FORMAT_KEY
public static final String TIME_FORMAT_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
DATE_FORMAT_KEY_SNAKE_CASE
public static final String DATE_FORMAT_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
DATE_FORMAT_KEY_CAMEL_CASE
public static final String DATE_FORMAT_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
DATE_FORMAT_KEY
public static final String DATE_FORMAT_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
DATETIME_FORMAT_KEY_SNAKE_CASE
public static final String DATETIME_FORMAT_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
DATETIME_FORMAT_KEY_CAMEL_CASE
public static final String DATETIME_FORMAT_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
DATETIME_FORMAT_KEY
public static final String DATETIME_FORMAT_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
TIME_ZONE_KEY_SNAKE_CASE
public static final String TIME_ZONE_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
TIME_ZONE_KEY_CAMEL_CASE
public static final String TIME_ZONE_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
TIME_ZONE_KEY
public static final String TIME_ZONE_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
SQL_DATE_AND_TIME_TIME_ZONE_KEY_SNAKE_CASE
public static final String SQL_DATE_AND_TIME_TIME_ZONE_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
SQL_DATE_AND_TIME_TIME_ZONE_KEY_CAMEL_CASE
public static final String SQL_DATE_AND_TIME_TIME_ZONE_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
SQL_DATE_AND_TIME_TIME_ZONE_KEY
public static final String SQL_DATE_AND_TIME_TIME_ZONE_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
CLASSIC_COMPATIBLE_KEY_SNAKE_CASE
public static final String CLASSIC_COMPATIBLE_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
CLASSIC_COMPATIBLE_KEY_CAMEL_CASE
public static final String CLASSIC_COMPATIBLE_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
CLASSIC_COMPATIBLE_KEY
public static final String CLASSIC_COMPATIBLE_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
TEMPLATE_EXCEPTION_HANDLER_KEY_SNAKE_CASE
public static final String TEMPLATE_EXCEPTION_HANDLER_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
TEMPLATE_EXCEPTION_HANDLER_KEY_CAMEL_CASE
public static final String TEMPLATE_EXCEPTION_HANDLER_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
TEMPLATE_EXCEPTION_HANDLER_KEY
public static final String TEMPLATE_EXCEPTION_HANDLER_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
ARITHMETIC_ENGINE_KEY_SNAKE_CASE
public static final String ARITHMETIC_ENGINE_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
ARITHMETIC_ENGINE_KEY_CAMEL_CASE
public static final String ARITHMETIC_ENGINE_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
ARITHMETIC_ENGINE_KEY
public static final String ARITHMETIC_ENGINE_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
OBJECT_WRAPPER_KEY_SNAKE_CASE
public static final String OBJECT_WRAPPER_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
OBJECT_WRAPPER_KEY_CAMEL_CASE
public static final String OBJECT_WRAPPER_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
OBJECT_WRAPPER_KEY
public static final String OBJECT_WRAPPER_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
BOOLEAN_FORMAT_KEY_SNAKE_CASE
public static final String BOOLEAN_FORMAT_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
BOOLEAN_FORMAT_KEY_CAMEL_CASE
public static final String BOOLEAN_FORMAT_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
BOOLEAN_FORMAT_KEY
public static final String BOOLEAN_FORMAT_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
OUTPUT_ENCODING_KEY_SNAKE_CASE
public static final String OUTPUT_ENCODING_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
OUTPUT_ENCODING_KEY_CAMEL_CASE
public static final String OUTPUT_ENCODING_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
OUTPUT_ENCODING_KEY
public static final String OUTPUT_ENCODING_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
URL_ESCAPING_CHARSET_KEY_SNAKE_CASE
public static final String URL_ESCAPING_CHARSET_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
URL_ESCAPING_CHARSET_KEY_CAMEL_CASE
public static final String URL_ESCAPING_CHARSET_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
URL_ESCAPING_CHARSET_KEY
public static final String URL_ESCAPING_CHARSET_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints.- See Also:
- Constant Field Values
-
STRICT_BEAN_MODELS_KEY_SNAKE_CASE
public static final String STRICT_BEAN_MODELS_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
STRICT_BEAN_MODELS_KEY_CAMEL_CASE
public static final String STRICT_BEAN_MODELS_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
STRICT_BEAN_MODELS_KEY
public static final String STRICT_BEAN_MODELS_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints. @since 2.3.22- See Also:
- Constant Field Values
-
AUTO_FLUSH_KEY_SNAKE_CASE
public static final String AUTO_FLUSH_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
AUTO_FLUSH_KEY_CAMEL_CASE
public static final String AUTO_FLUSH_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
AUTO_FLUSH_KEY
public static final String AUTO_FLUSH_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints. @since 2.3.17- See Also:
- Constant Field Values
-
NEW_BUILTIN_CLASS_RESOLVER_KEY_SNAKE_CASE
public static final String NEW_BUILTIN_CLASS_RESOLVER_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
NEW_BUILTIN_CLASS_RESOLVER_KEY_CAMEL_CASE
public static final String NEW_BUILTIN_CLASS_RESOLVER_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
NEW_BUILTIN_CLASS_RESOLVER_KEY
public static final String NEW_BUILTIN_CLASS_RESOLVER_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints. @since 2.3.17- See Also:
- Constant Field Values
-
SHOW_ERROR_TIPS_KEY_SNAKE_CASE
public static final String SHOW_ERROR_TIPS_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
SHOW_ERROR_TIPS_KEY_CAMEL_CASE
public static final String SHOW_ERROR_TIPS_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
SHOW_ERROR_TIPS_KEY
public static final String SHOW_ERROR_TIPS_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints. @since 2.3.21- See Also:
- Constant Field Values
-
API_BUILTIN_ENABLED_KEY_SNAKE_CASE
public static final String API_BUILTIN_ENABLED_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
API_BUILTIN_ENABLED_KEY_CAMEL_CASE
public static final String API_BUILTIN_ENABLED_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
API_BUILTIN_ENABLED_KEY
public static final String API_BUILTIN_ENABLED_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints. @since 2.3.22- See Also:
- Constant Field Values
-
LOG_TEMPLATE_EXCEPTIONS_KEY_SNAKE_CASE
public static final String LOG_TEMPLATE_EXCEPTIONS_KEY_SNAKE_CASE
Legacy, snake case (like_this
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
LOG_TEMPLATE_EXCEPTIONS_KEY_CAMEL_CASE
public static final String LOG_TEMPLATE_EXCEPTIONS_KEY_CAMEL_CASE
Modern, camel case (likeThis
) variation of the setting name. @since 2.3.23- See Also:
- Constant Field Values
-
LOG_TEMPLATE_EXCEPTIONS_KEY
public static final String LOG_TEMPLATE_EXCEPTIONS_KEY
Alias to the..._SNAKE_CASE
variation due to backward compatibility constraints. @since 2.3.22- See Also:
- Constant Field Values
-
STRICT_BEAN_MODELS
public static final String STRICT_BEAN_MODELS
Deprecated.UseSTRICT_BEAN_MODELS_KEY
instead.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
Configurable
public Configurable()
Deprecated.This shouldn't even be public; don't use it.Creates a top-level configurable, one that doesn't inherit from a parent, and thus stores the default values.
-
Configurable
protected Configurable(Version incompatibleImprovements)
Intended to be called from inside FreeMarker only. Creates a top-level configurable, one that doesn't inherit from a parent, and thus stores the default values. Called by theConfiguration
constructor.
-
Configurable
public Configurable(Configurable parent)
Creates a new instance. Normally you do not need to use this constructor, as you don't useConfigurable
directly, but its subclasses.
-
-
Method Detail
-
clone
protected Object clone() throws CloneNotSupportedException
- Overrides:
clone
in classObject
- Throws:
CloneNotSupportedException
-
getParent
public final Configurable getParent()
Returns the parentConfigurable
object of this object. The parent stores the default setting values for thisConfigurable
. For example, the parent of aTemplate
object is aConfiguration
object, so values not specified onTemplate
-level are get from theConfiguration
object.Note on the parent of
Environment
: If you setincompatible_improvements
to at least 2.3.22, it will be always the "main"Template
, that is, the template for whose processing theEnvironment
was created. With lowerincompatible_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 whichTemplate
the parent ofEnvironment
is during template execution, unless you setincompatible_improvements
to 2.3.22 or higher.- Returns:
- The parent
Configurable
object, ornull
if this is the rootConfigurable
object (i.e, if it's theConfiguration
object).
-
setClassicCompatible
public void setClassicCompatible(boolean classicCompatibility)
Toggles the "Classic Compatible" mode. For a comprehensive description of this mode, seeisClassicCompatible()
.
-
setClassicCompatibleAsInt
public void setClassicCompatibleAsInt(int classicCompatibility)
Same assetClassicCompatible(boolean)
, but allows some extra values.- Parameters:
classicCompatibility
-0
meansfalse
,1
meanstrue
,2
meanstrue
but with emulating bugs in early 2.x classic-compatibility mode. Currently2
affects how booleans are converted to string; with1
it's always"true"
/""
, but with2
it's"true"
/"false"
for values wrapped byBeansWrapper
as thenBoolean.toString()
prevails. Note thatsomeBoolean?string
will always consistently format the boolean according theboolean_format
setting, just like in FreeMarker 2.3 and later.
-
isClassicCompatible
public boolean isClassicCompatible()
Returns whether the engine runs in the "Classic Compatibile" mode. When this mode is active, the engine behavior is altered in following way: (these resemble the behavior of the 1.7.x line of FreeMarker engine, now named "FreeMarker Classic", hence the name).- handle undefined expressions gracefully. Namely when an expression
"expr" evaluates to null:
- in <assign varname=expr> directive, or in ${expr} directive, or in otherexpr == expr, or in otherexpr != expr, or in hash[expr], or in expr[keyOrIndex] (since 2.3.20), or in expr.key (since 2.3.20), then it's treated as empty string.
- as argument of <list expr as item> or <foreach item in expr>, the loop body is not executed (as if it were a 0-length list)
- as argument of <if> directive, or on other places where a boolean expression is expected, it's treated as false
- Non-boolean models are accepted in <if> directive, or as operands of logical operators. "Empty" models (zero-length string, empty sequence or hash) are evaluated as false, all others are evaluated as true.
- When boolean value is treated as a string (i.e. output in ${...} directive, or concatenated with other string), true values are converted to string "true", false values are converted to empty string. Except, if the value of the setting is 2, it will be formatted according the boolean_format setting, just like in 2.3.20 and later.
- Scalar models supplied to <list> and <foreach> are treated as a one-element list consisting of the passed model.
- Paths parameter of <include> will be interpreted as absolute path.
- handle undefined expressions gracefully. Namely when an expression
"expr" evaluates to null:
-
getClassicCompatibleAsInt
public int getClassicCompatibleAsInt()
-
setLocale
public void setLocale(Locale locale)
Sets the default locale used for number and date formatting (among others), also the locale used for searching localized template variations when no locale was explicitly requested.
-
getTimeZone
public TimeZone getTimeZone()
The getter pair ofsetTimeZone(TimeZone)
.
-
setTimeZone
public void setTimeZone(TimeZone timeZone)
Sets the time zone to use when formatting date/time values. Defaults to the system time zone (TimeZone.getDefault()
), regardless of the "locale" FreeMarker setting, so in a server application you probably want to set it explicitly in theEnvironment
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)
!- See Also:
setSQLDateAndTimeTimeZone(TimeZone)
-
setSQLDateAndTimeTimeZone
public void setSQLDateAndTimeTimeZone(TimeZone tz)
Sets the time zone used when dealing withjava.sql.Date
andjava.sql.Time
values. It defaults tonull
for backward compatibility, but in most application 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 thejava.sql.Date
andjava.sql.Time
values. If this setting isnull
, FreeMarker will use the value of (getTimeZone()
) forjava.sql.Date
andjava.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 plainjava.util.Date
values).To decide what value you need, a few things has to be understood:
- Date-only and time-only values in SQL-oriented databases are usually store calendar and clock field values directly (year, month, day, or hour, minute, seconds (with decimals)), as opposed to a set of points on the physical time line. Thus, unlike SQL timestamps, these values usually aren't meant to be shown differently depending on the time zone of the audience.
- When a JDBC query has to return a date-only or time-only value, it has to convert it to a point on the
physical time line, because that's what
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 in the database. (This used to be the default behavior of ORM-s, like Hibernate, too.) - The value of the
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 callsEnvironment.setTimeZone(TimeZone)
with that time zone. Thus, the visitor will seejava.sql.Timestamp
and plainjava.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. Whensql_date_and_time_time_zone
isnull
,time_zone
is used for rendering all kind of date/time/dateTime values, includingjava.sql.Date
andjava.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 probably was meant to shown "as is". - You may wonder why this setting isn't simply "SQL time zone", since the time zone related behavior of JDBC
applies to
java.sql.Timestamp
too. FreeMarker assumes that you have set up your application so that time stamps coming from the database go through the necessary conversion to store the correct distance from the epoch (1970-01-01 00:00:00 UTC), as requested byDate
. In that case the time stamp can be safely rendered in different time zones, and thus it needs no special treatment.
- Parameters:
tz
- Maybenull
, in which casejava.sql.Date
andjava.sql.Time
values will be formatted in the time zone returned bygetTimeZone()
. (Note that sincenull
is an allowed value for this setting, it will not causegetSQLDateAndTimeTimeZone()
to fall back to the parent configuration.)- Since:
- 2.3.21
- See Also:
setTimeZone(TimeZone)
-
getSQLDateAndTimeTimeZone
public TimeZone getSQLDateAndTimeTimeZone()
The getter pair ofsetSQLDateAndTimeTimeZone(TimeZone)
.- Returns:
null
if the value ofgetTimeZone()
should be used for formattingjava.sql.Date
andjava.sql.Time
values, otherwise the time zone that should be used to format the values of those two types.- Since:
- 2.3.21
-
getLocale
public Locale getLocale()
Returns the assumed locale when searching for template files with no explicit requested locale. Defaults to system locale.
-
setNumberFormat
public void setNumberFormat(String numberFormat)
Sets the default number format used to convert numbers to strings. Currently, this is either aDecimalFormat
pattern (like"0.##"
), or one of the following special values:"number"
: The number format returned byNumberFormat.getNumberInstance(Locale)
"currency"
: The number format returned byNumberFormat.getCurrencyInstance(Locale)
"percent"
: The number format returned byNumberFormat.getPercentInstance(Locale)
"computer"
: The number format used by FTL'sc
built-in (like insomeNumber?c
).
Defaults to "number".
-
getNumberFormat
public String getNumberFormat()
Getter pair ofsetNumberFormat(String)
.
-
setBooleanFormat
public void setBooleanFormat(String booleanFormat)
The string value for the booleantrue
andfalse
values, intended for human audience (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").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), onlymyBool?string
will allow it, which is deprecated since FreeMarker 2.3.20.Note that automatic boolean-to-string conversion only exists since FreeMarker 2.3.20. Earlier this setting only influenced the result of
myBool?string
.
-
getBooleanFormat
public String getBooleanFormat()
The getter pair ofsetBooleanFormat(String)
.
-
setTimeFormat
public void setTimeFormat(String timeFormat)
Sets the format used to convertDate
-s to string-s that are time (no date part) values, also the format thatsomeString?time
will use to parse strings.For the possible values see
setDateTimeFormat(String)
.Defaults to
""
, which means "use the FreeMarker default", which is currently"medium"
.
-
getTimeFormat
public String getTimeFormat()
The getter pair ofsetTimeFormat(String)
.
-
setDateFormat
public void setDateFormat(String dateFormat)
Sets the format used to convertDate
-s to string-s that are date (no time part) values, also the format thatsomeString?date
will use to parse strings.For the possible values see
setDateTimeFormat(String)
.Defaults to
""
, which means "use the FreeMarker default", which is currently"code"
.
-
getDateFormat
public String getDateFormat()
The getter pair ofsetDateFormat(String)
.
-
setDateTimeFormat
public void setDateTimeFormat(String dateTimeFormat)
Sets the format used to convertDate
-s to string-s that are date-time (timestamp) values, also the format thatsomeString?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"
(whereHH
means 24 hours format) or"MM/dd/yyyy hh:mm:ss a"
(wherea
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 likelastModified?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), like13:45:05
m
= Minutes, like13:45
. This isn't allowed for "xs".
h
= Hours, like13
. 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 forjava.sql.Date
andjava.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 forjava.sql.Date
andjava.sql.Time
, and for"iso"
date values.Time zone options:
u
= Use UTC instead of what thetime_zone
setting suggests. However,java.sql.Date
andjava.sql.Time
aren't affected by this (seesetSQLDateAndTimeTimeZone(TimeZone)
to understand why)
fu
= "Force UTC", that is, use UTC instead of what thetime_zone
or thesql_date_and_time_time_zone
setting suggests. This also effectsjava.sql.Date
andjava.sql.Time
values
Neither = Use the time zone suggested by thetime_zone
or thesql_date_and_time_time_zone
configuration setting (setTimeZone(TimeZone)
andsetSQLDateAndTimeTimeZone(TimeZone)
).
The options can be specified in any order.
Options from the same category are mutually exclusive, like using
m
ands
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, like20141225T235018
. 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 ofDateFormat
). 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.)
Defaults to
""
, which means "use the FreeMarker default", which is currently"code"
.
-
getDateTimeFormat
public String getDateTimeFormat()
The getter pair ofsetDateTimeFormat(String)
.
-
setTemplateExceptionHandler
public void setTemplateExceptionHandler(TemplateExceptionHandler templateExceptionHandler)
Sets the exception handler used to handle exceptions occurring inside templates. The default isTemplateExceptionHandler.DEBUG_HANDLER
. The recommended values are:- In production systems:
TemplateExceptionHandler.RETHROW_HANDLER
- During development of HTML templates:
TemplateExceptionHandler.HTML_DEBUG_HANDLER
- During development of non-HTML templates:
TemplateExceptionHandler.DEBUG_HANDLER
All of these will let the exception propagate further, so that you can catch it around
Template.process(Object, Writer)
for example. The difference is in what they print on the output before they do that.Note that the
TemplateExceptionHandler
is not meant to be used for generating HTTP error pages. Neither is it meant to be used to roll back the printed output. These should be solved outside template processing when the exception raises fromTemplate.process
.TemplateExceptionHandler
meant to be used if you want to include special content in the template output, or if you want to suppress certain exceptions. - In production systems:
-
getTemplateExceptionHandler
public TemplateExceptionHandler getTemplateExceptionHandler()
The getter pair ofsetTemplateExceptionHandler(TemplateExceptionHandler)
.
-
setArithmeticEngine
public void setArithmeticEngine(ArithmeticEngine arithmeticEngine)
Sets the arithmetic engine used to perform arithmetic operations. The default isArithmeticEngine.BIGDECIMAL_ENGINE
.
-
getArithmeticEngine
public ArithmeticEngine getArithmeticEngine()
The getter pair ofsetArithmeticEngine(ArithmeticEngine)
.
-
setObjectWrapper
public void setObjectWrapper(ObjectWrapper objectWrapper)
Sets the object wrapper used to wrap objects toTemplateModel
-s. The default isObjectWrapper.DEFAULT_WRAPPER
.
-
getObjectWrapper
public ObjectWrapper getObjectWrapper()
The getter pair ofsetObjectWrapper(ObjectWrapper)
.
-
setOutputEncoding
public void setOutputEncoding(String outputEncoding)
Informs FreeMarker about the charset used for the output. As FreeMarker outputs character stream (not byte stream), it's not aware of the output charset unless the software that encloses it tells it with this setting. Some templates may use FreeMarker features that require this information. Setting this tonull
means that the output encoding is not known.Defaults to
null
(unknown).
-
getOutputEncoding
public String getOutputEncoding()
-
setURLEscapingCharset
public void setURLEscapingCharset(String urlEscapingCharset)
Sets the URL escaping charset. If not set (null
), the output encoding (setOutputEncoding(String)
) will be used for URL escaping. Defaults tonull
.
-
getURLEscapingCharset
public String getURLEscapingCharset()
-
setNewBuiltinClassResolver
public void setNewBuiltinClassResolver(TemplateClassResolver newBuiltinClassResolver)
Sets theTemplateClassResolver
that is used when thenew
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 isTemplateClassResolver.UNRESTRICTED_RESOLVER
in FreeMarker 2.3.x, andTemplateClassResolver.SAFER_RESOLVER
starting from FreeMarker 2.4.0. If you allow users to upload templates, it's important to use a custom restrictiveTemplateClassResolver
.- Since:
- 2.3.17
-
getNewBuiltinClassResolver
public TemplateClassResolver getNewBuiltinClassResolver()
Retrieves theTemplateClassResolver
used to resolve classes when "SomeClassName"?new is called in a template.- Since:
- 2.3.17
-
setAutoFlush
public void setAutoFlush(boolean autoFlush)
Sets whether the outputWriter
is automatically flushed at the end ofTemplate.process(Object, Writer)
(and its overloads). The default istrue
.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 separateTemplate.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.- Since:
- 2.3.17
-
getAutoFlush
public boolean getAutoFlush()
- Since:
- 2.3.17
-
setShowErrorTips
public void setShowErrorTips(boolean showTips)
Sets if tips should be shown in error messages of errors arising during template processing. The default istrue
.- Since:
- 2.3.21
-
getShowErrorTips
public boolean getShowErrorTips()
- Since:
- 2.3.21
-
setAPIBuiltinEnabled
public void setAPIBuiltinEnabled(boolean value)
Specifies if?api
can be used in templates. Defaults tofalse
so that updating FreeMarker won't decrease the security of existing applications.- Since:
- 2.3.22
-
isAPIBuiltinEnabled
public boolean isAPIBuiltinEnabled()
- Since:
- 2.3.22
-
setLogTemplateExceptions
public void setLogTemplateExceptions(boolean value)
Specifies ifTemplateException
-s thrown by template processing are logged by FreeMarker or not. The default istrue
for backward compatibility, but that results in logging the exception twice in properly written applications, because there theTemplateException
thrown by the public FreeMarker API is also logged by the caller (even if only as the cause exception of a higher level exception). Hence, in modern applications it should be set tofalse
. Note that this setting has no effect on the logging of exceptions caught by#attempt
; those are always logged, no mater what (because those exceptions won't bubble up until the API caller).- Since:
- 2.3.22
-
getLogTemplateExceptions
public boolean getLogTemplateExceptions()
- Since:
- 2.3.22
-
setSetting
public void setSetting(String name, String value) throws TemplateException
Sets a FreeMarker setting by a name and string value. If you can configure FreeMarker directly with Java (or other programming language), you should use the dedicated setter methods instead (likesetObjectWrapper(ObjectWrapper)
. This meant to be used if you get the settings from somewhere as text. Regardless, below you will find an overview of the settings available no matter how you set them.Note: As of FreeMarker 2.3.23, setting names can be written in camel case too. For example, instead of
date_format
you can also usedateFormat
. It's likely that camel case will become to the recommended convention in the future.The list of settings commonly supported in all
Configurable
subclasses:"locale"
: SeesetLocale(Locale)
.
String value: local codes with the usual format in Java, such as"en_US"
."classic_compatible"
: SeesetClassicCompatible(boolean)
andsetClassicCompatibleAsInt(int)
.
String value:"true"
,"false"
, also since 2.3.200
or1
or2
. (Also accepts"yes"
,"no"
,"t"
,"f"
,"y"
,"n"
.) Case insensitive."template_exception_handler"
: SeesetTemplateExceptionHandler(TemplateExceptionHandler)
.
String value: If the value contains dot, then it's interpreted as an object builder expression. If the value does not contain dot, then it must be one of these predefined values (case insensitive):"rethrow"
(meansTemplateExceptionHandler.RETHROW_HANDLER
),"debug"
(meansTemplateExceptionHandler.DEBUG_HANDLER
),"html_debug"
(meansTemplateExceptionHandler.HTML_DEBUG_HANDLER
),"ignore"
(meansTemplateExceptionHandler.IGNORE_HANDLER
),"default"
(only allowed forConfiguration
instances) for the default."arithmetic_engine"
: SeesetArithmeticEngine(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"
: SeesetObjectWrapper(ObjectWrapper)
.
String value: If the value contains dot, then it's interpreted as an object builder expression, with the addition thatBeansWrapper
,DefaultObjectWrapper
andSimpleObjectWrapper
can be referred without package name. For example, these strings are valid values:"DefaultObjectWrapper(2.3.21)"
,"BeansWrapper(2.3.21, simpleMapWrapper=true)"
.
If the value does not contain dot, then it must be one of these special values (case insensitive):"default"
means the default ofConfiguration
(the default depends on theConfiguration#Configuration(Version) incompatible_improvements
, but a bug existed in 2.3.21 where that was ignored),"default_2_3_0"
(means the deprecatedObjectWrapper.DEFAULT_WRAPPER
)"simple"
(means the deprecatedObjectWrapper.SIMPLE_WRAPPER
),"beans"
(means the deprecatedObjectWrapper.BEANS_WRAPPER
orBeansWrapperBuilder.build()
),"jython"
(meansObjectWrapper.DEFAULT_WRAPPER
)"number_format"
: SeesetNumberFormat(String)
."boolean_format"
: SeesetBooleanFormat(String)
."date_format", "time_format", "datetime_format"
: SeesetDateFormat(String)
,setTimeFormat(String)
,setDateTimeFormat(String)
."time_zone"
: SeesetTimeZone(TimeZone)
.
String value: With the format asTimeZone.getTimeZone(java.lang.String)
defines it. Also, since 2.3.21"JVM default"
can be used that will be replaced with the actual JVM default time zone whensetSetting(String, String)
is called. For example"GMT-8:00"
or"America/Los_Angeles"
If you set this setting, consider settingsql_date_and_time_time_zone
too (see below)!sql_date_and_time_time_zone
: SeesetSQLDateAndTimeTimeZone(TimeZone)
. Since 2.3.21.
String value: With the format asTimeZone.getTimeZone(java.lang.String)
defines it. Also,"JVM default"
can be used that will be replaced with the actual JVM default time zone whensetSetting(String, String)
is called. Also"null"
can be used, which has the same effect assetSQLDateAndTimeTimeZone(null)
."output_encoding"
: SeesetOutputEncoding(String)
."url_escaping_charset"
: SeesetURLEscapingCharset(String)
."auto_flush"
: SeesetAutoFlush(boolean)
. Since 2.3.17.
String value:"true"
,"false"
,"y"
, etc."new_builtin_class_resolver"
: SeesetNewBuiltinClassResolver(TemplateClassResolver)
. Since 2.3.17. The value must be one of these (ignore the quotation marks):"unrestricted"
: UseTemplateClassResolver.UNRESTRICTED_RESOLVER
"safer"
: UseTemplateClassResolver.SAFER_RESOLVER
"allows_nothing"
: UseTemplateClassResolver.ALLOWS_NOTHING_RESOLVER
Something that contains colon will use
OptInTemplateClassResolver
and is expected to store comma separated values (possibly quoted) segmented with"allowed_classes:"
and/or"trusted_templates:"
. Examples of valid values:Setting value Meaning allowed_classes: com.example.C1, com.example.C2, trusted_templates: lib/*, safe.ftl
Only allow instantiating the com.example.C1
andcom.example.C2
classes. But, allow templates within thelib/
directory (likelib/foo/bar.ftl
) and templatesafe.ftl
(that does not matchfoo/safe.ftl
, only exactlysafe.ftl
) to instantiate anything thatTemplateClassResolver.SAFER_RESOLVER
allows.allowed_classes: com.example.C1, com.example.C2
Only allow instantiating the com.example.C1
andcom.example.C2
classes. There are no trusted templates.trusted_templates: lib/*, safe.ftl
Do not allow instantiating any classes, except in templates inside lib/
or in templatesafe.ftl
.For more details see
OptInTemplateClassResolver
.Otherwise if the value contains dot, it's interpreted as an object builder expression.
"show_error_tips"
: SeesetShowErrorTips(boolean)
. Since 2.3.21.
String value:"true"
,"false"
,"y"
, etc.api_builtin_enabled
: SeesetAPIBuiltinEnabled(boolean)
. Since 2.3.22.
String value:"true"
,"false"
,"y"
, etc.
Configuration
(a subclass ofConfigurable
) also understands these:"auto_import"
: SeeConfiguration.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. SeeConfiguration.setAutoIncludes(List)
String value is something like:/include/common.ftl, "/include/evil name.ftl"
"default_encoding"
: SeeConfiguration.setDefaultEncoding(String)
.
As the default value is the system default, which can change from one server to another, you should always set this!"localized_lookup"
: SeeConfiguration.setLocalizedLookup(boolean)
.
String value:"true"
,"false"
(also the equivalents:"yes"
,"no"
,"t"
,"f"
,"y"
,"n"
). Case insensitive."strict_syntax"
: SeeConfiguration.setStrictSyntaxMode(boolean)
. Deprecated.
String value:"true"
,"false"
,yes
, etc."whitespace_stripping"
: SeeConfiguration.setWhitespaceStripping(boolean)
.
String value:"true"
,"false"
,yes
, etc."cache_storage"
: SeeConfiguration.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 aMruCacheStorage
will be used with the maximum strong and soft sizes specified with the setting value. Examples of valid setting values:Setting value max. strong size max. soft size "strong:50, soft:500"
50 500 "strong:100, soft"
100 Integer.MAX_VALUE
"strong:100"
100 0 "soft:100"
0 100 "strong"
Integer.MAX_VALUE
0 "soft"
0 Integer.MAX_VALUE
The value is not case sensitive. The order of soft and strong entries is not significant.
"template_update_delay"
: Template update delay in seconds (not in milliseconds) if no unit is specified; seeConfiguration.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"
: SeeConfiguration.setTagSyntax(int)
.
String value: Must be one of"auto_detect"
,"angle_bracket"
, and"square_bracket"
."naming_convention"
: SeeConfiguration.setNamingConvention(int)
.
String value: Must be one of"auto_detect"
,"legacy"
, and"camel_case"
."incompatible_improvements"
: SeeConfiguration.setIncompatibleImprovements(Version)
.
String value: version number like2.3.20
."incompatible_enhancements"
: See:Configuration.setIncompatibleEnhancements(String)
. This setting name is deprecated, use"incompatible_improvements"
instead."template_loader"
: See:Configuration.setTemplateLoader(TemplateLoader)
.
String value:"default"
(case insensitive) for the default, or else interpreted as an object builder expression."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"
forTemplateNameFormat.DEFAULT_2_3_0
,"default_2_4_0"
forTemplateNameFormat.DEFAULT_2_4_0
.
Regarding object builder expressions (used by the setting values where it was indicated):
Before FreeMarker 2.3.21 it had to be a fully qualified class name, and nothing else.
Since 2.3.21, the generic syntax is: className(constrArg1, constrArg2, ... constrArgN, propName1=propValue1, propName2=propValue2, ... propNameN=propValueN), where className is the fully qualified class name of the instance to create (except if we have builder class or INSTANCE field around, but see that later), constrArg-s are the values of constructor arguments, and propName=propValue-s set JavaBean properties (like x=1 means setX(1)) on the created instance. You can have any number of constructor arguments and property setters, including 0. Constructor arguments must precede any property setters.
- Example: com.example.MyObjectWrapper(1, 2, exposeFields=true, cacheSize=5000) is nearly equivalent with this Java code: obj = new com.example.MyObjectWrapper(1, 2); obj.setExposeFields(true); obj.setCacheSize(5000);
-
If you have no constructor arguments and property setters, and the className class has a public static
INSTANCE
field, the value of that filed will be the value of the expression, and the constructor won't be called. Note that if you use the backward compatible syntax, where these's no parenthesis after the class name, then it will not look forINSTANCE
. -
If there exists a class named classNameBuilder, then that class will be instantiated instead with the given constructor arguments, and the JavaBean properties of that builder instance will be set. After that, the public build() method of the instance will be called, whose return value will be the value of the whole expression. (The builder class and the build() method is simply found by name, there's no special interface to implement.) Note that if you use the backward compatible syntax, where these's no parenthesis after the class name, then it will not look for builder class.
-
Currently, the values of arguments and properties can only be one of these:
- A numerical literal, like
123
or-1.5
. Like in FTL, there are no numerical types, the value will be automatically converted to the type of the target. - A boolean literal:
true
orfalse
- The null literal:
null
- A string literal with FTL syntax, except that it can't contain ${...}-s and
#{...}-s. Examples:
"Line 1\nLine 2"
orr"C:\temp"
. - An object builder expression. That is, object builder expressions can be nested into each other.
- A numerical literal, like
-
The top-level object builder expressions may omit
()
. In that case, for backward compatibility, theINSTANCE
field and the builder class is not searched, so the instance will be always created with its parameterless constructor. (This behavior will possibly change in 2.4.) The()
can't be omitted for nested expressions. -
The classes and methods that the expression meant to access must be all public.
- Parameters:
name
- the name of the setting.value
- the string that describes the new value of the setting.- Throws:
Configurable.UnknownSettingException
- if the name is wrong.TemplateException
- if the new value of the setting can't be set for any other reasons.
-
setStrictBeanModels
public void setStrictBeanModels(boolean strict)
-
getSetting
public String getSetting(String key)
Deprecated.It's not possible in general to convert setting values to string, and thus it's impossible to ensure thatsetSetting(String, String)
will work with the returned value correctly.Returns the textual representation of a setting.- Parameters:
key
- the setting key. Can be any of standard XXX_KEY constants, or a custom key.
-
getSettings
public 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 thatsetSettings(Properties)
will work with them correctly.)This meant to return the String-to-StringMap
of the settings. So it actually should return aProperties
object, but it doesn't by mistake. The returnedMap
is read-only, but it will reflect the further configuration changes (aliasing effect).
-
getEnvironment
protected Environment getEnvironment()
-
unknownSettingException
protected TemplateException unknownSettingException(String name)
Creates the exception that should be thrown when a setting name isn't recognized.
-
getCorrectedNameForUnknownSetting
protected String getCorrectedNameForUnknownSetting(String name)
- Parameters:
name
- The wrong name- Returns:
- The corrected name, or
null
if there's no known correction - Since:
- 2.3.21
-
settingValueAssignmentException
protected TemplateException settingValueAssignmentException(String name, String value, Throwable cause)
- Since:
- 2.3.21
-
invalidSettingValueException
protected TemplateException invalidSettingValueException(String name, String value)
-
setSettings
public void setSettings(Properties props) throws TemplateException
Set the settings stored in aProperties
object.- Throws:
TemplateException
- if theProperties
object contains invalid keys, or invalid setting values, or any other error occurs while changing the settings.
-
setSettings
public void setSettings(InputStream propsIn) throws TemplateException, IOException
Reads a setting list (key and element pairs) from the input stream. The stream has to follow the usual.properties
format.- Throws:
TemplateException
- if the stream contains invalid keys, or invalid setting values, or any other error occurs while changing the settings.IOException
- if an error occurred when reading from the input stream.
-
setCustomAttribute
public void setCustomAttribute(String name, Object value)
Sets a named custom attribute for this configurable.- Parameters:
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, seeremoveCustomAttribute(String)
.
-
getCustomAttributeNames
public String[] getCustomAttributeNames()
Returns an array with names of all custom attributes defined directly on this configurable. (That is, it doesn't contain the names of custom attributes defined indirectly on its parent configurables.) The returned array is never null, but can be zero-length. The order of elements in the returned array is not defined and can change between invocations.
-
removeCustomAttribute
public void removeCustomAttribute(String name)
Removes a named custom attribute for this configurable. Note that this is different than setting the custom attribute value to null. If you set the value to null,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).- Parameters:
name
- the name of the custom attribute
-
getCustomAttribute
public Object getCustomAttribute(String name)
Retrieves a named custom attribute for this configurable. If the attribute is not present in the configurable, and the configurable has a parent, then the parent is looked up as well.- Parameters:
name
- the name of the custom attribute- Returns:
- the value of the custom attribute. Note that if the custom attribute
was created with <#ftl attributes={...}>, then this value is already
unwrapped (i.e. it's a
String
, or aList
, or aMap
, ...etc., not a FreeMarker specific class).
-
doAutoImportsAndIncludes
protected void doAutoImportsAndIncludes(Environment env) throws TemplateException, IOException
- Throws:
TemplateException
IOException
-
parseAsList
protected ArrayList parseAsList(String text) throws ParseException
- Throws:
ParseException
-
parseAsSegmentedList
protected ArrayList parseAsSegmentedList(String text) throws ParseException
- Throws:
ParseException
-
parseAsImportList
protected HashMap parseAsImportList(String text) throws ParseException
- Throws:
ParseException
-
-