freemarker.core
Class Configurable

java.lang.Object
  extended by 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 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
Configurable()
           
Configurable(Configurable parent)
          Creates a new instance.
 
Method Summary
protected  java.lang.Object clone()
           
protected  void doAutoImportsAndIncludes(Environment env)
           
 ArithmeticEngine getArithmeticEngine()
          Retrieves the arithmetic engine used to perform arithmetic operations.
 boolean getAutoFlush()
          See setAutoFlush(boolean)
 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.
 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()
          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.
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)
           
 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 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 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

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

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

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 key,
                       java.lang.String value)
                throws TemplateException
Sets a setting by a name and string value.

List of supported names and their valid values:

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

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