freemarker.core

Class Configurable

java.lang.Object

freemarker.core.Configurable

Direct Known Subclasses:

Configuration, Environment, Template

public class Configurable
extends java.lang.Object

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.

Author:

Attila Szegedi

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Configurable.UnknownSettingException

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ARITHMETIC_ENGINE_KEY
static java.lang.String	AUTO_FLUSH_KEY
static java.lang.String	BOOLEAN_FORMAT_KEY
static java.lang.String	CLASSIC_COMPATIBLE_KEY
static java.lang.String	DATE_FORMAT_KEY
static java.lang.String	DATETIME_FORMAT_KEY
static java.lang.String	LOCALE_KEY
static java.lang.String	NEW_BUILTIN_CLASS_RESOLVER_KEY
static java.lang.String	NUMBER_FORMAT_KEY
static java.lang.String	OBJECT_WRAPPER_KEY
static java.lang.String	OUTPUT_ENCODING_KEY
static java.lang.String	STRICT_BEAN_MODELS
static java.lang.String	TEMPLATE_EXCEPTION_HANDLER_KEY
static java.lang.String	TIME_FORMAT_KEY
static java.lang.String	TIME_ZONE_KEY
static java.lang.String	URL_ESCAPING_CHARSET_KEY

Constructor Summary

Constructors

Constructor and Description
Configurable() Creates a top-level configurable, one that doesn't ingerit from a parent, and thus stores the default values.
Configurable(Configurable parent) Creates a new instance.

Method Summary

Methods

Modifier and Type	Method and Description
protected java.lang.Object	clone()
protected void	doAutoImportsAndIncludes(Environment env)
ArithmeticEngine	getArithmeticEngine() The getter pair of setArithmeticEngine(ArithmeticEngine).
boolean	getAutoFlush() See setAutoFlush(boolean)
java.lang.String	getBooleanFormat() The getter pair of setBooleanFormat(String).
int	getClassicCompatibleAsInt()
java.lang.Object	getCustomAttribute(java.lang.String name) Retrieves a named custom attribute for this configurable.
java.lang.String[]	getCustomAttributeNames() Returns an array with names of all custom attributes defined directly on this configurable.
java.lang.String	getDateFormat() The getter pair of setDateFormat(String).
java.lang.String	getDateTimeFormat() The getter pair of setDateTimeFormat(String).
protected Environment	getEnvironment()
java.util.Locale	getLocale() Returns the assumed locale when searching for template files with no explicit requested locale.
TemplateClassResolver	getNewBuiltinClassResolver() Retrieves the TemplateClassResolver used to resolve classes when "SomeClassName"?
java.lang.String	getNumberFormat() Returns the default number format used to convert numbers to strings.
ObjectWrapper	getObjectWrapper() The getter pair of setObjectWrapper(ObjectWrapper).
java.lang.String	getOutputEncoding()
Configurable	getParent() Returns the parent Configurable object of this object.
java.lang.String	getSetting(java.lang.String key) 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 setSetting(String, String) will work with them correctly.)
java.util.Map	getSettings() Deprecated. This method was always defective, and certainly it always will be. Don't use it. (Simply, it's hardly possible in general to convert setting values to text in a way that ensures that setSettings(Properties) will work with them correctly.)
TemplateExceptionHandler	getTemplateExceptionHandler() The getter pair of setTemplateExceptionHandler(TemplateExceptionHandler).
java.lang.String	getTimeFormat() The getter pair of setTimeFormat(String).
java.util.TimeZone	getTimeZone() The getter pair of setTimeZone(TimeZone).
java.lang.String	getURLEscapingCharset()
protected TemplateException	invalidSettingValueException(java.lang.String name, java.lang.String value)
boolean	isClassicCompatible() Returns whether the engine runs in the "Classic Compatibile" mode.
protected java.util.HashMap	parseAsImportList(java.lang.String text)
protected java.util.ArrayList	parseAsList(java.lang.String text)
protected java.util.ArrayList	parseAsSegmentedList(java.lang.String text)
void	removeCustomAttribute(java.lang.String name) Removes a named custom attribute for this configurable.
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(java.lang.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 Compatibile" mode.
void	setClassicCompatibleAsInt(int classicCompatibility) Same as setClassicCompatible(boolean), but allows some extra values.
void	setCustomAttribute(java.lang.String name, java.lang.Object value) Sets a named custom attribute for this configurable.
void	setDateFormat(java.lang.String dateFormat) Sets the format used to convert Date-s to string-s that are date-only (no time part) values.
void	setDateTimeFormat(java.lang.String dateTimeFormat) Sets the format used to convert Date-s to string-s that are date+time values.
void	setLocale(java.util.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	setNewBuiltinClassResolver(TemplateClassResolver newBuiltinClassResolver) Sets the TemplateClassResolver that is used when the new built-in is called in a template.
void	setNumberFormat(java.lang.String numberFormat) Sets the number format used to convert numbers to strings.
void	setObjectWrapper(ObjectWrapper objectWrapper) Sets the object wrapper used to wrap objects to TemplateModel-s.
void	setOutputEncoding(java.lang.String outputEncoding) Informs FreeMarker about the charset used for the output.
void	setSetting(java.lang.String name, java.lang.String value) Sets a FreeMarker setting by a name and string value.
void	setSettings(java.io.InputStream propsIn) Reads a setting list (key and element pairs) from the input stream.
void	setSettings(java.util.Properties props) Set the settings stored in a Properties object.
void	setStrictBeanModels(boolean strict)
void	setTemplateExceptionHandler(TemplateExceptionHandler templateExceptionHandler) Sets the exception handler used to handle exceptions occurring inside templates.
void	setTimeFormat(java.lang.String timeFormat) Sets the format used to convert Date-s to string-s that are time-only (not date part) values.
void	setTimeZone(java.util.TimeZone timeZone) Sets the time zone to use when formatting date/time values.
void	setURLEscapingCharset(java.lang.String urlEscapingCharset) Sets the URL escaping charset.
protected TemplateException	unknownSettingException(java.lang.String name)

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOCALE_KEY

public static final java.lang.String LOCALE_KEY

See Also:

Constant Field Values

NUMBER_FORMAT_KEY

public static final java.lang.String NUMBER_FORMAT_KEY

See Also:

Constant Field Values

TIME_FORMAT_KEY

public static final java.lang.String TIME_FORMAT_KEY

See Also:

Constant Field Values

DATE_FORMAT_KEY

public static final java.lang.String DATE_FORMAT_KEY

See Also:

Constant Field Values

DATETIME_FORMAT_KEY

public static final java.lang.String DATETIME_FORMAT_KEY

See Also:

Constant Field Values

TIME_ZONE_KEY

public static final java.lang.String TIME_ZONE_KEY

See Also:

Constant Field Values

CLASSIC_COMPATIBLE_KEY

public static final java.lang.String CLASSIC_COMPATIBLE_KEY

See Also:

Constant Field Values

TEMPLATE_EXCEPTION_HANDLER_KEY

public static final java.lang.String TEMPLATE_EXCEPTION_HANDLER_KEY

See Also:

Constant Field Values

ARITHMETIC_ENGINE_KEY

public static final java.lang.String ARITHMETIC_ENGINE_KEY

See Also:

Constant Field Values

OBJECT_WRAPPER_KEY

public static final java.lang.String OBJECT_WRAPPER_KEY

See Also:

Constant Field Values

BOOLEAN_FORMAT_KEY

public static final java.lang.String BOOLEAN_FORMAT_KEY

See Also:

Constant Field Values

OUTPUT_ENCODING_KEY

public static final java.lang.String OUTPUT_ENCODING_KEY

See Also:

Constant Field Values

URL_ESCAPING_CHARSET_KEY

public static final java.lang.String URL_ESCAPING_CHARSET_KEY

See Also:

Constant Field Values

STRICT_BEAN_MODELS

public static final java.lang.String STRICT_BEAN_MODELS

See Also:

Constant Field Values

AUTO_FLUSH_KEY

public static final java.lang.String AUTO_FLUSH_KEY

Since:

2.3.17

See Also:

Constant Field Values

NEW_BUILTIN_CLASS_RESOLVER_KEY

public static final java.lang.String NEW_BUILTIN_CLASS_RESOLVER_KEY

Since:

2.3.17

See Also:

Constant Field Values

Constructor Detail

Configurable

public Configurable()

Creates a top-level configurable, one that doesn't ingerit from a parent, and thus stores the default values. The only class that should use this is Configuration.

Configurable

public Configurable(Configurable parent)

Creates a new instance. Normally you do not need to use this constructor, as you don't use Configurable directly, but its subclasses.

Method Detail

clone

protected java.lang.Object clone()
                          throws java.lang.CloneNotSupportedException

Overrides:

clone in class java.lang.Object

Throws:

java.lang.CloneNotSupportedException

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.

Returns:

the parent Configurable object, or null, if this is the root Configurable object.

setClassicCompatible

public void setClassicCompatible(boolean classicCompatibility)

Toggles the "Classic Compatibile" mode. For a comprehensive description of this mode, see isClassicCompatible().

setClassicCompatibleAsInt

public void setClassicCompatibleAsInt(int classicCompatibility)

Same as setClassicCompatible(boolean), but allows some extra values.

Parameters:

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.

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.

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.

getClassicCompatibleAsInt

public int getClassicCompatibleAsInt()

setLocale

public void setLocale(java.util.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.

See Also:

Configuration.getTemplate(String, Locale)

getTimeZone

public java.util.TimeZone getTimeZone()

The getter pair of setTimeZone(TimeZone).

setTimeZone

public void setTimeZone(java.util.TimeZone timeZone)

Sets the time zone to use when formatting date/time values. Defaults to the system time zone (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 the visitor.

getLocale

public java.util.Locale getLocale()

Returns the assumed locale when searching for template files with no explicit requested locale. Defaults to system locale.

setNumberFormat

public void setNumberFormat(java.lang.String numberFormat)

Sets the number format used to convert numbers to strings.

getNumberFormat

public java.lang.String getNumberFormat()

Returns the default number format used to convert numbers to strings. Defaults to "number"

setBooleanFormat

public void setBooleanFormat(java.lang.String booleanFormat)

The string value for the boolean 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.

getBooleanFormat

public java.lang.String getBooleanFormat()

The getter pair of setBooleanFormat(String).

setTimeFormat

public void setTimeFormat(java.lang.String timeFormat)

Sets the format used to convert Date-s to string-s that are time-only (not date part) values. Possible values are patterns accepted by Java's DateFormat, also "short", "medium", "long" and "full" that has locale-dependent meaning also defined by DateFormat.

Defaults to "", which means "use the FreeMarker default", which is currently "medium".

getTimeFormat

public java.lang.String getTimeFormat()

The getter pair of setTimeFormat(String).

setDateFormat

public void setDateFormat(java.lang.String dateFormat)

Sets the format used to convert Date-s to string-s that are date-only (no time part) values. Possible values are patterns accepted by Java's DateFormat, also "short", "medium", "long" and "full" that has locale-dependent meaning also defined by DateFormat.

Defaults to "", which means "use the FreeMarker default", which is currently "medium".

getDateFormat

public java.lang.String getDateFormat()

The getter pair of setDateFormat(String).

setDateTimeFormat

public void setDateTimeFormat(java.lang.String dateTimeFormat)

Sets the format used to convert Date-s to string-s that are date+time values. Possible values are patterns accepted by Java's DateFormat, also "short", "medium", "long" and "full" that has locale-dependent meaning also defined by DateFormat. It's also possible to give values like "short_long" (in any combinations), which will use "short" for the date part, and "long" for the time part.

Defaults to "", which means "use the FreeMarker default", which is currently "medium".

getDateTimeFormat

public java.lang.String getDateTimeFormat()

The getter pair of setDateTimeFormat(String).

setTemplateExceptionHandler

public void setTemplateExceptionHandler(TemplateExceptionHandler templateExceptionHandler)

Sets the exception handler used to handle exceptions occurring inside templates. The default is TemplateExceptionHandler.DEBUG_HANDLER. The recommended values are:

• In productions 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 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.

getTemplateExceptionHandler

public TemplateExceptionHandler getTemplateExceptionHandler()

The getter pair of setTemplateExceptionHandler(TemplateExceptionHandler).

setArithmeticEngine

public void setArithmeticEngine(ArithmeticEngine arithmeticEngine)

Sets the arithmetic engine used to perform arithmetic operations. The default is ArithmeticEngine.BIGDECIMAL_ENGINE.

getArithmeticEngine

public ArithmeticEngine getArithmeticEngine()

The getter pair of setArithmeticEngine(ArithmeticEngine).

setObjectWrapper

public void setObjectWrapper(ObjectWrapper objectWrapper)

Sets the object wrapper used to wrap objects to TemplateModel-s. The default is ObjectWrapper.DEFAULT_WRAPPER.

getObjectWrapper

public ObjectWrapper getObjectWrapper()

The getter pair of setObjectWrapper(ObjectWrapper).

setOutputEncoding

public void setOutputEncoding(java.lang.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 to null means that the output encoding is not known.

Defaults to null (unknown).

getOutputEncoding

public java.lang.String getOutputEncoding()

setURLEscapingCharset

public void setURLEscapingCharset(java.lang.String urlEscapingCharset)

Sets the URL escaping charset. If not set (null), the output encoding (setOutputEncoding(String)) will be used for URL escaping. Defaults to null.

getURLEscapingCharset

public java.lang.String getURLEscapingCharset()

setNewBuiltinClassResolver

public void setNewBuiltinClassResolver(TemplateClassResolver newBuiltinClassResolver)

Sets the 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.

Since:

2.3.17

getNewBuiltinClassResolver

public TemplateClassResolver getNewBuiltinClassResolver()

Retrieves the TemplateClassResolver 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 output 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.

Since:

2.3.17

getAutoFlush

public boolean getAutoFlush()

See setAutoFlush(boolean)

Since:

2.3.17

setSetting

public void setSetting(java.lang.String name,
              java.lang.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 (like 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 a 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 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).

• "arithmetic_engine": See setArithmeticEngine(ArithmeticEngine).
  String value: If the value contains dot, then it's 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 (case insensitive): "bigdecimal", "conservative".

• "object_wrapper": See setObjectWrapper(ObjectWrapper).
  String value: If the value contains dot, then it's 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 (case insensitive): "default" (means ObjectWrapper.DEFAULT_WRAPPER), "simple" (means ObjectWrapper.SIMPLE_WRAPPER), "beans" (means ObjectWrapper.DEFAULT_WRAPPER), "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. For example "GMT-8:00" or "America/Los_Angeles"

• "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.
  String value: The value must be one of these (ignore the quotation marks):

  1. "unrestricted": Use TemplateClassResolver.UNRESTRICTED_RESOLVER

  2. "safer": Use TemplateClassResolver.SAFER_RESOLVER

  3. "allows_nothing": Use TemplateClassResolver.ALLOWS_NOTHING_RESOLVER

  4. 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.

  5. Otherwise if the value contains dot, it's interpreted as a full-qualified class name, and the object will be created with its parameterless constructor.

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 class name, and the object will be created with its parameterless constructor. 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.

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 java.lang.String getSetting(java.lang.String key)

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 setSetting(String, String) will work with them 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 java.util.Map getSettings()

Deprecated. This method was always defective, and certainly it always will be. Don't use it. (Simply, it's hardly possible in general to convert setting values to text in a way that ensures that setSettings(Properties) will work with them correctly.)

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).

getEnvironment

protected Environment getEnvironment()

unknownSettingException

protected TemplateException unknownSettingException(java.lang.String name)

invalidSettingValueException

protected TemplateException invalidSettingValueException(java.lang.String name,
                                             java.lang.String value)

setSettings

public void setSettings(java.util.Properties props)
                 throws TemplateException

Set the settings stored in a Properties object.

Throws:

TemplateException - if the Properties object contains invalid keys, or invalid setting values, or any other error occurs while changing the settings.

setSettings

public void setSettings(java.io.InputStream propsIn)
                 throws TemplateException,
                        java.io.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.

java.io.IOException - if an error occurred when reading from the input stream.

setCustomAttribute

public void setCustomAttribute(java.lang.String name,
                      java.lang.Object value)

Sets a named custom attribute for this configurable.

Parameters:

name - the name of the custom attribute

value - 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).

getCustomAttributeNames

public java.lang.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(java.lang.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 java.lang.Object getCustomAttribute(java.lang.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 a List, or a Map, ...etc., not a FreeMarker specific class).

doAutoImportsAndIncludes

protected void doAutoImportsAndIncludes(Environment env)
                                 throws TemplateException,
                                        java.io.IOException

Throws:

TemplateException

java.io.IOException

parseAsList

protected java.util.ArrayList parseAsList(java.lang.String text)
                                   throws ParseException

Throws:

ParseException

parseAsSegmentedList

protected java.util.ArrayList parseAsSegmentedList(java.lang.String text)
                                            throws ParseException

Throws:

ParseException

parseAsImportList

protected java.util.HashMap parseAsImportList(java.lang.String text)
                                       throws ParseException

Throws:

ParseException