Home » freemarker-2.3.13 » freemarker.template » [javadoc | source]
freemarker.template
public class: Configuration [javadoc | source]
java.lang.Object
   freemarker.core.Configurable
      freemarker.template.Configuration

All Implemented Interfaces:
    Cloneable

Main entry point into the FreeMarker API, this class encapsulates the various configuration parameters with which FreeMarker is run, as well as serves as a central template loading and caching point. Note that this class uses a default strategy for loading and caching templates. You can plug in a replacement template loading mechanism by using the #setTemplateLoader(TemplateLoader) method. This object is not synchronized. Thus, the settings must not be changed after you have started to access the object from multiple threads. If you use multiple threads, set everything directly after you have instantiated the Configuration object, and don't change the settings anymore.
Field Summary
public static final  String DEFAULT_ENCODING_KEY     
public static final  String LOCALIZED_LOOKUP_KEY     
public static final  String STRICT_SYNTAX_KEY     
public static final  String WHITESPACE_STRIPPING_KEY     
public static final  String CACHE_STORAGE_KEY     
public static final  String TEMPLATE_UPDATE_DELAY_KEY     
public static final  String AUTO_IMPORT_KEY     
public static final  String AUTO_INCLUDE_KEY     
public static final  String TAG_SYNTAX_KEY     
public static final  int AUTO_DETECT_TAG_SYNTAX     
public static final  int ANGLE_BRACKET_TAG_SYNTAX     
public static final  int SQUARE_BRACKET_TAG_SYNTAX     
Fields inherited from freemarker.core.Configurable:
LOCALE_KEY,  NUMBER_FORMAT_KEY,  TIME_FORMAT_KEY,  DATE_FORMAT_KEY,  DATETIME_FORMAT_KEY,  TIME_ZONE_KEY,  CLASSIC_COMPATIBLE_KEY,  TEMPLATE_EXCEPTION_HANDLER_KEY,  ARITHMETIC_ENGINE_KEY,  OBJECT_WRAPPER_KEY,  BOOLEAN_FORMAT_KEY,  OUTPUT_ENCODING_KEY,  URL_ESCAPING_CHARSET_KEY,  STRICT_BEAN_MODELS
Constructor:
 public Configuration() 
Method from freemarker.template.Configuration Summary:
addAutoImport,   addAutoInclude,   clearEncodingMap,   clearSharedVariables,   clearTemplateCache,   clone,   doAutoImports,   doAutoIncludes,   getDefaultConfiguration,   getDefaultEncoding,   getEncoding,   getLocalizedLookup,   getSharedVariable,   getSharedVariableNames,   getStrictSyntaxMode,   getTagSyntax,   getTemplate,   getTemplate,   getTemplate,   getTemplate,   getTemplate,   getTemplateLoader,   getVersionNumber,   getWhitespaceStripping,   loadBuiltInEncodingMap,   removeAutoImport,   removeAutoInclude,   setAllSharedVariables,   setAutoImports,   setAutoIncludes,   setCacheStorage,   setClassForTemplateLoading,   setDefaultConfiguration,   setDefaultEncoding,   setDirectoryForTemplateLoading,   setEncoding,   setLocalizedLookup,   setServletContextForTemplateLoading,   setSetting,   setSharedVariable,   setSharedVariable,   setStrictSyntaxMode,   setTagSyntax,   setTemplateLoader,   setTemplateUpdateDelay,   setWhitespaceStripping
Methods from freemarker.core.Configurable:
clone,   getArithmeticEngine,   getBooleanFormat,   getBooleanFormat,   getCustomAttribute,   getCustomAttribute,   getCustomAttributeNames,   getDateFormat,   getDateTimeFormat,   getEnvironment,   getLocale,   getNumberFormat,   getObjectWrapper,   getOutputEncoding,   getParent,   getSetting,   getSettings,   getTemplateExceptionHandler,   getTimeFormat,   getTimeZone,   getURLEscapingCharset,   invalidSettingValueException,   isClassicCompatible,   removeCustomAttribute,   setArithmeticEngine,   setBooleanFormat,   setClassicCompatible,   setCustomAttribute,   setCustomAttribute,   setDateFormat,   setDateTimeFormat,   setLocale,   setNumberFormat,   setObjectWrapper,   setOutputEncoding,   setParent,   setSetting,   setSettings,   setSettings,   setStrictBeanModels,   setTemplateExceptionHandler,   setTimeFormat,   setTimeZone,   setURLEscapingCharset,   unknownSettingException
Methods from java.lang.Object:
equals,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from freemarker.template.Configuration Detail:
 public synchronized  void addAutoImport(String namespace,
    String template) 
    Add an auto-imported template. The importing will happen at the top of any template that is vended by this Configuration object.
 public synchronized  void addAutoInclude(String templateName) 
    add a template to be automatically included at the top of any template that is vended by this Configuration object.
 public  void clearEncodingMap() 
    Clears language-to-encoding map.
 public  void clearSharedVariables() 
    Removes all shared variables, except the predefined ones (compress, html_escape, etc.).
 public  void clearTemplateCache() 
    Removes all entries from the template cache, thus forcing reloading of templates on subsequent getTemplate calls. This method is thread-safe and can be called while the engine works.
 public Object clone() 
  void doAutoImports(Environment env) throws IOException, TemplateException 
  void doAutoIncludes(Environment env) throws IOException, TemplateException 
 public static Configuration getDefaultConfiguration() 
Deprecated! The - usage of the static singleton (the "default") Configuration instance can easily cause erroneous, unpredictable behavior. This is because multiple independent software components may use FreeMarker internally inside the same application, so they will interfere because of the common Configuration instance. Each such component should use its own private Configuration object instead, that it typically creates with new Configuration() when the component is initialized.

    Returns the default (singleton) Configuration object. Note that you can create as many separate configurations as you wish; this global instance is provided for convenience, or when you have no reason to use a separate instance.
 public String getDefaultEncoding() 
    Gets the default encoding for converting bytes to characters when reading template files in a locale for which no explicit encoding was specified. Defaults to default system encoding.
 public String getEncoding(Locale loc) 
 public boolean getLocalizedLookup() 
    Returns if localized template lookup is enabled or not. This method is thread-safe and can be called while the engine works.
 public TemplateModel getSharedVariable(String name) 
    Gets a shared variable. Shared variables are variables that are available to all templates. When a template is processed, and an identifier is undefined in the data model, a shared variable object with the same identifier is then looked up in the configuration. There are several predefined variables that are always available through this method, see the FreeMarker manual for a comprehensive list of them.
 public Set getSharedVariableNames() 
    Returns the set containing the names of all defined shared variables. The method returns a new Set object on each call that is completely disconnected from the Configuration. That is, modifying the set will have no effect on the Configuration object.
 public boolean getStrictSyntaxMode() 
    Tells whether directives such as if, else, etcetera must be written as #if, #else, etcetera.
 public int getTagSyntax() 
 public Template getTemplate(String name) throws IOException 
    Equivalent to getTemplate(name, thisCfg.getLocale(), thisCfg.getEncoding(thisCfg.getLocale()), true).
 public Template getTemplate(String name,
    Locale locale) throws IOException 
    Equivalent to getTemplate(name, locale, thisCfg.getEncoding(locale), true).
 public Template getTemplate(String name,
    String encoding) throws IOException 
    Equivalent to getTemplate(name, thisCfg.getLocale(), encoding, true).
 public Template getTemplate(String name,
    Locale locale,
    String encoding) throws IOException 
    Equivalent to getTemplate(name, locale, encoding, true).
 public Template getTemplate(String name,
    Locale locale,
    String encoding,
    boolean parse) throws IOException 
 public TemplateLoader getTemplateLoader() 
 public static String getVersionNumber() 
    Returns FreeMarker version number string. Examples of possible return values: "2.2.5", "2.3pre13", "2.3pre13mod", "2.3rc1", "2.3", "3.0".

    Notes on FreeMarker version numbering rules:

    • "pre" and "rc" (lowercase!) means "preview" and "release candidate" respectively. It is must be followed with a number (as "1" for the first release candidate).
    • The "mod" after the version number indicates that it's an unreleased modified version of the released version. After releases, the nighly builds are such releases. E.g. the nightly build after releasing "2.2.1" but before releasing "2.2.2" is "2.2.1mod".
    • The 2nd version number must be present, and maybe 0, as in "3.0".
    • The 3rd version number is never 0. E.g. the version number string for the first release of the 2.2 series is "2.2", and NOT "2.2.0".
    • When only the 3rd version number increases (2.2 -> 2.2.1, 2.2.1 -> 2.2.2 etc.), 100% backward compatiblity with the previous version MUST be kept. This means that freemarker.jar can be replaced in an application without risk (as far as the application doesn't depend on the presence of a FreeMarker bug). Note that backward compatibility restrictions do not apply for preview releases.
 public boolean getWhitespaceStripping() 
    Gets whether the FTL parser will try to remove superfluous white-space around certain FTL tags.
 public  void loadBuiltInEncodingMap() 
    Loads a preset language-to-encoding map. It assumes the usual character encodings for most languages. The previous content of the encoding map will be lost. This default map currently contains the following mappings:
    arISO-8859-6
    beISO-8859-5
    bgISO-8859-5
    caISO-8859-1
    csISO-8859-2
    daISO-8859-1
    deISO-8859-1
    elISO-8859-7
    enISO-8859-1
    esISO-8859-1
    etISO-8859-1
    fiISO-8859-1
    frISO-8859-1
    hrISO-8859-2
    huISO-8859-2
    isISO-8859-1
    itISO-8859-1
    iwISO-8859-8
    jaShift_JIS
    koEUC-KR
    ltISO-8859-2
    lvISO-8859-2
    mkISO-8859-5
    nlISO-8859-1
    noISO-8859-1
    plISO-8859-2
    ptISO-8859-1
    roISO-8859-2
    ruISO-8859-5
    shISO-8859-5
    skISO-8859-2
    slISO-8859-2
    sqISO-8859-2
    srISO-8859-5
    svISO-8859-1
    trISO-8859-9
    ukISO-8859-5
    zhGB2312
    zh_TWBig5
 public synchronized  void removeAutoImport(String namespace) 
    Remove an auto-imported template
 public synchronized  void removeAutoInclude(String templateName) 
    remove a template from the auto-include list.
 public  void setAllSharedVariables(TemplateHashModelEx hash) throws TemplateModelException 
    Adds all object in the hash as shared variable to the configuration.

    Never use TemplateModel implementation that is not thread-safe for shared variables, if the configuration is used by multiple threads! It is the typical situation for Servlet based Web sites.

 public synchronized  void setAutoImports(Map map) 
    set a map of namespace names to templates for auto-importing a set of templates. Note that all previous auto-imports are removed.
 public synchronized  void setAutoIncludes(List templateNames) 
    set the list of automatically included templates. Note that all previous auto-includes are removed.
 public synchronized  void setCacheStorage(CacheStorage storage) 
 public  void setClassForTemplateLoading(Class clazz,
    String pathPrefix) 
    Sets a class relative to which we do the Class.getResource() call to load templates.
 public static  void setDefaultConfiguration(Configuration config) 
Deprecated! Using - the "default" Configuration instance can easily lead to erroneous, unpredictable behaviour. See more here... .

 public  void setDefaultEncoding(String encoding) 
    Sets the default encoding for converting bytes to characters when reading template files in a locale for which no explicit encoding was specified. Defaults to default system encoding.
 public  void setDirectoryForTemplateLoading(File dir) throws IOException 
    Set the explicit directory from which to load templates.
 public  void setEncoding(Locale locale,
    String encoding) 
    Sets the character set encoding to use for templates of a given locale. If there is no explicit encoding set for some locale, then the default encoding will be used, what you can set with #setDefaultEncoding .
 public  void setLocalizedLookup(boolean localizedLookup) 
    Enables/disables localized template lookup. Enabled by default. This method is thread-safe and can be called while the engine works.
 public  void setServletContextForTemplateLoading(Object sctxt,
    String path) 
    Sets the servlet context from which to load templates
 public  void setSetting(String key,
    String value) throws TemplateException 
    Sets a setting by name and string value. In additional to the settings understood by the super method , it understands these:
    • "auto_import": Sets the list of auto-imports. Example of valid value:
      /lib/form.ftl as f, /lib/widget as w, "/lib/evil name.ftl" as odd See: #setAutoImports
    • "auto_include": Sets the list of auto-includes. Example of valid value:
      /include/common.ftl, "/include/evil name.ftl" See: #setAutoIncludes
    • "default_encoding": The name of the charset, such as "UTF-8". See: #setDefaultEncoding
    • "localized_lookup": "true", "false", "yes", "no", "t", "f", "y", "n". Case insensitive. See: #setLocalizedLookup
    • "strict_syntax": "true", "false", etc. See: #setStrictSyntaxMode
    • "whitespace_stripping": "true", "false", etc. See: #setWhitespaceStripping
    • "cache_storage": 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 a freemarker.cache.MruCacheStorage will be used with the maximum strong and soft sizes specified with the setting value. Examples of valid setting values:
      Setting valuemax. strong sizemax. soft size
      "strong:50, soft:500"50500
      "strong:100, soft"100Integer.MAX_VALUE
      "strong:100"1000
      "soft:100"0100
      "strong"Integer.MAX_VALUE0
      "soft"0Integer.MAX_VALUE
      The value is not case sensitive. The order of soft and strong entries is not significant. See also: #setCacheStorage
    • "template_update_delay": Valid positive integer, the update delay measured in seconds. See: #setTemplateUpdateDelay
    • "tag_syntax": Must be one of: "auto_detect", "angle_bracket", "square_bracket".
 public  void setSharedVariable(String name,
    TemplateModel tm) 
    Adds a shared variable to the configuration. Shared variables are variables that are visible as top-level variables for all templates which use this configuration, if the data model does not contain a variable with the same name.

    Never use TemplateModel implementation that is not thread-safe for shared variables, if the configuration is used by multiple threads! It is the typical situation for Servlet based Web sites.

 public  void setSharedVariable(String name,
    Object obj) throws TemplateModelException 
 public  void setStrictSyntaxMode(boolean b) 
    Sets whether directives such as if, else, etcetera must be written as #if, #else, etcetera. Any tag not starting with <# or </# is considered as plain text and will go to the output as is. Tag starting with <# or </# must be valid FTL tag, or else the template is invalid (i.e. <#noSuchDirective> is an error).
 public  void setTagSyntax(int tagSyntax) 
 public synchronized  void setTemplateLoader(TemplateLoader loader) 
 public  void setTemplateUpdateDelay(int delay) 
    Set the time in seconds that must elapse before checking whether there is a newer version of a template file. This method is thread-safe and can be called while the engine works.
 public  void setWhitespaceStripping(boolean b) 
    Sets whether the FTL parser will try to remove superfluous white-space around certain FTL tags.