|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectfreemarker.core.Configurable
freemarker.template.Configuration
public class Configuration
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.
Nested Class Summary |
---|
Nested classes/interfaces inherited from class freemarker.core.Configurable |
---|
Configurable.UnknownSettingException |
Field Summary | |
---|---|
static int |
ANGLE_BRACKET_TAG_SYNTAX
|
static int |
AUTO_DETECT_TAG_SYNTAX
|
static java.lang.String |
AUTO_IMPORT_KEY
|
static java.lang.String |
AUTO_INCLUDE_KEY
|
static java.lang.String |
CACHE_STORAGE_KEY
|
static java.lang.String |
DEFAULT_ENCODING_KEY
|
static java.lang.String |
DEFAULT_INCOMPATIBLE_ENHANCEMENTS
|
static java.lang.String |
INCOMPATIBLE_ENHANCEMENTS
|
static java.lang.String |
LOCALIZED_LOOKUP_KEY
|
static int |
PARSED_DEFAULT_INCOMPATIBLE_ENHANCEMENTS
|
static int |
SQUARE_BRACKET_TAG_SYNTAX
|
static java.lang.String |
STRICT_SYNTAX_KEY
|
static java.lang.String |
TAG_SYNTAX_KEY
|
static java.lang.String |
TEMPLATE_UPDATE_DELAY_KEY
|
static java.lang.String |
WHITESPACE_STRIPPING_KEY
|
Constructor Summary | |
---|---|
Configuration()
|
Method Summary | |
---|---|
void |
addAutoImport(java.lang.String namespace,
java.lang.String template)
Add an auto-imported template. |
void |
addAutoInclude(java.lang.String templateName)
add a template to be automatically included at the top of any template that is vended by this Configuration object. |
void |
clearEncodingMap()
Clears language-to-encoding map. |
void |
clearSharedVariables()
Removes all shared variables, except the predefined ones (compress, html_escape, etc.). |
void |
clearTemplateCache()
Removes all entries from the template cache, thus forcing reloading of templates on subsequent getTemplate calls. |
java.lang.Object |
clone()
|
protected void |
doAutoImportsAndIncludes(Environment env)
|
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. |
java.lang.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. |
java.lang.String |
getEncoding(java.util.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. |
java.lang.String |
getIncompatibleEnhancements()
|
boolean |
getLocalizedLookup()
Returns if localized template lookup is enabled or not. |
int |
getParsedIncompatibleEnhancements()
Same as getIncompatibleEnhancements() , but returns the version
as an int, according to
StringUtil.versionStringToInt(String) . |
TemplateModel |
getSharedVariable(java.lang.String name)
Gets a shared variable. |
java.util.Set |
getSharedVariableNames()
Returns the set containing the names of all defined shared variables. |
boolean |
getStrictSyntaxMode()
Tells whether directives such as if, else, etcetera must be written as #if, #else, etcetera. |
int |
getTagSyntax()
See setTagSyntax(int) to see the returned number. |
Template |
getTemplate(java.lang.String name)
Equivalent to getTemplate(name, thisCfg.getLocale(), thisCfg.getEncoding(thisCfg.getLocale()), true). |
Template |
getTemplate(java.lang.String name,
java.util.Locale locale)
Equivalent to getTemplate(name, locale, thisCfg.getEncoding(locale), true). |
Template |
getTemplate(java.lang.String name,
java.util.Locale locale,
java.lang.String encoding)
Equivalent to getTemplate(name, locale, encoding, true). |
Template |
getTemplate(java.lang.String name,
java.util.Locale locale,
java.lang.String encoding,
boolean parse)
Retrieves a template specified by a name and locale, interpreted using the specified character encoding, either parsed or unparsed. |
Template |
getTemplate(java.lang.String name,
java.lang.String encoding)
Equivalent to getTemplate(name, thisCfg.getLocale(), encoding, true). |
TemplateLoader |
getTemplateLoader()
|
static java.lang.String |
getVersionNumber()
Returns FreeMarker version number string. |
boolean |
getWhitespaceStripping()
Gets whether the FTL parser will try to remove superfluous white-space around certain FTL tags. |
void |
loadBuiltInEncodingMap()
Loads a preset language-to-encoding map. |
void |
removeAutoImport(java.lang.String namespace)
Remove an auto-imported template |
void |
removeAutoInclude(java.lang.String templateName)
remove a template from the auto-include list. |
void |
removeTemplateFromCache(java.lang.String name)
Equivalent to removeTemplateFromCache(name, thisCfg.getLocale(), thisCfg.getEncoding(thisCfg.getLocale()), true). |
void |
removeTemplateFromCache(java.lang.String name,
java.util.Locale locale)
Equivalent to removeTemplateFromCache(name, locale, thisCfg.getEncoding(locale), true). |
void |
removeTemplateFromCache(java.lang.String name,
java.util.Locale locale,
java.lang.String encoding)
Equivalent to removeTemplateFromCache(name, locale, encoding, true). |
void |
removeTemplateFromCache(java.lang.String name,
java.util.Locale locale,
java.lang.String encoding,
boolean parse)
Removes a template from the template cache, hence forcing the re-loading of it when it's next time requested. |
void |
removeTemplateFromCache(java.lang.String name,
java.lang.String encoding)
Equivalent to removeTemplateFromCache(name, thisCfg.getLocale(), encoding, true). |
void |
setAllSharedVariables(TemplateHashModelEx hash)
Adds all object in the hash as shared variable to the configuration. |
void |
setAutoImports(java.util.Map map)
set a map of namespace names to templates for auto-importing a set of templates. |
void |
setAutoIncludes(java.util.List templateNames)
set the list of automatically included templates. |
void |
setCacheStorage(CacheStorage storage)
Sets the CacheStorage used for caching Template -s. |
void |
setClassForTemplateLoading(java.lang.Class clazz,
java.lang.String pathPrefix)
Sets a class relative to which we do the Class.getResource() call to load templates. |
static void |
setDefaultConfiguration(Configuration config)
Deprecated. Using the "default" Configuration instance can
easily lead to erroneous, unpredictable behaviour.
See more here... . |
void |
setDefaultEncoding(java.lang.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. |
void |
setDirectoryForTemplateLoading(java.io.File dir)
Set the explicit directory from which to load templates. |
void |
setEncoding(java.util.Locale locale,
java.lang.String encoding)
Sets the character set encoding to use for templates of a given locale. |
void |
setIncompatibleEnhancements(java.lang.String version)
Sets which of the slightly non-backward compatible bugfixes/enhancements should be enabled. |
void |
setLocalizedLookup(boolean localizedLookup)
Enables/disables localized template lookup. |
void |
setServletContextForTemplateLoading(java.lang.Object sctxt,
java.lang.String path)
Sets the servlet context from which to load templates |
void |
setSetting(java.lang.String key,
java.lang.String value)
Sets a setting by name and string value. |
void |
setSharedVariable(java.lang.String name,
java.lang.Object obj)
Adds shared variable to the configuration. |
void |
setSharedVariable(java.lang.String name,
TemplateModel tm)
Adds a shared variable to the configuration. |
void |
setStrictSyntaxMode(boolean b)
Sets whether directives such as if, else, etcetera must be written as #if, #else, etcetera. |
void |
setTagSyntax(int tagSyntax)
Determines the syntax of the template files (angle bracket VS square bracket) that has no |
void |
setTemplateLoader(TemplateLoader loader)
Sets a template loader that is used to look up and load templates. |
void |
setTemplateUpdateDelay(int delay)
Set the time in seconds that must elapse before checking whether there is a newer version of a template file. |
void |
setWhitespaceStripping(boolean b)
Sets whether the FTL parser will try to remove superfluous white-space around certain FTL tags. |
Methods inherited from class java.lang.Object |
---|
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final java.lang.String DEFAULT_ENCODING_KEY
public static final java.lang.String LOCALIZED_LOOKUP_KEY
public static final java.lang.String STRICT_SYNTAX_KEY
public static final java.lang.String WHITESPACE_STRIPPING_KEY
public static final java.lang.String CACHE_STORAGE_KEY
public static final java.lang.String TEMPLATE_UPDATE_DELAY_KEY
public static final java.lang.String AUTO_IMPORT_KEY
public static final java.lang.String AUTO_INCLUDE_KEY
public static final java.lang.String TAG_SYNTAX_KEY
public static final java.lang.String INCOMPATIBLE_ENHANCEMENTS
public static final int AUTO_DETECT_TAG_SYNTAX
public static final int ANGLE_BRACKET_TAG_SYNTAX
public static final int SQUARE_BRACKET_TAG_SYNTAX
public static final java.lang.String DEFAULT_INCOMPATIBLE_ENHANCEMENTS
public static final int PARSED_DEFAULT_INCOMPATIBLE_ENHANCEMENTS
Constructor Detail |
---|
public Configuration()
Method Detail |
---|
public java.lang.Object clone()
clone
in class Configurable
public void loadBuiltInEncodingMap()
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 |
clearEncodingMap()
,
setEncoding(java.util.Locale, java.lang.String)
public void clearEncodingMap()
loadBuiltInEncodingMap()
,
setEncoding(java.util.Locale, java.lang.String)
public static Configuration getDefaultConfiguration()
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.
public static void setDefaultConfiguration(Configuration config)
Configuration
instance can
easily lead to erroneous, unpredictable behaviour.
See more here...
.
getDefaultConfiguration()
.
public void setTemplateLoader(TemplateLoader loader)
setClassForTemplateLoading(Class, String)
,
setDirectoryForTemplateLoading(File)
, and
setServletContextForTemplateLoading(Object, String)
. By default,
a multi-loader is used that first tries to load a template from the file
in the current directory, then from a resource on the classpath.
public TemplateLoader getTemplateLoader()
setTemplateLoader(freemarker.cache.TemplateLoader)
public void setCacheStorage(CacheStorage storage)
CacheStorage
used for caching Template
-s. The
default is a SoftCacheStorage
. If the total size of the Template
objects is significant but most templates are used rarely, using a
MruCacheStorage
instead might be advisable. If you don't want caching at
all, use NullCacheStorage
(you can't use null).
public void setDirectoryForTemplateLoading(java.io.File dir) throws java.io.IOException
java.io.IOException
public void setServletContextForTemplateLoading(java.lang.Object sctxt, java.lang.String path)
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/public void setClassForTemplateLoading(java.lang.Class clazz, java.lang.String pathPrefix)
public void setTemplateUpdateDelay(int delay)
public void setStrictSyntaxMode(boolean b)
public boolean getStrictSyntaxMode()
setStrictSyntaxMode(boolean)
public void setIncompatibleEnhancements(java.lang.String version)
This setting doesn't affect non-backward compatible security fixes; they are always enabled. This setting also doesn't affect enhancements where there's a significant chance of breaking existing applications.
Using this setting is a good way of preparing for the next minor (2nd) version number increase. When that happens, not only the default value of this setting changes, but it's possible that older values become unsupported.
Currently affected fixes/enhancements:
public java.lang.String getIncompatibleEnhancements()
public int getParsedIncompatibleEnhancements()
getIncompatibleEnhancements()
, but returns the version
as an int, according to
StringUtil.versionStringToInt(String)
.
public void setWhitespaceStripping(boolean b)
public boolean getWhitespaceStripping()
setWhitespaceStripping(boolean)
public void setTagSyntax(int tagSyntax)
tagSyntax
parameter must be one of:
AUTO_DETECT_TAG_SYNTAX
:
use the syntax of the first FreeMarker tag (can be anything, like list,
include, user defined, ...etc)
ANGLE_BRACKET_TAG_SYNTAX
:
use the angle bracket syntax (the normal syntax)
SQUARE_BRACKET_TAG_SYNTAX
:
use the square bracket syntax
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.
public int getTagSyntax()
setTagSyntax(int)
to see the returned number.
public Template getTemplate(java.lang.String name) throws java.io.IOException
java.io.IOException
public Template getTemplate(java.lang.String name, java.util.Locale locale) throws java.io.IOException
java.io.IOException
public Template getTemplate(java.lang.String name, java.lang.String encoding) throws java.io.IOException
java.io.IOException
public Template getTemplate(java.lang.String name, java.util.Locale locale, java.lang.String encoding) throws java.io.IOException
java.io.IOException
public Template getTemplate(java.lang.String name, java.util.Locale locale, java.lang.String encoding, boolean parse) throws java.io.IOException
TemplateCache.getTemplate(String, Locale, String, boolean)
.
java.io.FileNotFoundException
- if the template could not be found.
java.io.IOException
- if there was a problem loading the template.
ParseException
- (extends IOException
) if the template is syntactically bad.public void setDefaultEncoding(java.lang.String encoding)
public java.lang.String getDefaultEncoding()
public java.lang.String getEncoding(java.util.Locale loc)
setEncoding(Locale, String)
or loadBuiltInEncodingMap()
.
loc
- the locale
public void setEncoding(java.util.Locale locale, java.lang.String encoding)
setDefaultEncoding(java.lang.String)
.
clearEncodingMap()
,
loadBuiltInEncodingMap()
public void setSharedVariable(java.lang.String name, TemplateModel tm)
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.
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.setSharedVariable(String,Object)
,
setAllSharedVariables(freemarker.template.TemplateHashModelEx)
public java.util.Set getSharedVariableNames()
public void setSharedVariable(java.lang.String name, java.lang.Object obj) throws TemplateModelException
Configurable.getObjectWrapper()
to wrap the
obj
.
TemplateModelException
setSharedVariable(String,TemplateModel)
,
setAllSharedVariables(freemarker.template.TemplateHashModelEx)
public void setAllSharedVariables(TemplateHashModelEx hash) throws TemplateModelException
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.
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.
TemplateModelException
setSharedVariable(String,Object)
,
setSharedVariable(String,TemplateModel)
public TemplateModel getSharedVariable(java.lang.String name)
setSharedVariable(String,Object)
,
setSharedVariable(String,TemplateModel)
,
setAllSharedVariables(freemarker.template.TemplateHashModelEx)
public void clearSharedVariables()
public void clearTemplateCache()
getTemplate
calls.
This method is thread-safe and can be called while the engine works.
public void removeTemplateFromCache(java.lang.String name) throws java.io.IOException
java.io.IOException
public void removeTemplateFromCache(java.lang.String name, java.util.Locale locale) throws java.io.IOException
java.io.IOException
public void removeTemplateFromCache(java.lang.String name, java.lang.String encoding) throws java.io.IOException
java.io.IOException
public void removeTemplateFromCache(java.lang.String name, java.util.Locale locale, java.lang.String encoding) throws java.io.IOException
java.io.IOException
public void removeTemplateFromCache(java.lang.String name, java.util.Locale locale, java.lang.String encoding, boolean parse) throws java.io.IOException
setTemplateUpdateDelay(int)
alone does.
For the meaning of the parameters, see
getTemplate(String, Locale, String, boolean)
.
java.io.IOException
public boolean getLocalizedLookup()
public void setLocalizedLookup(boolean localizedLookup)
public void setSetting(java.lang.String key, java.lang.String value) throws TemplateException
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(java.util.Map)
"auto_include"
: Sets the list of auto-includes. Example of valid value:
/include/common.ftl, "/include/evil name.ftl"
See: setAutoIncludes(java.util.List)
"default_encoding"
: The name of the charset, such as "UTF-8"
.
See: setDefaultEncoding(java.lang.String)
"localized_lookup"
:
"true"
, "false"
, "yes"
, "no"
,
"t"
, "f"
, "y"
, "n"
.
Case insensitive.
See: setLocalizedLookup(boolean)
"strict_syntax"
: "true"
, "false"
, etc.
See: setStrictSyntaxMode(boolean)
"whitespace_stripping"
: "true"
, "false"
, etc.
See: setWhitespaceStripping(boolean)
"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 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
|
setCacheStorage(freemarker.cache.CacheStorage)
"template_update_delay"
: Valid positive integer, the
update delay measured in seconds.
See: setTemplateUpdateDelay(int)
"tag_syntax"
: Must be one of:
"auto_detect"
, "angle_bracket"
,
"square_bracket"
.
"incompatible_enhancements"
: The FreeMarker version
number where the desired enhancements were already implemented.
See: setIncompatibleEnhancements(String)
.
setSetting
in class Configurable
key
- the name of the setting.value
- the string that describes the new value of the setting.
UnknownSettingException
- if the key is wrong.
TemplateException
- if the new value of the setting can't be set
for any other reasons.public void addAutoImport(java.lang.String namespace, java.lang.String template)
namespace
- the name of the namespace into which the template is importedtemplate
- the name of the templatepublic void removeAutoImport(java.lang.String namespace)
namespace
- the name of the namespace into which the template was importedpublic void setAutoImports(java.util.Map map)
protected void doAutoImportsAndIncludes(Environment env) throws TemplateException, java.io.IOException
doAutoImportsAndIncludes
in class Configurable
TemplateException
java.io.IOException
public void addAutoInclude(java.lang.String templateName)
templateName
- the lookup name of the template.public void setAutoIncludes(java.util.List templateNames)
public void removeAutoInclude(java.lang.String templateName)
templateName
- the lookup name of the template in question.public static java.lang.String getVersionNumber()
"2.2.5"
, "2.3pre13"
,
"2.3pre13mod"
, "2.3rc1"
, "2.3"
,
"3.0"
.
Notes on FreeMarker version numbering rules:
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |