| java.lang.Object
 freemarker.core.Configurable
freemarker.template.Configuration
| Configuration | | public class Configuration extends Configurable implements Cloneable(Code) | | 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
Configuration.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.
author:
Jonathan Revusky
author:
Attila Szegedi
version:
$Id: Configuration.java,v 1.122.2.5 2006/04/26 21:25:19 ddekany Exp $ |
| Method Summary | |
| public synchronized void | addAutoImport(String namespace, String template)
Add an auto-imported template. | | 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. | | public Object | clone()
| | void | doAutoImports(Environment env)
| | void | doAutoIncludes(Environment env)
| | public static Configuration | getDefaultConfiguration()
Returns the default (singleton) Configuration object. | | 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. | | 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. | | public boolean | getLocalizedLookup()
Returns if localized template lookup is enabled or not. | | public TemplateModel | getSharedVariable(String name)
Gets a shared variable. | | 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. | | 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)
Equivalent to getTemplate(name, thisCfg.getLocale(), thisCfg.getEncoding(thisCfg.getLocale()), true). | | public Template | getTemplate(String name, Locale locale)
Equivalent to getTemplate(name, locale, thisCfg.getEncoding(locale), true). | | public Template | getTemplate(String name, String encoding)
Equivalent to getTemplate(name, thisCfg.getLocale(), encoding, true). | | public Template | getTemplate(String name, Locale locale, String encoding)
Equivalent to getTemplate(name, locale, encoding, true). | | public Template | getTemplate(String name, Locale locale, String encoding, boolean parse)
Retrieves a template specified by a name and locale, interpreted using
the specified character encoding, either parsed or unparsed. | | public TemplateLoader | getTemplateLoader()
| | public static String | getVersionNumber()
Returns FreeMarker version number string. | | 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. | | public synchronized void | removeAutoImport(String namespace)
| | public synchronized void | removeAutoInclude(String templateName)
remove a template from the auto-include list. | | public void | setAllSharedVariables(TemplateHashModelEx hash)
Adds all object in the hash as shared variable to the configuration. | | public synchronized void | setAutoImports(Map map)
set a map of namespace names to templates for auto-importing
a set of templates. | | public synchronized void | setAutoIncludes(List templateNames)
set the list of automatically included templates. | | 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)
Sets the Configuration object that will be retrieved from future calls
to
Configuration.getDefaultConfiguration() . | | 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. | | public void | setDirectoryForTemplateLoading(File dir)
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. | | public void | setLocalizedLookup(boolean localizedLookup)
Enables/disables localized template lookup. | | public void | setServletContextForTemplateLoading(Object sctxt, String path)
Sets the servlet context from which to load templates
Parameters:
sctxt - the ServletContext object. | | public void | setSetting(String key, String value)
Sets a setting by name and string value.
In additional to the settings understood by
Configurable.setSetting the super method , it understands these:
"auto_import": Sets the list of auto-imports. | | public void | setSharedVariable(String name, TemplateModel tm)
Adds a shared variable to the configuration. | | public void | setSharedVariable(String name, Object obj)
Adds shared variable to the configuration. | | 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. | | public void | setTagSyntax(int tagSyntax)
Determines the syntax of the template files (angle bracket VS square bracket)
that has no ftl directive in it. | | public synchronized void | setTemplateLoader(TemplateLoader loader)
Sets a template loader that is used to look up and load templates.
By providing your own template loader, you can customize the way
templates are loaded. | | 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. | | public void | setWhitespaceStripping(boolean b)
Sets whether the FTL parser will try to remove
superfluous white-space around certain FTL tags. |
| ANGLE_BRACKET_TAG_SYNTAX | | final public static int ANGLE_BRACKET_TAG_SYNTAX(Code) | | |
| AUTO_DETECT_TAG_SYNTAX | | final public static int AUTO_DETECT_TAG_SYNTAX(Code) | | |
| AUTO_IMPORT_KEY | | final public static String AUTO_IMPORT_KEY(Code) | | |
| AUTO_INCLUDE_KEY | | final public static String AUTO_INCLUDE_KEY(Code) | | |
| CACHE_STORAGE_KEY | | final public static String CACHE_STORAGE_KEY(Code) | | |
| DEFAULT_ENCODING_KEY | | final public static String DEFAULT_ENCODING_KEY(Code) | | |
| LOCALIZED_LOOKUP_KEY | | final public static String LOCALIZED_LOOKUP_KEY(Code) | | |
| SQUARE_BRACKET_TAG_SYNTAX | | final public static int SQUARE_BRACKET_TAG_SYNTAX(Code) | | |
| STRICT_SYNTAX_KEY | | final public static String STRICT_SYNTAX_KEY(Code) | | |
| TAG_SYNTAX_KEY | | final public static String TAG_SYNTAX_KEY(Code) | | |
| TEMPLATE_UPDATE_DELAY_KEY | | final public static String TEMPLATE_UPDATE_DELAY_KEY(Code) | | |
| WHITESPACE_STRIPPING_KEY | | final public static String WHITESPACE_STRIPPING_KEY(Code) | | |
| Configuration | | public Configuration()(Code) | | |
| addAutoImport | | public synchronized void addAutoImport(String namespace, String template)(Code) | | 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
Parameters:
template - the name of the template |
| addAutoInclude | | public synchronized void addAutoInclude(String templateName)(Code) | | 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. |
| clearSharedVariables | | public void clearSharedVariables()(Code) | | Removes all shared variables, except the predefined ones (compress, html_escape, etc.).
|
| clearTemplateCache | | public void clearTemplateCache()(Code) | | 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.
|
| getDefaultConfiguration | | public static Configuration getDefaultConfiguration()(Code) | | 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.
ConfigurationConfigurationConfiguration |
| getDefaultEncoding | | public String getDefaultEncoding()(Code) | | 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.
|
| getLocalizedLookup | | public boolean getLocalizedLookup()(Code) | | Returns if localized template lookup is enabled or not.
This method is thread-safe and can be called while the engine works.
|
| getSharedVariableNames | | public Set getSharedVariableNames()(Code) | | 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.
|
| getStrictSyntaxMode | | public boolean getStrictSyntaxMode()(Code) | | Tells whether directives such as if, else, etcetera
must be written as #if, #else, etcetera.
See Also: Configuration.setStrictSyntaxMode |
| getTagSyntax | | public int getTagSyntax()(Code) | | whether the alternative square bracketsyntax is set as the default |
| getTemplate | | public Template getTemplate(String name) throws IOException(Code) | | Equivalent to getTemplate(name, thisCfg.getLocale(), thisCfg.getEncoding(thisCfg.getLocale()), true).
|
| getVersionNumber | | public static String getVersionNumber()(Code) | | 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.
|
| getWhitespaceStripping | | public boolean getWhitespaceStripping()(Code) | | Gets whether the FTL parser will try to remove
superfluous white-space around certain FTL tags.
See Also: Configuration.setWhitespaceStripping |
| loadBuiltInEncodingMap | | public void loadBuiltInEncodingMap()(Code) | | 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:
| ar | ISO-8859-6 |
| be | ISO-8859-5 |
| bg | ISO-8859-5 |
| ca | ISO-8859-1 |
| cs | ISO-8859-2 |
| da | ISO-8859-1 |
| de | ISO-8859-1 |
| el | ISO-8859-7 |
| en | ISO-8859-1 |
| es | ISO-8859-1 |
| et | ISO-8859-1 |
| fi | ISO-8859-1 |
| fr | ISO-8859-1 |
| hr | ISO-8859-2 |
| hu | ISO-8859-2 |
| is | ISO-8859-1 |
| it | ISO-8859-1 |
| iw | ISO-8859-8 |
| ja | Shift_JIS |
| ko | EUC-KR |
| lt | ISO-8859-2 |
| lv | ISO-8859-2 |
| mk | ISO-8859-5 |
| nl | ISO-8859-1 |
| no | ISO-8859-1 |
| pl | ISO-8859-2 |
| pt | ISO-8859-1 |
| ro | ISO-8859-2 |
| ru | ISO-8859-5 |
| sh | ISO-8859-5 |
| sk | ISO-8859-2 |
| sl | ISO-8859-2 |
| sq | ISO-8859-2 |
| sr | ISO-8859-5 |
| sv | ISO-8859-1 |
| tr | ISO-8859-9 |
| uk | ISO-8859-5 |
| zh | GB2312 |
| zh_TW | Big5 |
See Also: Configuration.clearEncodingMap
See Also: Configuration.setEncoding |
| removeAutoImport | | public synchronized void removeAutoImport(String namespace)(Code) | | Remove an auto-imported template
Parameters:
namespace - the name of the namespace into which the template was imported |
| removeAutoInclude | | public synchronized void removeAutoInclude(String templateName)(Code) | | remove a template from the auto-include list.
Parameters:
templateName - the lookup name of the template in question. |
| setAutoImports | | public synchronized void setAutoImports(Map map)(Code) | | set a map of namespace names to templates for auto-importing
a set of templates. Note that all previous auto-imports are removed.
|
| setAutoIncludes | | public synchronized void setAutoIncludes(List templateNames)(Code) | | set the list of automatically included templates.
Note that all previous auto-includes are removed.
|
| setClassForTemplateLoading | | public void setClassForTemplateLoading(Class clazz, String pathPrefix)(Code) | | Sets a class relative to which we do the
Class.getResource() call to load templates.
|
| setDefaultEncoding | | public void setDefaultEncoding(String encoding)(Code) | | 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.
|
| setDirectoryForTemplateLoading | | public void setDirectoryForTemplateLoading(File dir) throws IOException(Code) | | Set the explicit directory from which to load templates.
|
| setLocalizedLookup | | public void setLocalizedLookup(boolean localizedLookup)(Code) | | Enables/disables localized template lookup. Enabled by default.
This method is thread-safe and can be called while the engine works.
|
| setServletContextForTemplateLoading | | public void setServletContextForTemplateLoading(Object sctxt, String path)(Code) | | Sets the servlet context from which to load templates
Parameters:
sctxt - the ServletContext object. Note that the type is Objectto prevent class loading errors when user who uses FreeMarker not forservlets has no javax.servlet in the CLASSPATH.
Parameters:
path - the path relative to the ServletContext.If this path is absolute, it is taken to be relativeto 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/ |
| setSetting | | public void setSetting(String key, String value) throws TemplateException(Code) | | Sets a setting by name and string value.
In additional to the settings understood by
Configurable.setSetting 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:
Configuration.setAutoImports "auto_include": Sets the list of auto-includes. Example of valid value:
/include/common.ftl, "/include/evil name.ftl"
See:
Configuration.setAutoIncludes "default_encoding": The name of the charset, such as "UTF-8".
See:
Configuration.setDefaultEncoding "localized_lookup":
"true", "false", "yes", "no",
"t", "f", "y", "n".
Case insensitive.
See:
Configuration.setLocalizedLookup "strict_syntax": "true", "false", etc.
See:
Configuration.setStrictSyntaxMode "whitespace_stripping": "true", "false", etc.
See:
Configuration.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 value | max. strong size | max. soft size
|
|---|
"strong:50, soft:500" | 50 | 500
| "strong:100, soft" | 100 | Integer.MAX_VALUE
| "strong:100" | 100 | 0
| "soft:100" | 0 | 100
| "strong" | Integer.MAX_VALUE | 0
| "soft" | 0 | Integer.MAX_VALUE
|
The value is not case sensitive. The order of soft and strong
entries is not significant.
See also:
Configuration.setCacheStorage "template_update_delay": Valid positive integer, the
update delay measured in seconds.
See:
Configuration.setTemplateUpdateDelay "tag_syntax": Must be one of:
"auto_detect", "angle_bracket",
"square_bracket".
Parameters:
key - the name of the setting.
Parameters:
value - the string that describes the new value of the setting.
throws:
UnknownSettingException - if the key is wrong.
throws:
TemplateException - if the new value of the setting can't be setfor any other reasons. |
| setSharedVariable | | public void setSharedVariable(String name, TemplateModel tm)(Code) | | 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 replacethat.
See Also: Configuration.setSharedVariable(String,Object)
See Also: Configuration.setAllSharedVariables |
| setStrictSyntaxMode | | public void setStrictSyntaxMode(boolean b)(Code) | | 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).
|
| setTagSyntax | | public void setTagSyntax(int tagSyntax)(Code) | | 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
Configuration.ANGLE_BRACKET_TAG_SYNTAX is the
default for better backward compatibility. Starting from 2.4.x
Configuration.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.
|
| setTemplateUpdateDelay | | public void setTemplateUpdateDelay(int delay)(Code) | | 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.
|
| setWhitespaceStripping | | public void setWhitespaceStripping(boolean b)(Code) | | Sets whether the FTL parser will try to remove
superfluous white-space around certain FTL tags.
|
|
|