Package freemarker.core

Class Configurable

java.lang.Object
freemarker.core.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.

  • Field Details

  • 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
      Overrides:
      clone in class Object
      Throws:
      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.

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

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

    • getEnvironment

      public Environment getEnvironment()

    • unknownSettingException

      protected TemplateException unknownSettingException(String name)

    • invalidSettingValueException

      protected TemplateException invalidSettingValueException(String name, String value)

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

    • doAutoImportsAndIncludes

      protected void doAutoImportsAndIncludes(Environment env) throws TemplateException, IOException
      Throws:
      TemplateException
      IOException