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.

Version:

$Id: Configurable.java,v 1.23.2.2 2007/04/02 13:46:43 szegedia Exp $

Author:

Attila Szegedi

Nested Class Summary

static class

Configurable.UnknownSettingException

Field Summary

static java.lang.String	ARITHMETIC_ENGINE_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	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

Configurable()

Configurable(Configurable parent)
Creates a new instance.

Method Summary

protected java.lang.Object	clone()
ArithmeticEngine	getArithmeticEngine() Retrieves the arithmetic engine used to perform arithmetic operations.
java.lang.String	getBooleanFormat()
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() Returns the date format used to convert date models representing date-only dates to strings.
java.lang.String	getDateTimeFormat() Returns the date format used to convert date models representing datetime dates to strings.
protected Environment	getEnvironment()
java.util.Locale	getLocale() Returns the assumed locale when searching for template files with no explicit requested locale.
java.lang.String	getNumberFormat() Returns the default number format used to convert numbers to strings.
ObjectWrapper	getObjectWrapper() Retrieves the object wrapper used to wrap objects to template models.
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() Retrieves the exception handler used to handle template exceptions.
java.lang.String	getTimeFormat() Returns the date format used to convert date models representing time-only dates to strings.
java.util.TimeZone	getTimeZone() Returns the time zone to use when formatting time values.
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.
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	setBooleanFormat(java.lang.String booleanFormat)
void	setClassicCompatible(boolean classicCompatibility) Toggles the "Classic Compatibile" mode.
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 date format used to convert date models representing date-only dates to strings.
void	setDateTimeFormat(java.lang.String dateTimeFormat) Sets the date format used to convert date models representing datetime dates to strings.
void	setLocale(java.util.Locale locale) Sets the locale to assume when searching for template files with no explicit requested locale.
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 template models.
void	setOutputEncoding(java.lang.String outputEncoding) Sets the output encoding.
void	setSetting(java.lang.String key, java.lang.String value) Sets a 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 template exceptions.
void	setTimeFormat(java.lang.String timeFormat) Sets the date format used to convert date models representing time-only values to strings.
void	setTimeZone(java.util.TimeZone timeZone) Sets the time zone to use when formatting 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

Constructor Detail

Configurable

public Configurable()

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

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.

setLocale

public void setLocale(java.util.Locale locale)

Sets the locale to assume when searching for template files with no explicit requested locale.

getTimeZone

public java.util.TimeZone getTimeZone()

Returns the time zone to use when formatting time values. Defaults to system time zone.

setTimeZone

public void setTimeZone(java.util.TimeZone timeZone)

Sets the time zone to use when formatting time values.

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)

getBooleanFormat

public java.lang.String getBooleanFormat()

setTimeFormat

public void setTimeFormat(java.lang.String timeFormat)

Sets the date format used to convert date models representing time-only values to strings.

getTimeFormat

public java.lang.String getTimeFormat()

Returns the date format used to convert date models representing time-only dates to strings. Defaults to "time"

setDateFormat

public void setDateFormat(java.lang.String dateFormat)

Sets the date format used to convert date models representing date-only dates to strings.

getDateFormat

public java.lang.String getDateFormat()

Returns the date format used to convert date models representing date-only dates to strings. Defaults to "date"

setDateTimeFormat

public void setDateTimeFormat(java.lang.String dateTimeFormat)

Sets the date format used to convert date models representing datetime dates to strings.

getDateTimeFormat

public java.lang.String getDateTimeFormat()

Returns the date format used to convert date models representing datetime dates to strings. Defaults to "datetime"

setTemplateExceptionHandler

public void setTemplateExceptionHandler(TemplateExceptionHandler templateExceptionHandler)

Sets the exception handler used to handle template exceptions.

Parameters:

templateExceptionHandler - the template exception handler to use for handling TemplateExceptions. By default, TemplateExceptionHandler.HTML_DEBUG_HANDLER is used.

getTemplateExceptionHandler

public TemplateExceptionHandler getTemplateExceptionHandler()

Retrieves the exception handler used to handle template exceptions.

setArithmeticEngine

public void setArithmeticEngine(ArithmeticEngine arithmeticEngine)

Sets the arithmetic engine used to perform arithmetic operations.

Parameters:

arithmeticEngine - the arithmetic engine used to perform arithmetic operations.By default, ArithmeticEngine.BIGDECIMAL_ENGINE is used.

getArithmeticEngine

public ArithmeticEngine getArithmeticEngine()

Retrieves the arithmetic engine used to perform arithmetic operations.

setObjectWrapper

public void setObjectWrapper(ObjectWrapper objectWrapper)

Sets the object wrapper used to wrap objects to template models.

Parameters:

objectWrapper - the object wrapper used to wrap objects to template models.By default, ObjectWrapper.DEFAULT_WRAPPER is used.

getObjectWrapper

public ObjectWrapper getObjectWrapper()

Retrieves the object wrapper used to wrap objects to template models.

setOutputEncoding

public void setOutputEncoding(java.lang.String outputEncoding)

Sets the output encoding. Allows null, which means that the output encoding is not known.

getOutputEncoding

public java.lang.String getOutputEncoding()

setURLEscapingCharset

public void setURLEscapingCharset(java.lang.String urlEscapingCharset)

Sets the URL escaping charset. Allows null, which means that the output encoding will be used for URL escaping.

getURLEscapingCharset

public java.lang.String getURLEscapingCharset()

setSetting

public void setSetting(java.lang.String key,
                       java.lang.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.

Parameters:

key - the name of the setting.

value - the string that describes the new value of the setting.

Throws:

Configurable.UnknownSettingException - if the key 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).