This is a common superclass of
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.
ARITHMETIC_ENGINE_KEY
public static final String ARITHMETIC_ENGINE_KEY
BOOLEAN_FORMAT_KEY
public static final String BOOLEAN_FORMAT_KEY
CLASSIC_COMPATIBLE_KEY
public static final String CLASSIC_COMPATIBLE_KEY
DATETIME_FORMAT_KEY
public static final String DATETIME_FORMAT_KEY
DATE_FORMAT_KEY
public static final String DATE_FORMAT_KEY
LOCALE_KEY
public static final String LOCALE_KEY
NUMBER_FORMAT_KEY
public static final String NUMBER_FORMAT_KEY
OBJECT_WRAPPER_KEY
public static final String OBJECT_WRAPPER_KEY
OUTPUT_ENCODING_KEY
public static final String OUTPUT_ENCODING_KEY
STRICT_BEAN_MODELS
public static final String STRICT_BEAN_MODELS
TEMPLATE_EXCEPTION_HANDLER_KEY
public static final String TEMPLATE_EXCEPTION_HANDLER_KEY
TIME_FORMAT_KEY
public static final String TIME_FORMAT_KEY
TIME_ZONE_KEY
public static final String TIME_ZONE_KEY
URL_ESCAPING_CHARSET_KEY
public static final String URL_ESCAPING_CHARSET_KEY
clone
protected Object clone()
throws CloneNotSupportedException
getArithmeticEngine
public ArithmeticEngine getArithmeticEngine()
Retrieves the arithmetic engine used to perform arithmetic operations.
getBooleanFormat
public String getBooleanFormat()
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.
name
- the name of the custom attribute
- 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 a List
, or a
Map
, ...etc., not a FreeMarker specific class).
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.
getDateFormat
public String getDateFormat()
Returns the date format used to convert date models representing
date-only dates to strings.
Defaults to "date"
getDateTimeFormat
public String getDateTimeFormat()
Returns the date format used to convert date models representing datetime
dates to strings.
Defaults to "datetime"
getLocale
public Locale getLocale()
Returns the assumed locale when searching for template files with no
explicit requested locale. Defaults to system locale.
getNumberFormat
public String getNumberFormat()
Returns the default number format used to convert numbers to strings.
Defaults to "number"
getObjectWrapper
public ObjectWrapper getObjectWrapper()
Retrieves the object wrapper used to wrap objects to template models.
getOutputEncoding
public String getOutputEncoding()
getParent
public final Configurable getParent()
Returns the parent
Configurable object of this object.
The parent stores the default values for this configurable. For example,
the parent of the
Template
object is the
Configuration
object, so setting values not
specfied on template level are specified by the confuration object.
- the parent Configurable object, or null, if this is
the root Configurable object.
getSetting
public String getSetting(String key)
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
setSetting(String,String)
will work with them correctly.)
Returns the textual representation of a setting.
key
- the setting key. Can be any of standard XXX_KEY
constants, or a custom key.
getSettings
public Map getSettings()
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.)
This meant to return the String-to-String 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).
getTemplateExceptionHandler
public TemplateExceptionHandler getTemplateExceptionHandler()
Retrieves the exception handler used to handle template exceptions.
getTimeFormat
public String getTimeFormat()
Returns the date format used to convert date models representing
time-only dates to strings.
Defaults to "time"
getTimeZone
public TimeZone getTimeZone()
Returns the time zone to use when formatting time values. Defaults to
system time zone.
getURLEscapingCharset
public String getURLEscapingCharset()
invalidSettingValueException
protected TemplateException invalidSettingValueException(String name,
String value)
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:
- as argument of the <assign varname=expr> directive,
${expr} directive, otherexpr == expr or
otherexpr != expr conditional expressions, or
hash[expr] expression, then it is 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 otherwise where a
boolean expression is expected, it is 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.
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.
In all other aspects, the engine is a 2.1 engine even in compatibility
mode - you don't lose any of the new functionality by enabling it.
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).
name
- the name of the custom attribute
setArithmeticEngine
public void setArithmeticEngine(ArithmeticEngine arithmeticEngine)
Sets the arithmetic engine used to perform arithmetic operations.
setBooleanFormat
public void setBooleanFormat(String booleanFormat)
setClassicCompatible
public void setClassicCompatible(boolean classicCompatibility)
Toggles the "Classic Compatibile" mode. For a comprehensive description
of this mode, see
isClassicCompatible()
.
setCustomAttribute
public void setCustomAttribute(String name,
Object value)
Sets a named custom attribute for this configurable.
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)
.
setDateFormat
public void setDateFormat(String dateFormat)
Sets the date format used to convert date models representing date-only
dates to strings.
setDateTimeFormat
public void setDateTimeFormat(String dateTimeFormat)
Sets the date format used to convert date models representing datetime
dates to strings.
setLocale
public void setLocale(Locale locale)
Sets the locale to assume when searching for template files with no
explicit requested locale.
setNumberFormat
public void setNumberFormat(String numberFormat)
Sets the number format used to convert numbers to strings.
setObjectWrapper
public void setObjectWrapper(ObjectWrapper objectWrapper)
Sets the object wrapper used to wrap objects to template models.
setOutputEncoding
public void setOutputEncoding(String outputEncoding)
Sets the output encoding. Allows null
, which means that the
output encoding is not known.
setSetting
public void setSetting(String key,
String value)
throws TemplateException
Sets a setting by a name and string value.
List of supported names and their valid values:
"locale"
: local codes with the usual format, such as "en_US"
.
"classic_compatible"
:
"true"
, "false"
, "yes"
, "no"
,
"t"
, "f"
, "y"
, "n"
.
Case insensitive.
"template_exception_handler"
: If the value contains dot, then it is
interpreted as class name, and the object will be created with
its parameterless constructor. If the value does not contain dot,
then it must be one of these special values:
"rethrow"
, "debug"
,
"html_debug"
, "ignore"
(case insensitive).
"arithmetic_engine"
: If the value contains dot, then it is
interpreted as class name, and the object will be created with
its parameterless constructor. If the value does not contain dot,
then it must be one of these special values:
"bigdecimal"
, "conservative"
(case insensitive).
"object_wrapper"
: If the value contains dot, then it is
interpreted as class name, and the object will be created with
its parameterless constructor. If the value does not contain dot,
then it must be one of these special values:
"simple"
, "beans"
, "jython"
(case insensitive).
"number_format"
: pattern as java.text.DecimalFormat
defines.
"boolean_format"
: the textual value for boolean true and false,
separated with comma. For example "yes,no"
.
"date_format", "time_format", "datetime_format"
: patterns as
java.text.SimpleDateFormat
defines.
"time_zone"
: time zone, with the format as
java.util.TimeZone.getTimeZone
defines. For example "GMT-8:00"
or
"America/Los_Angeles"
"output_encoding"
: Informs FreeMarker about the charset
used for the output. As FreeMarker outputs character stream (not
byte stream), it is not aware of the output charset unless the
software that encloses it tells it explicitly with this setting.
Some templates may use FreeMarker features that require this.
"url_escaping_charset"
: If this setting is set, then it
overrides the value of the "output_encoding"
setting when
FreeMarker does URL encoding.
key
- the name of the setting.value
- the string that describes the new value of the setting.
TemplateException
- if the new value of the setting can't be set
for any other reasons.
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.
TemplateException
- if the stream contains
invalid keys, or invalid setting values, or any other error occurs
while changing the settings.
setSettings
public void setSettings(Properties props)
throws TemplateException
Set the settings stored in a Properties
object.
TemplateException
- if the Properties
object contains
invalid keys, or invalid setting values, or any other error occurs
while changing the settings.
setStrictBeanModels
public void setStrictBeanModels(boolean strict)
setTemplateExceptionHandler
public void setTemplateExceptionHandler(TemplateExceptionHandler templateExceptionHandler)
Sets the exception handler used to handle template exceptions.
setTimeFormat
public void setTimeFormat(String timeFormat)
Sets the date format used to convert date models representing time-only
values to strings.
setTimeZone
public void setTimeZone(TimeZone timeZone)
Sets the time zone to use when formatting time values.
setURLEscapingCharset
public void setURLEscapingCharset(String urlEscapingCharset)
Sets the URL escaping charset. Allows null
, which means that the
output encoding will be used for URL escaping.
unknownSettingException
protected TemplateException unknownSettingException(String name)