freemarker.core

Class Configurable

Known Direct 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

class
Configurable.UnknownSettingException

Field Summary

static String
ARITHMETIC_ENGINE_KEY
static String
BOOLEAN_FORMAT_KEY
static String
CLASSIC_COMPATIBLE_KEY
static String
DATETIME_FORMAT_KEY
static String
DATE_FORMAT_KEY
static String
LOCALE_KEY
static String
NUMBER_FORMAT_KEY
static String
OBJECT_WRAPPER_KEY
static String
OUTPUT_ENCODING_KEY
static String
STRICT_BEAN_MODELS
static String
TEMPLATE_EXCEPTION_HANDLER_KEY
static String
TIME_FORMAT_KEY
static String
TIME_ZONE_KEY
static String
URL_ESCAPING_CHARSET_KEY

Constructor Summary

Configurable()
Configurable(Configurable parent)
Creates a new instance.

Method Summary

protected Object
clone()
ArithmeticEngine
getArithmeticEngine()
Retrieves the arithmetic engine used to perform arithmetic operations.
String
getBooleanFormat()
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()
Returns the date format used to convert date models representing date-only dates to strings.
String
getDateTimeFormat()
Returns the date format used to convert date models representing datetime dates to strings.
protected Environment
getEnvironment()
Locale
getLocale()
Returns the assumed locale when searching for template files with no explicit requested locale.
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.
String
getOutputEncoding()
Configurable
getParent()
Returns the parent Configurable object of this object.
String
getSetting(String key)
Deprecated. This method was always defective, and certainly it always will be.
Map
getSettings()
Deprecated. This method was always defective, and certainly it always will be.
TemplateExceptionHandler
getTemplateExceptionHandler()
Retrieves the exception handler used to handle template exceptions.
String
getTimeFormat()
Returns the date format used to convert date models representing time-only dates to strings.
TimeZone
getTimeZone()
Returns the time zone to use when formatting time values.
String
getURLEscapingCharset()
protected TemplateException
invalidSettingValueException(String name, String value)
boolean
isClassicCompatible()
Returns whether the engine runs in the "Classic Compatibile" mode.
void
removeCustomAttribute(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(String booleanFormat)
void
setClassicCompatible(boolean classicCompatibility)
Toggles the "Classic Compatibile" mode.
void
setCustomAttribute(String name, Object value)
Sets a named custom attribute for this configurable.
void
setDateFormat(String dateFormat)
Sets the date format used to convert date models representing date-only dates to strings.
void
setDateTimeFormat(String dateTimeFormat)
Sets the date format used to convert date models representing datetime dates to strings.
void
setLocale(Locale locale)
Sets the locale to assume when searching for template files with no explicit requested locale.
void
setNumberFormat(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(String outputEncoding)
Sets the output encoding.
void
setSetting(String key, String value)
Sets a 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
setStrictBeanModels(boolean strict)
void
setTemplateExceptionHandler(TemplateExceptionHandler templateExceptionHandler)
Sets the exception handler used to handle template exceptions.
void
setTimeFormat(String timeFormat)
Sets the date format used to convert date models representing time-only values to strings.
void
setTimeZone(TimeZone timeZone)
Sets the time zone to use when formatting time values.
void
setURLEscapingCharset(String urlEscapingCharset)
Sets the URL escaping charset.
protected TemplateException
unknownSettingException(String name)

Field Details

ARITHMETIC_ENGINE_KEY

public static final String ARITHMETIC_ENGINE_KEY

BOOLEAN_FORMAT_KEY

public static final String BOOLEAN_FORMAT_KEY

CLASSIC_COMPATIBLE_KEY

public static final String CLASSIC_COMPATIBLE_KEY

DATETIME_FORMAT_KEY

public static final String DATETIME_FORMAT_KEY

DATE_FORMAT_KEY

public static final String DATE_FORMAT_KEY

LOCALE_KEY

public static final String LOCALE_KEY

NUMBER_FORMAT_KEY

public static final String NUMBER_FORMAT_KEY

OBJECT_WRAPPER_KEY

public static final String OBJECT_WRAPPER_KEY

OUTPUT_ENCODING_KEY

public static final String OUTPUT_ENCODING_KEY

STRICT_BEAN_MODELS

public static final String STRICT_BEAN_MODELS

TEMPLATE_EXCEPTION_HANDLER_KEY

public static final String TEMPLATE_EXCEPTION_HANDLER_KEY

TIME_FORMAT_KEY

public static final String TIME_FORMAT_KEY

TIME_ZONE_KEY

public static final String TIME_ZONE_KEY

URL_ESCAPING_CHARSET_KEY

public static final String URL_ESCAPING_CHARSET_KEY

Constructor Details

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 Details

clone

protected Object clone()
            throws CloneNotSupportedException

getArithmeticEngine

public ArithmeticEngine getArithmeticEngine()
Retrieves the arithmetic engine used to perform arithmetic operations.

getBooleanFormat

public String getBooleanFormat()

getCustomAttribute

public Object getCustomAttribute(String name)
Retrieves a named custom attribute for this configurable. If the attribute is not present in the configurable, and the configurable has a parent, then the parent is looked up as well.
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).

getCustomAttributeNames

public String[] getCustomAttributeNames()
Returns an array with names of all custom attributes defined directly on this configurable. (That is, it doesn't contain the names of custom attributes defined indirectly on its parent configurables.) The returned array is never null, but can be zero-length. The order of elements in the returned array is not defined and can change between invocations.

getDateFormat

public String getDateFormat()
Returns the date format used to convert date models representing date-only dates to strings. Defaults to "date"

getDateTimeFormat

public String getDateTimeFormat()
Returns the date format used to convert date models representing datetime dates to strings. Defaults to "datetime"

getEnvironment

protected Environment getEnvironment()

getLocale

public Locale getLocale()
Returns the assumed locale when searching for template files with no explicit requested locale. Defaults to system locale.

getNumberFormat

public String getNumberFormat()
Returns the default number format used to convert numbers to strings. Defaults to "number"

getObjectWrapper

public ObjectWrapper getObjectWrapper()
Retrieves the object wrapper used to wrap objects to template models.

getOutputEncoding

public String getOutputEncoding()

getParent

public final Configurable getParent()
Returns the parent Configurable object of this object. The parent stores the default values for this configurable. For example, the parent of the Template object is the Configuration object, so setting values not specfied on template level are specified by the confuration object.
Returns:
the parent Configurable object, or null, if this is the root Configurable object.

getSetting

public String getSetting(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 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).

getTemplateExceptionHandler

public TemplateExceptionHandler getTemplateExceptionHandler()
Retrieves the exception handler used to handle template exceptions.

getTimeFormat

public String getTimeFormat()
Returns the date format used to convert date models representing time-only dates to strings. Defaults to "time"

getTimeZone

public TimeZone getTimeZone()
Returns the time zone to use when formatting time values. Defaults to system time zone.

getURLEscapingCharset

public String getURLEscapingCharset()

invalidSettingValueException

protected TemplateException invalidSettingValueException(String name,
                                                         String value)

isClassicCompatible

public boolean isClassicCompatible()
Returns whether the engine runs in the "Classic Compatibile" mode. When this mode is active, the engine behavior is altered in following way: (these resemble the behavior of the 1.7.x line of FreeMarker engine, now named "FreeMarker Classic", hence the name).
  • handle undefined expressions gracefully. Namely when an expression "expr" evaluates to null:
    • as argument of the <assign varname=expr> directive, ${expr} directive, otherexpr == expr or otherexpr != expr conditional expressions, or hash[expr] expression, then it is treated as empty string.
    • as argument of <list expr as item> or <foreach item in expr>, the loop body is not executed (as if it were a 0-length list)
    • as argument of <if> directive, or otherwise where a boolean expression is expected, it is treated as false
  • Non-boolean models are accepted in <if> directive, or as operands of logical operators. "Empty" models (zero-length string, empty sequence or hash) are evaluated as false, all others are evaluated as true.
  • When boolean value is treated as a string (i.e. output in ${...} directive, or concatenated with other string), true values are converted to string "true", false values are converted to empty string.
  • Scalar models supplied to <list> and <foreach> are treated as a one-element list consisting of the passed model.
  • Paths parameter of <include> will be interpreted as absolute path.
  • In all other aspects, the engine is a 2.1 engine even in compatibility mode - you don't lose any of the new functionality by enabling it.

    removeCustomAttribute

    public void removeCustomAttribute(String name)
    Removes a named custom attribute for this configurable. Note that this is different than setting the custom attribute value to null. If you set the value to null, getCustomAttribute(String) will return null, while if you remove the attribute, it will return the value of the attribute in the parent configurable (if there is a parent configurable, that is).
    Parameters:
    name - the name of the custom attribute

    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.

    setBooleanFormat

    public void setBooleanFormat(String booleanFormat)

    setClassicCompatible

    public void setClassicCompatible(boolean classicCompatibility)

    setCustomAttribute

    public void setCustomAttribute(String name,
                                   Object value)
    Sets a named custom attribute for this configurable.

    setDateFormat

    public void setDateFormat(String dateFormat)
    Sets the date format used to convert date models representing date-only dates to strings.

    setDateTimeFormat

    public void setDateTimeFormat(String dateTimeFormat)
    Sets the date format used to convert date models representing datetime dates to strings.

    setLocale

    public void setLocale(Locale locale)
    Sets the locale to assume when searching for template files with no explicit requested locale.

    setNumberFormat

    public void setNumberFormat(String numberFormat)
    Sets the number format used to convert numbers to strings.

    setObjectWrapper

    public void setObjectWrapper(ObjectWrapper objectWrapper)
    Sets the object wrapper used to wrap objects to template models.
    Parameters:
    objectWrapper - the object wrapper used to wrap objects to template models.By default, ObjectWrapper.DEFAULT_WRAPPER is used.

    setOutputEncoding

    public void setOutputEncoding(String outputEncoding)
    Sets the output encoding. Allows null, which means that the output encoding is not known.

    setSetting

    public void setSetting(String key,
                           String value)
                throws TemplateException
    Sets a setting by a name and string value.

    List of supported names and their valid values:

    • "locale": local codes with the usual format, such as "en_US".
    • "classic_compatible": "true", "false", "yes", "no", "t", "f", "y", "n". Case insensitive.
    • "template_exception_handler": If the value contains dot, then it is interpreted as class name, and the object will be created with its parameterless constructor. If the value does not contain dot, then it must be one of these special values: "rethrow", "debug", "html_debug", "ignore" (case insensitive).
    • "arithmetic_engine": If the value contains dot, then it is interpreted as class name, and the object will be created with its parameterless constructor. If the value does not contain dot, then it must be one of these special values: "bigdecimal", "conservative" (case insensitive).
    • "object_wrapper": If the value contains dot, then it is interpreted as class name, and the object will be created with its parameterless constructor. If the value does not contain dot, then it must be one of these special values: "simple", "beans", "jython" (case insensitive).
    • "number_format": pattern as java.text.DecimalFormat defines.
    • "boolean_format": the textual value for boolean true and false, separated with comma. For example "yes,no".
    • "date_format", "time_format", "datetime_format": patterns as java.text.SimpleDateFormat defines.
    • "time_zone": time zone, with the format as java.util.TimeZone.getTimeZone defines. For example "GMT-8:00" or "America/Los_Angeles"
    • "output_encoding": Informs FreeMarker about the charset used for the output. As FreeMarker outputs character stream (not byte stream), it is not aware of the output charset unless the software that encloses it tells it explicitly with this setting. Some templates may use FreeMarker features that require this.
    • "url_escaping_charset": If this setting is set, then it overrides the value of the "output_encoding" setting when FreeMarker does URL encoding.
    Parameters:
    key - the name of the setting.
    value - the string that describes the new value of the setting.
    Throws:
    TemplateException - if the new value of the setting can't be set for any other reasons.

    setSettings

    public void setSettings(InputStream propsIn)
                throws TemplateException,
                       IOException
    Reads a setting list (key and element pairs) from the input stream. The stream has to follow the usual .properties format.
    Throws:
    TemplateException - if the stream contains invalid keys, or invalid setting values, or any other error occurs while changing the settings.

    setSettings

    public void setSettings(Properties props)
                throws TemplateException
    Set the settings stored in a Properties object.
    Throws:
    TemplateException - if the Properties object contains invalid keys, or invalid setting values, or any other error occurs while changing the settings.

    setStrictBeanModels

    public void setStrictBeanModels(boolean strict)

    setTemplateExceptionHandler

    public void setTemplateExceptionHandler(TemplateExceptionHandler templateExceptionHandler)
    Sets the exception handler used to handle template exceptions.
    Parameters:
    templateExceptionHandler - the template exception handler to use for handling TemplateExceptions. By default, TemplateExceptionHandler.HTML_DEBUG_HANDLER is used.

    setTimeFormat

    public void setTimeFormat(String timeFormat)
    Sets the date format used to convert date models representing time-only values to strings.

    setTimeZone

    public void setTimeZone(TimeZone timeZone)
    Sets the time zone to use when formatting time values.

    setURLEscapingCharset

    public void setURLEscapingCharset(String urlEscapingCharset)
    Sets the URL escaping charset. Allows null, which means that the output encoding will be used for URL escaping.

    unknownSettingException

    protected TemplateException unknownSettingException(String name)