|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectfreemarker.core.Configurable
freemarker.template.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 inherited from class freemarker.core.Configurable |
Configurable.UnknownSettingException |
Field Summary | |
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 |
LOCALIZED_LOOKUP_KEY
|
static java.lang.String |
STRICT_SYNTAX_KEY
|
static java.lang.String |
TEMPLATE_UPDATE_DELAY_KEY
|
static java.lang.String |
WHITESPACE_STRIPPING_KEY
|
Fields inherited from class freemarker.core.Configurable |
ARITHMETIC_ENGINE_KEY, BOOLEAN_FORMAT_KEY, CLASSIC_COMPATIBLE_KEY, DATE_FORMAT_KEY, DATETIME_FORMAT_KEY, LOCALE_KEY, NUMBER_FORMAT_KEY, OBJECT_WRAPPER_KEY, TEMPLATE_EXCEPTION_HANDLER_KEY, TIME_FORMAT_KEY, TIME_ZONE_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()
|
static Configuration |
getDefaultConfiguration()
Returns the default (singleton) Configuration object. |
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. |
boolean |
getLocalizedLookup()
Returns if localized template lookup is enabled or not. |
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. |
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 |
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)
|
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)
Sets the Configuration object that will be retrieved from future calls to getDefaultConfiguration() . |
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 |
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 |
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
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()
public static void setDefaultConfiguration(Configuration config)
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)
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 setWhitespaceStripping(boolean b)
public boolean getWhitespaceStripping()
setWhitespaceStripping(boolean)
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 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_imports"
: 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_includes"
: 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)
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)
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 |