public class Configurable extends 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 String |
API_BUILTIN_ENABLED_KEY |
static String |
ARITHMETIC_ENGINE_KEY |
static String |
AUTO_FLUSH_KEY |
static String |
BOOLEAN_FORMAT_KEY |
static String |
CLASSIC_COMPATIBLE_KEY |
static String |
DATE_FORMAT_KEY |
static String |
DATETIME_FORMAT_KEY |
static String |
LOCALE_KEY |
static String |
LOG_TEMPLATE_EXCEPTIONS_KEY |
static String |
NEW_BUILTIN_CLASS_RESOLVER_KEY |
static String |
NUMBER_FORMAT_KEY |
static String |
OBJECT_WRAPPER_KEY |
static String |
OUTPUT_ENCODING_KEY |
static String |
SHOW_ERROR_TIPS_KEY |
static String |
SQL_DATE_AND_TIME_TIME_ZONE_KEY |
static String |
STRICT_BEAN_MODELS
Deprecated.
Use
STRICT_BEAN_MODELS_KEY instead. |
static String |
STRICT_BEAN_MODELS_KEY |
static String |
TEMPLATE_EXCEPTION_HANDLER_KEY |
static String |
TIME_FORMAT_KEY |
static String |
TIME_ZONE_KEY |
static String |
URL_ESCAPING_CHARSET_KEY |
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 |
---|---|
protected Object |
clone() |
protected void |
doAutoImportsAndIncludes(Environment env) |
ArithmeticEngine |
getArithmeticEngine()
The getter pair of
setArithmeticEngine(ArithmeticEngine) . |
boolean |
getAutoFlush()
|
String |
getBooleanFormat()
The getter pair of
setBooleanFormat(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 of
setDateFormat(String) . |
String |
getDateTimeFormat()
The getter pair of
setDateTimeFormat(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 the
TemplateClassResolver used
to resolve classes when "SomeClassName"?new is called in a template. |
String |
getNumberFormat()
Getter pair of
setNumberFormat(String) . |
ObjectWrapper |
getObjectWrapper()
The getter pair of
setObjectWrapper(ObjectWrapper) . |
String |
getOutputEncoding() |
Configurable |
getParent()
Returns the parent
Configurable 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 that
setSetting(String, String) will work with
the returned value correctly. |
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()
|
TimeZone |
getSQLDateAndTimeTimeZone()
The getter pair of
setSQLDateAndTimeTimeZone(TimeZone) . |
TemplateExceptionHandler |
getTemplateExceptionHandler()
The getter pair of
setTemplateExceptionHandler(TemplateExceptionHandler) . |
String |
getTimeFormat()
The getter pair of
setTimeFormat(String) . |
TimeZone |
getTimeZone()
The getter pair of
setTimeZone(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 output
Writer is automatically flushed at
the end of Template.process(Object, Writer) (and its
overloads). |
void |
setBooleanFormat(String booleanFormat)
The string value for the boolean
true and false 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 as
setClassicCompatible(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 convert
Date -s to string-s that are date (no time part) values,
also the format that someString?date will use to parse strings. |
void |
setDateTimeFormat(String dateTimeFormat)
Sets the format used to convert
Date -s to string-s that are date-time (timestamp) values,
also the format that someString?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 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(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 to
TemplateModel -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 a
Properties 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 with
java.sql.Date and
java.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 convert
Date -s to string-s that are time (no date part) values,
also the format that someString?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) |
public static final String LOCALE_KEY
public static final String NUMBER_FORMAT_KEY
public static final String TIME_FORMAT_KEY
public static final String DATE_FORMAT_KEY
public static final String DATETIME_FORMAT_KEY
public static final String TIME_ZONE_KEY
public static final String SQL_DATE_AND_TIME_TIME_ZONE_KEY
public static final String CLASSIC_COMPATIBLE_KEY
public static final String TEMPLATE_EXCEPTION_HANDLER_KEY
public static final String ARITHMETIC_ENGINE_KEY
public static final String OBJECT_WRAPPER_KEY
public static final String BOOLEAN_FORMAT_KEY
public static final String OUTPUT_ENCODING_KEY
public static final String URL_ESCAPING_CHARSET_KEY
public static final String STRICT_BEAN_MODELS
STRICT_BEAN_MODELS_KEY
instead.public static final String STRICT_BEAN_MODELS_KEY
public static final String AUTO_FLUSH_KEY
public static final String NEW_BUILTIN_CLASS_RESOLVER_KEY
public static final String SHOW_ERROR_TIPS_KEY
public static final String API_BUILTIN_ENABLED_KEY
public static final String LOG_TEMPLATE_EXCEPTIONS_KEY
public Configurable()
protected Configurable(Version incompatibleImprovements)
Configuration
constructor.public Configurable(Configurable parent)
Configurable
directly, but its subclasses.protected Object clone() throws CloneNotSupportedException
clone
in class Object
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 void setLocale(Locale locale)
public TimeZone getTimeZone()
setTimeZone(TimeZone)
.public void setTimeZone(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 void setSQLDateAndTimeTimeZone(TimeZone tz)
java.sql.Date
and
java.sql.Time
values. It defaults to null
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 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 in 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 probably was meant to shown "as is".
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 by Date
. In that case
the time stamp can be safely rendered in different time zones, and thus it needs 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 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 Locale getLocale()
public void setNumberFormat(String numberFormat)
DecimalFormat
pattern (like "0.##"
), or one of the following special values:
"number"
: The number format returned by NumberFormat.getNumberInstance(Locale)
"currency"
: The number format returned by NumberFormat.getCurrencyInstance(Locale)
"percent"
: The number format returned by NumberFormat.getPercentInstance(Locale)
"computer"
: The number format used by FTL's c
built-in (like in someNumber?c
).Defaults to "number".
public String getNumberFormat()
setNumberFormat(String)
.public void setBooleanFormat(String booleanFormat)
true
and false
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), only myBool?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
.
public String getBooleanFormat()
setBooleanFormat(String)
.public void setTimeFormat(String timeFormat)
Date
-s to string-s that are time (no date part) values,
also the format that someString?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"
.
public String getTimeFormat()
setTimeFormat(String)
.public void setDateFormat(String dateFormat)
Date
-s to string-s that are date (no time part) values,
also the format that someString?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"
.
public String getDateFormat()
setDateFormat(String)
.public void setDateTimeFormat(String dateTimeFormat)
Date
-s to string-s that are date-time (timestamp) values,
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.)
Defaults to ""
, which means "use the FreeMarker default", which is currently "code"
.
public String getDateTimeFormat()
setDateTimeFormat(String)
.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.
public TemplateExceptionHandler getTemplateExceptionHandler()
setTemplateExceptionHandler(TemplateExceptionHandler)
.public void setArithmeticEngine(ArithmeticEngine arithmeticEngine)
ArithmeticEngine.BIGDECIMAL_ENGINE
.public ArithmeticEngine getArithmeticEngine()
setArithmeticEngine(ArithmeticEngine)
.public void setObjectWrapper(ObjectWrapper objectWrapper)
TemplateModel
-s.
The default is ObjectWrapper.DEFAULT_WRAPPER
.public ObjectWrapper getObjectWrapper()
setObjectWrapper(ObjectWrapper)
.public void setOutputEncoding(String outputEncoding)
null
means that the output encoding is not known.
Defaults to null
(unknown).
public String getOutputEncoding()
public void setURLEscapingCharset(String urlEscapingCharset)
null
), the output encoding
(setOutputEncoding(String)
) will be used for URL escaping.
Defaults to null
.public String getURLEscapingCharset()
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
.public TemplateClassResolver getNewBuiltinClassResolver()
TemplateClassResolver
used
to resolve classes when "SomeClassName"?new is called in a template.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 void setShowErrorTips(boolean showTips)
true
.public boolean getShowErrorTips()
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 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
; those are always logged, no mater what (because those exceptions won't bubble up
until the API caller).public boolean getLogTemplateExceptions()
public void setSetting(String name, String value) throws TemplateException
setObjectWrapper(ObjectWrapper)
. This meant to be used if you get the settings from somewhere
as text. Regardless, below you will find an overview of the settings available no matter how you set them.
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"
.
"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.
"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
),
"default"
(only allowed for Configuration
instances) for the default.
"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)"
,
"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(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 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(java.lang.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.
"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"
:
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:"
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 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.
Configuration
(a subclass of Configurable
) also understands these:
"auto_import"
:
See Configuration.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 Configuration.setAutoIncludes(List)
String value is something like:
/include/common.ftl, "/include/evil name.ftl"
"default_encoding"
:
See Configuration.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"
:
See Configuration.setLocalizedLookup(boolean)
.
String value: "true"
, "false"
(also the equivalents: "yes"
, "no"
,
"t"
, "f"
, "y"
, "n"
).
Case insensitive.
"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"
:
See Configuration.setTemplateUpdateDelay(int)
.
String value: Valid positive integer, the update delay measured in seconds.
"tag_syntax"
:
See Configuration.setTagSyntax(int)
.
String value: Must be one of
"auto_detect"
, "angle_bracket"
, and "square_bracket"
.
"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.
"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"
for TemplateNameFormat.DEFAULT_2_3_0
, "default_2_4_0"
for
TemplateNameFormat.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.
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.
Currently, the values of arguments and properties can only be one of these:
123
or -1.5
. Like in FTL, there are no numerical types,
the value will be automatically converted to the type of the target.true
or false
null
"Line 1\nLine 2"
or r"C:\temp"
.
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 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 void setStrictBeanModels(boolean strict)
public String getSetting(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.public 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(String name)
protected String getCorrectedNameForUnknownSetting(String name)
name
- The wrong namenull
if there's no known correctionprotected TemplateException settingValueAssignmentException(String name, String value, Throwable cause)
protected TemplateException invalidSettingValueException(String name, String value)
public void setSettings(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(InputStream propsIn) throws TemplateException, IOException
.properties
format.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.public void setCustomAttribute(String name, 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 String[] getCustomAttributeNames()
public void removeCustomAttribute(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 Object getCustomAttribute(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, IOException
TemplateException
IOException
protected ArrayList parseAsList(String text) throws ParseException
ParseException
protected ArrayList parseAsSegmentedList(String text) throws ParseException
ParseException
protected HashMap parseAsImportList(String text) throws ParseException
ParseException