Package freemarker.cache
Class TemplateCache
- java.lang.Object
-
- freemarker.cache.TemplateCache
-
public class TemplateCache extends Object
Performs caching and on-demand loading of the templates. The actual template "file" loading is delegated to aTemplateLoader
that you can specify in the constructor. Some aspects of caching is delegated to aCacheStorage
that you can also specify in the constructor.Typically you don't instantiate or otherwise use this class directly. The
Configuration
embeds an instance of this class, that you access indirectly throughConfiguration.getTemplate(String)
and otherConfiguration
API-s. ThenTemplateLoader
andCacheStorage
can be set withConfiguration.setTemplateLoader(TemplateLoader)
andConfiguration.setCacheStorage(CacheStorage)
.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
TemplateCache.MaybeMissingTemplate
Used for the return value ofgetTemplate(String, Locale, Object, String, boolean)
.
-
Field Summary
Fields Modifier and Type Field Description static long
DEFAULT_TEMPLATE_UPDATE_DELAY_MILLIS
The default template update delay; seeConfiguration.setTemplateUpdateDelayMilliseconds(long)
.
-
Constructor Summary
Constructors Constructor Description TemplateCache()
Deprecated.UseTemplateCache(TemplateLoader)
instead.TemplateCache(TemplateLoader templateLoader)
Deprecated.TemplateCache(TemplateLoader templateLoader, CacheStorage cacheStorage)
Deprecated.TemplateCache(TemplateLoader templateLoader, CacheStorage cacheStorage, TemplateLookupStrategy templateLookupStrategy, TemplateNameFormat templateNameFormat, Configuration config)
TemplateCache(TemplateLoader templateLoader, CacheStorage cacheStorage, Configuration config)
TemplateCache(TemplateLoader templateLoader, Configuration config)
Same asTemplateCache(TemplateLoader, CacheStorage, Configuration)
with a newSoftCacheStorage
as the 2nd parameter.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
clear()
Removes all entries from the cache, forcing reloading of templates on subsequentgetTemplate(String, Locale, String, boolean)
calls.protected static TemplateLoader
createLegacyDefaultTemplateLoader()
Deprecated.TheTemplateLoader
should be always specified by the constructor caller.CacheStorage
getCacheStorage()
long
getDelay()
Gets the delay in milliseconds between checking for newer versions of a template source.static String
getFullTemplatePath(Environment env, String baseName, String targetName)
Deprecated.UseEnvironment.toFullTemplateName(String, String)
instead, as that can throwMalformedTemplateNameException
, and is on a more logical place anyway.boolean
getLocalizedLookup()
Returns if localized template lookup is enabled or not.TemplateCache.MaybeMissingTemplate
getTemplate(String name, Locale locale, Object customLookupCondition, String encoding, boolean parseAsFTL)
Retrieves the template with the given name (and according the specified further parameters) from the template cache, loading it into the cache first if it's missing/staled.Template
getTemplate(String name, Locale locale, String encoding, boolean parseAsFTL)
Deprecated.UsegetTemplate(String, Locale, Object, String, boolean)
, which can return more detailed result when the template is missing.TemplateLoader
getTemplateLoader()
TemplateLookupStrategy
getTemplateLookupStrategy()
TemplateNameFormat
getTemplateNameFormat()
void
removeTemplate(String name, Locale locale, Object customLookupCondition, String encoding, boolean parse)
Removes an entry from the cache, hence forcing the re-loading of it when it's next time requested.void
removeTemplate(String name, Locale locale, String encoding, boolean parse)
void
setConfiguration(Configuration config)
Deprecated.Use theTemplateCache(TemplateLoader, CacheStorage, Configuration)
constructor.void
setDelay(long delay)
Sets the delay in milliseconds between checking for newer versions of a template sources.void
setLocalizedLookup(boolean localizedLookup)
Setis if localized template lookup is enabled or not.
-
-
-
Field Detail
-
DEFAULT_TEMPLATE_UPDATE_DELAY_MILLIS
public static final long DEFAULT_TEMPLATE_UPDATE_DELAY_MILLIS
The default template update delay; seeConfiguration.setTemplateUpdateDelayMilliseconds(long)
.- Since:
- 2.3.23
- See Also:
- Constant Field Values
-
-
Constructor Detail
-
TemplateCache
public TemplateCache()
Deprecated.UseTemplateCache(TemplateLoader)
instead. The default loader is useless in most applications, also it can mean a security risk.Returns a template cache that will first try to load a template from the file system relative to the current user directory (i.e. the value of the system propertyuser.dir
), then from the classpath.
-
TemplateCache
public TemplateCache(TemplateLoader templateLoader)
Deprecated.
-
TemplateCache
public TemplateCache(TemplateLoader templateLoader, CacheStorage cacheStorage)
Deprecated.
-
TemplateCache
public TemplateCache(TemplateLoader templateLoader, Configuration config)
Same asTemplateCache(TemplateLoader, CacheStorage, Configuration)
with a newSoftCacheStorage
as the 2nd parameter.- Since:
- 2.3.21
-
TemplateCache
public TemplateCache(TemplateLoader templateLoader, CacheStorage cacheStorage, Configuration config)
Same asTemplateCache(TemplateLoader, CacheStorage, TemplateLookupStrategy, TemplateNameFormat, Configuration)
withTemplateLookupStrategy.DEFAULT_2_3_0
andTemplateNameFormat.DEFAULT_2_3_0
.- Since:
- 2.3.21
-
TemplateCache
public TemplateCache(TemplateLoader templateLoader, CacheStorage cacheStorage, TemplateLookupStrategy templateLookupStrategy, TemplateNameFormat templateNameFormat, Configuration config)
- Parameters:
templateLoader
- TheTemplateLoader
to use. Can't benull
.cacheStorage
- TheCacheStorage
to use. Can't benull
.templateLookupStrategy
- TheTemplateLookupStrategy
to use. Can't benull
.config
- TheConfiguration
this cache will be used for. Can benull
for backward compatibility, as it can be set withsetConfiguration(Configuration)
later.- Since:
- 2.3.22
-
-
Method Detail
-
setConfiguration
public void setConfiguration(Configuration config)
Deprecated.Use theTemplateCache(TemplateLoader, CacheStorage, Configuration)
constructor.Sets the configuration object to which this cache belongs. This method is called by the configuration itself to establish the relation, and should not be called by users.
-
getTemplateLoader
public TemplateLoader getTemplateLoader()
-
getCacheStorage
public CacheStorage getCacheStorage()
-
getTemplateLookupStrategy
public TemplateLookupStrategy getTemplateLookupStrategy()
- Since:
- 2.3.22
-
getTemplateNameFormat
public TemplateNameFormat getTemplateNameFormat()
- Since:
- 2.3.22
-
getTemplate
public TemplateCache.MaybeMissingTemplate getTemplate(String name, Locale locale, Object customLookupCondition, String encoding, boolean parseAsFTL) throws IOException
Retrieves the template with the given name (and according the specified further parameters) from the template cache, loading it into the cache first if it's missing/staled.All parameters must be non-
null
, exceptcustomLookupCondition
. For the meaning of the parameters seeConfiguration.getTemplate(String, Locale, String, boolean)
.- Returns:
- A
TemplateCache.MaybeMissingTemplate
object that contains theTemplate
, or aTemplateCache.MaybeMissingTemplate
object that containsnull
as theTemplate
and information about the missing template. The return value itself is nevernull
. Note that exceptions occurring during template loading will not be classified as a missing template, so they will cause an exception to be thrown by this method instead of returning aTemplateCache.MaybeMissingTemplate
. The idea is that having a missing template is normal (not exceptional), providing that the backing storage mechanism could indeed check that it's missing. - Throws:
MalformedTemplateNameException
- If thename
was malformed according the currentTemplateNameFormat
. However, if theTemplateNameFormat
isTemplateNameFormat.DEFAULT_2_3_0
andConfiguration.getIncompatibleImprovements()
is less than 2.4.0, then instead of throwing this exception, aTemplateCache.MaybeMissingTemplate
will be returned, similarly as if the template were missing (theTemplateCache.MaybeMissingTemplate.getMissingTemplateReason()
will describe the real error).IOException
- If reading the template has failed from a reason other than the template is missing. This method should never be aTemplateNotFoundException
, as that condition is indicated in the return value.- Since:
- 2.3.22
-
getTemplate
public Template getTemplate(String name, Locale locale, String encoding, boolean parseAsFTL) throws IOException
Deprecated.UsegetTemplate(String, Locale, Object, String, boolean)
, which can return more detailed result when the template is missing.- Returns:
TemplateCache.MaybeMissingTemplate.getTemplate()
of thegetTemplate(String, Locale, Object, String, boolean)
return value.- Throws:
IOException
-
createLegacyDefaultTemplateLoader
protected static TemplateLoader createLegacyDefaultTemplateLoader()
Deprecated.TheTemplateLoader
should be always specified by the constructor caller.Returns the deprecated default template loader of FreeMarker 2.3.0.
-
getDelay
public long getDelay()
Gets the delay in milliseconds between checking for newer versions of a template source.- Returns:
- the current value of the delay
-
setDelay
public void setDelay(long delay)
Sets the delay in milliseconds between checking for newer versions of a template sources.- Parameters:
delay
- the new value of the delay
-
getLocalizedLookup
public boolean getLocalizedLookup()
Returns if localized template lookup is enabled or not.
-
setLocalizedLookup
public void setLocalizedLookup(boolean localizedLookup)
Setis if localized template lookup is enabled or not.
-
clear
public void clear()
Removes all entries from the cache, forcing reloading of templates on subsequentgetTemplate(String, Locale, String, boolean)
calls. If the configured template loader isstateful
, then itsStatefulTemplateLoader.resetState()
method is invoked as well.
-
removeTemplate
public void removeTemplate(String name, Locale locale, String encoding, boolean parse) throws IOException
- Throws:
IOException
-
removeTemplate
public void removeTemplate(String name, Locale locale, Object customLookupCondition, String encoding, boolean parse) throws IOException
Removes an entry from the cache, hence forcing the re-loading of it when it's next time requested. (It doesn't delete the template file itself.) This is to give the application finer control over cache updating thansetDelay(long)
alone does. For the meaning of the parameters, seegetTemplate(TemplateLoader, String, Locale, Object, String, boolean)
.- Throws:
IOException
-
getFullTemplatePath
public static String getFullTemplatePath(Environment env, String baseName, String targetName)
Deprecated.UseEnvironment.toFullTemplateName(String, String)
instead, as that can throwMalformedTemplateNameException
, and is on a more logical place anyway.- Throws:
IllegalArgumentException
- If thebaseName
ortargetName
is malformed according theTemplateNameFormat
in use.
-
-