Package freemarker.template

Class Configuration

  • All Implemented Interfaces:
    Scope, TemplateHashModel, TemplateHashModelEx, TemplateModel, Cloneable
    public class Configuration
extends Configurable
implements Cloneable, Scope
    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.

    • Constructor Detail

      • Configuration

        public Configuration()

    • Method Detail

      • setTemplateCache

        public void setTemplateCache​(TemplateCache cache)

      • loadBuiltInEncodingMap

        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
        See Also:
        clearEncodingMap(), setEncoding(java.util.Locale, java.lang.String)

      • getDefaultConfiguration

        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.

      • getCurrentConfiguration

        public static Configuration getCurrentConfiguration()
        Returns:
        the Configuration object that is being used in this template processing thread.

      • getCurrentObjectWrapper

        public static ObjectWrapper getCurrentObjectWrapper()
        Returns:
        the ObjectWrapper object that is being used in this template processing thread.

      • setDefaultConfiguration

        public static void setDefaultConfiguration​(Configuration config)
        Deprecated.
        Using the "default" Configuration instance can easily lead to erroneous, unpredictable behaviour. See more here....
        Sets the Configuration object that will be retrieved from future calls to getDefaultConfiguration().

      • setCacheStorage

        public void setCacheStorage​(CacheStorage storage)

      • setDirectoryForTemplateLoading

        public void setDirectoryForTemplateLoading​(File dir)
                                    throws IOException
        Set the explicit directory from which to load templates.
        Throws:
        IOException

      • setServletContextForTemplateLoading

        public void setServletContextForTemplateLoading​(Object sctxt,
                                                String path)
        Sets the servlet context from which to load templates
        Parameters:
        sctxt - the ServletContext object. Note that the type is Object to prevent class loading errors when user who uses FreeMarker not for servlets has no javax.servlet in the CLASSPATH.
        path - the path relative to the ServletContext. If this path is absolute, it is taken to be relative to the server's URL, i.e. http://myserver.com/ and if the path is relative, it is taken to be relative to the web app context, i.e. http://myserver.context.com/mywebappcontext/

      • setClassForTemplateLoading

        public void setClassForTemplateLoading​(Class clazz,
                                       String pathPrefix)
        Sets a class relative to which we do the Class.getResource() call to load templates.

      • setTemplateUpdateDelay

        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.

      • setTagSyntax

        public void setTagSyntax​(int tagSyntax)
        Determines the syntax of the template files (angle bracket VS square bracket) that has no ftl directive in it. The tagSyntax parameter must be one of:

        In FreeMarker 2.3.x ANGLE_BRACKET_TAG_SYNTAX is the default for better backward compatibility. Starting from 2.4.x AUTO_DETECT_TAG_SYNTAX is the default, so it is recommended to use that even for 2.3.x.

        This setting is ignored for the templates that have ftl directive in it. For those templates the syntax used for the ftl directive determines the syntax.

      • setStrictVariableDefinition

        public void setStrictVariableDefinition​(boolean b)
        Sets whether, by default, templates use strict variable definition syntax, such that any variable created at the top template level must be declared with a #var directive. At the moment, the factory-set default is on.

      • getStrictVariableDefinition

        public boolean getStrictVariableDefinition()
        Returns:
        whether, by default, templates use strict variable definition syntax, such that any variable created at the top template level must be declared with a #var directive. At the moment, the factory-set default is on.

      • setWhitespaceStripping

        public void setWhitespaceStripping​(boolean b)
        Sets whether the FTL parser will try to remove superfluous white-space around certain FTL tags.

      • getWhitespaceStripping

        public boolean getWhitespaceStripping()
        Gets whether the FTL parser will try to remove superfluous white-space around certain FTL tags.
        See Also:
        setWhitespaceStripping(boolean)

      • getTemplate

        public Template getTemplate​(String name)
                     throws IOException
        Equivalent to getTemplate(name, thisCfg.getLocale(), thisCfg.getEncoding(thisCfg.getLocale()), true).
        Throws:
        IOException

      • setDefaultEncoding

        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.

      • getDefaultEncoding

        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.

      • getEncoding

        public String getEncoding​(Locale loc)
        Gets the preferred character encoding for the given locale, or the default encoding if no encoding is set explicitly for the specified locale. You can associate encodings with locales using setEncoding(Locale, String) or loadBuiltInEncodingMap().
        Parameters:
        loc - the locale
        Returns:
        the preferred character encoding for the locale.

      • setSharedVariable

        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.

        Parameters:
        name - the name used to access the data object from your template. If a shared variable with this name already exists, it will replace that.
        See Also:
        setSharedVariable(String,Object), setAllSharedVariables(freemarker.template.TemplateHashModelEx)

      • getSharedVariableNames

        public Set<String> 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.

      • setAllSharedVariables

        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.

        Parameters:
        hash - a hash model whose objects will be copied to the configuration with same names as they are given in the hash. If a shared variable with these names already exist, it will be replaced with those from the map.
        Throws:
        TemplateModelException
        See Also:
        setSharedVariable(String,Object), setSharedVariable(String,TemplateModel)

      • clearSharedVariables

        public void clearSharedVariables()
        Removes all shared variables, except the predefined ones (compress, html_escape, etc.).

      • clearTemplateCache

        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.

      • getLocalizedLookup

        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.

      • setLocalizedLookup

        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.

      • addAutoImport

        public 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.
        Parameters:
        namespace - the name of the namespace into which the template is imported
        template - the name of the template

      • removeAutoImport

        public void removeAutoImport​(String namespace)
        Remove an auto-imported template
        Parameters:
        namespace - the name of the namespace into which the template was imported

      • setAutoImports

        public void setAutoImports​(Map<String,​String> map)
        set a map of namespace names to templates for auto-importing a set of templates. Note that all previous auto-imports are removed.

      • addAutoInclude

        public void addAutoInclude​(String templateName)
        add a template to be automatically included at the top of any template that is vended by this Configuration object.
        Parameters:
        templateName - the lookup name of the template.

      • setAutoIncludes

        public void setAutoIncludes​(List<String> templateNames)
        set the list of automatically included templates. Note that all previous auto-includes are removed.

      • removeAutoInclude

        public void removeAutoInclude​(String templateName)
        remove a template from the auto-include list.
        Parameters:
        templateName - the lookup name of the template in question.

      • addAutoTemplateVisitors

        public void addAutoTemplateVisitors​(freemarker.core.ast.ASTVisitor... visitors)

      • removeAutoTemplateVisitors

        public void removeAutoTemplateVisitors​(freemarker.core.ast.ASTVisitor... visitors)

      • setAutoTemplateVisitors

        public void setAutoTemplateVisitors​(freemarker.core.ast.ASTVisitor... visitors)

      • setSecure

        public void setSecure​(boolean secure)
        Sets whether templates are secured. When templates are secured, they are executing in a protection domain determined by their code source. See SecureTemplateLoader and its implementations for details. When templates are not secured, they are executing in the protection domain of FreeMarker libraries. If your deployment execution of templates from sources you don't control, you should consider using the secured templates feature.
        Parameters:
        secure -
        Throws:
        SecurityException - if there is a SecurityManager in the JVM, isSecure() is true and the calling code doesn't have the "setSecure" FreeMarkerPermission

      • isSecure

        public boolean isSecure()

      • getVersionNumber

        public static String getVersionNumber()
        Returns FreeMarker version.

      • setTolerateParsingProblems

        public void setTolerateParsingProblems​(boolean tolerateParsingProblems)
        Set whether the getTemplate() methods throw exceptions when there is a (recoverable) parsing problem in the template. This would only be set true by certain tools such as FTL-aware editors that work with FTL code that contains syntactical errors.
        Parameters:
        tolerateParsingProblems -

      • getEnclosingScope

        public Scope getEnclosingScope()
        Specified by:
        getEnclosingScope in interface Scope
        Returns:
        null The Configuration is the final fallback scope. It has no enclosing scope.

      • definesVariable

        public boolean definesVariable​(String name)
        Specified by:
        definesVariable in interface Scope
        Returns:
        whether the variable is defined in this specific scope. (It could be defined in a fallback scope and this method will return false.)

      • getTemplate

        public Template getTemplate()
        Specified by:
        getTemplate in interface Scope
        Returns:
        null The Configuration object is not associated with a template.

      • put

        public void put​(String varname,
                TemplateModel value)
        Description copied from interface: Scope
        Set a variable in this scope. This will typically only be used internally by the FreeMarker engine.
        Specified by:
        put in interface Scope

      • get

        public TemplateModel get​(String name)
        Description copied from interface: TemplateHashModel
        Gets a TemplateModel from the hash.
        Specified by:
        get in interface TemplateHashModel
        Parameters:
        name - the name by which the TemplateModel is identified in the template.
        Returns:
        the TemplateModel referred to by the key, or null if not found.

      • resolveVariable

        public TemplateModel resolveVariable​(String name)
        Description copied from interface: Scope
        Evaluates the variable of this name in this scope, falling back to the enclosing Scope if it is not defined in this one.
        Specified by:
        resolveVariable in interface Scope

      • getDirectVariableNames

        public Collection<String> getDirectVariableNames()
        Description copied from interface: Scope
        Returns the names of variables directly managed by this scope (i.e. it does not traverse the chain of enclosing scopes, but limits itself to this scope only).
        Specified by:
        getDirectVariableNames in interface Scope
        Returns:
        a collection of known variable names for this scope, without enclosing scopes. The returned collection should be either immutable, or it should be disconnected from the scope, so any modifications to the collection don't affect the scope.

      • remove

        public TemplateModel remove​(String varname)
        Description copied from interface: Scope
        Removes a variable in this scope. This will typically only be used by FreeMarker engine internals
        Specified by:
        remove in interface Scope

      • size

        public int size()
        Specified by:
        size in interface TemplateHashModelEx
        Returns:
        the number of key/value mappings in the hash.

      • enableRhino

        public boolean enableRhino()
        We're keeping this functionality for now, but if there is no sign anybody is interested in using this, it will likely be removed.
        Returns:
        whether successful

      • enableJython

        public boolean enableJython()
        We're keeping this functionality for now, but if there is no sign anybody is interested in using this, it will likely be removed.
        Returns:
        whether successful

      • enableJRuby

        public boolean enableJRuby()
        We're keeping this functionality for now, but if there is no sign anybody is interested in using this, it will likely be removed.
        Returns:
        whether successful