Package freemarker.core

Class Configurable

  • Direct Known Subclasses:
    Configuration, Environment, TemplateCore
    public class Configurable
extends 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.

    • 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

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

      • setParent

        public void setParent​(Configurable parent)
        Reparenting support. This is used by Environment when it includes a template - the included template becomes the parent configurable during its evaluation.

      • setLocale

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

      • getTimeZone

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

      • setTimeZone

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

      • getLocale

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

      • setNumberFormat

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

      • getNumberFormat

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

      • setBooleanFormat

        public void setBooleanFormat​(String booleanFormat)

      • getBooleanFormat

        public String getBooleanFormat()

      • getBooleanFormat

        public String getBooleanFormat​(boolean value)

      • setTimeFormat

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

      • getTimeFormat

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

      • setDateFormat

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

      • getDateFormat

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

      • setDateTimeFormat

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

      • getDateTimeFormat

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

      • getTemplateExceptionHandler

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

      • setArithmeticEngine

        public void setArithmeticEngine​(freemarker.core.ast.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 freemarker.core.ast.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.

      • getObjectWrapper

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

      • setOutputEncoding

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

      • setNumbersForComputers

        public void setNumbersForComputers​(boolean b)

      • getOutputEncoding

        public String getOutputEncoding()

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

      • getURLEscapingCharset

        public String getURLEscapingCharset()

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

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

      • 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.
        IOException - if an error occurred when reading from the input stream.

      • setCustomAttribute

        public void setCustomAttribute​(String name,
                               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 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​(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 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).