Prev Class | Next Class | Frames | No Frames |
Summary: Nested | Field | Method | Constr | Detail: Nested | Field | Method | Constr |
java.lang.Object
freemarker.core.Configurable
freemarker.template.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.
Nested Class Summary |
Nested classes/interfaces inherited from class freemarker.core.Configurable | |
Configurable.UnknownSettingException |
Field Summary | |
static int | |
static int | |
static String | |
static String | |
static String | |
static String | |
static String | |
static int | |
static String | |
static String | |
static String | |
static String |
Fields inherited from class freemarker.core.Configurable | |
ARITHMETIC_ENGINE_KEY , BOOLEAN_FORMAT_KEY , CLASSIC_COMPATIBLE_KEY , DATETIME_FORMAT_KEY , DATE_FORMAT_KEY , LOCALE_KEY , NUMBER_FORMAT_KEY , OBJECT_WRAPPER_KEY , OUTPUT_ENCODING_KEY , STRICT_BEAN_MODELS , TEMPLATE_EXCEPTION_HANDLER_KEY , TIME_FORMAT_KEY , TIME_ZONE_KEY , URL_ESCAPING_CHARSET_KEY |
Constructor Summary | |
Method Summary | |
void |
|
void |
|
void |
|
void |
|
void |
|
Object |
|
static Configuration |
|
String |
|
String |
|
boolean |
|
TemplateModel |
|
Set |
|
boolean |
|
int | |
Template |
|
Template |
|
Template |
|
Template |
|
Template |
|
TemplateLoader | |
static String |
|
boolean |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
static void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
void |
|
public static final int ANGLE_BRACKET_TAG_SYNTAX
- Field Value:
- 1
public static final int AUTO_DETECT_TAG_SYNTAX
- Field Value:
- 0
public static final String AUTO_IMPORT_KEY
public static final String AUTO_INCLUDE_KEY
public static final String CACHE_STORAGE_KEY
public static final String DEFAULT_ENCODING_KEY
public static final String LOCALIZED_LOOKUP_KEY
public static final int SQUARE_BRACKET_TAG_SYNTAX
- Field Value:
- 2
public static final String STRICT_SYNTAX_KEY
public static final String TAG_SYNTAX_KEY
public static final String TEMPLATE_UPDATE_DELAY_KEY
public static final String WHITESPACE_STRIPPING_KEY
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 importedtemplate
- the name of the template
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.
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 subsequentgetTemplate
calls. This method is thread-safe and can be called while the engine works.
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 commonConfiguration
instance. Each such component should use its own privateConfiguration
object instead, that it typically creates withnew 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)
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 usingsetEncoding(Locale,String)
orloadBuiltInEncodingMap()
.
- Parameters:
loc
- the locale
- Returns:
- the preferred character encoding for the locale.
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.
- See Also:
setStrictSyntaxMode(boolean)
public int getTagSyntax()
- Returns:
- whether the alternative square bracket syntax is set as the default
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, 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
Retrieves a template specified by a name and locale, interpreted using the specified character encoding, either parsed or unparsed. For the exact semantics of parameters, seeTemplateCache.getTemplate(String,Locale,String,boolean)
.
- Returns:
- the requested template.
public Template getTemplate(String name, String encoding) throws IOException
Equivalent to getTemplate(name, thisCfg.getLocale(), encoding, true).
public TemplateLoader getTemplateLoader()
- Returns:
- the template loader that is used to look up and load templates.
- See Also:
setTemplateLoader(TemplateLoader)
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.
- See Also:
setWhitespaceStripping(boolean)
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:
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:
clearEncodingMap()
,setEncoding(Locale,String)
public void removeAutoImport(String namespace)
Remove an auto-imported template
- Parameters:
namespace
- the name of the namespace into which the template was imported
public void removeAutoInclude(String templateName)
remove a template from the auto-include list.
- Parameters:
templateName
- the lookup name of the template in question.
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.
public 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 void setAutoIncludes(List templateNames)
set the list of automatically included templates. Note that all previous auto-includes are removed.
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 morehere...
.Sets the Configuration object that will be retrieved from future calls togetDefaultConfiguration()
.
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 withsetDefaultEncoding(String)
.
- See Also:
clearEncodingMap()
,loadBuiltInEncodingMap()
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
- Parameters:
sctxt
- the ServletContext object. Note that the type isObject
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 setSetting(String key, String value) throws TemplateException
Sets a setting by name and string value. In additional to the settings understood bythe 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(Map)
"auto_include"
: Sets the list of auto-includes. Example of valid value:/include/common.ftl, "/include/evil name.ftl"
See:setAutoIncludes(List)
"default_encoding"
: The name of the charset, such as"UTF-8"
. See:setDefaultEncoding(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 aMruCacheStorage
will be used with the maximum strong and soft sizes specified with the setting value. Examples of valid setting values:The value is not case sensitive. The order of soft and strong entries is not significant. See also:
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(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"
.
- Overrides:
- setSetting in interface Configurable
- Parameters:
key
- the name of the setting.value
- the string that describes the new value of the setting.
- Throws:
TemplateException
- if the new value of the setting can't be set for any other reasons.
public void setSharedVariable(String name, Object obj) throws TemplateModelException
Adds shared variable to the configuration. It usesConfigurable.getObjectWrapper()
to wrap theobj
.
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.
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)
Determines the syntax of the template files (angle bracket VS square bracket) that has noftl directive in it. ThetagSyntax
parameter must be one of:In FreeMarker 2.3.x
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 syntaxANGLE_BRACKET_TAG_SYNTAX
is the default for better backward compatibility. Starting from 2.4.xAUTO_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 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. Several convenience methods in this class already allow you to install commonly used loaders:setClassForTemplateLoading(Class,String)
,setDirectoryForTemplateLoading(File)
, andsetServletContextForTemplateLoading(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 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.