Package freemarker.cache
Class TemplateCache
java.lang.Object
freemarker.cache.TemplateCache
Performs caching and on-demand loading of the templates.
The actual template "file" loading is delegated to a
TemplateLoader that you can specify in the constructor.
Some aspects of caching is delegated to a CacheStorage 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 through Configuration.getTemplate(String) and other
Configuration API-s. Then TemplateLoader and CacheStorage can be set with
Configuration.setTemplateLoader(TemplateLoader) and
Configuration.setCacheStorage(CacheStorage).
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic classUsed for the return value ofgetTemplate(String, Locale, Object, String, boolean). -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic longThe default template update delay; seeConfiguration.setTemplateUpdateDelayMilliseconds(long). -
Constructor Summary
ConstructorsConstructorDescriptionDeprecated.TemplateCache(TemplateLoader templateLoader)Deprecated.TemplateCache(TemplateLoader templateLoader, CacheStorage cacheStorage)Deprecated.TemplateCache(TemplateLoader templateLoader, CacheStorage cacheStorage, TemplateLookupStrategy templateLookupStrategy, TemplateNameFormat templateNameFormat, TemplateConfigurationFactory templateConfigurations, Configuration config)TemplateCache(TemplateLoader templateLoader, CacheStorage cacheStorage, TemplateLookupStrategy templateLookupStrategy, TemplateNameFormat templateNameFormat, Configuration config)Same asTemplateCache(TemplateLoader, CacheStorage, TemplateLookupStrategy, TemplateNameFormat, TemplateConfigurationFactory, Configuration)withnullfortemplateConfigurations-s.TemplateCache(TemplateLoader templateLoader, CacheStorage cacheStorage, Configuration config)TemplateCache(TemplateLoader templateLoader, Configuration config)Same asTemplateCache(TemplateLoader, CacheStorage, Configuration)with a newSoftCacheStorageas the 2nd parameter. -
Method Summary
Modifier and TypeMethodDescriptionvoidclear()Removes all entries from the cache, forcing reloading of templates on subsequentgetTemplate(String, Locale, String, boolean)calls.protected static TemplateLoaderDeprecated.TheTemplateLoadershould be always specified by the constructor caller.longgetDelay()Gets the delay in milliseconds between checking for newer versions of a template source.static StringgetFullTemplatePath(Environment env, String baseName, String targetName)Deprecated.UseEnvironment.toFullTemplateName(String, String)instead, as that can throwMalformedTemplateNameException, and is on a more logical place anyway.booleanReturns if localized template lookup is enabled or not.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.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.voidremoveTemplate(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.voidremoveTemplate(String name, Locale locale, String encoding, boolean parse)voidsetConfiguration(Configuration config)Deprecated.Use theTemplateCache(TemplateLoader, CacheStorage, Configuration)constructor.voidsetDelay(long delay)Sets the delay in milliseconds between checking for newer versions of a template sources.voidsetLocalizedLookup(boolean localizedLookup)Setis if localized template lookup is enabled or not.
-
Field Details
-
DEFAULT_TEMPLATE_UPDATE_DELAY_MILLIS
public static final long DEFAULT_TEMPLATE_UPDATE_DELAY_MILLISThe default template update delay; seeConfiguration.setTemplateUpdateDelayMilliseconds(long).- Since:
- 2.3.23
- See Also:
- Constant Field Values
-
-
Constructor Details
-
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
Deprecated. -
TemplateCache
Deprecated. -
TemplateCache
Same asTemplateCache(TemplateLoader, CacheStorage, Configuration)with a newSoftCacheStorageas 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_0andTemplateNameFormat.DEFAULT_2_3_0.- Since:
- 2.3.21
-
TemplateCache
public TemplateCache(TemplateLoader templateLoader, CacheStorage cacheStorage, TemplateLookupStrategy templateLookupStrategy, TemplateNameFormat templateNameFormat, Configuration config)Same asTemplateCache(TemplateLoader, CacheStorage, TemplateLookupStrategy, TemplateNameFormat, TemplateConfigurationFactory, Configuration)withnullfortemplateConfigurations-s.- Since:
- 2.3.22
-
TemplateCache
public TemplateCache(TemplateLoader templateLoader, CacheStorage cacheStorage, TemplateLookupStrategy templateLookupStrategy, TemplateNameFormat templateNameFormat, TemplateConfigurationFactory templateConfigurations, Configuration config)- Parameters:
templateLoader- TheTemplateLoaderto use. Can benull, though then every request will result inTemplateNotFoundException.cacheStorage- TheCacheStorageto use. Can't benull.templateLookupStrategy- TheTemplateLookupStrategyto use. Can't benull.templateNameFormat- TheTemplateNameFormatto use. Can't benull.templateConfigurations- TheTemplateConfigurationFactoryto use. Can benull(then all templates will use the settings coming from theConfigurationas is).config- TheConfigurationthis cache will be used for. Can benullfor backward compatibility, as it can be set withsetConfiguration(Configuration)later.- Since:
- 2.3.24
-
-
Method Details
-
setConfiguration
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
-
getCacheStorage
-
getTemplateLookupStrategy
- Since:
- 2.3.22
-
getTemplateNameFormat
- Since:
- 2.3.22
-
getTemplateConfigurations
- Since:
- 2.3.24
-
getTemplate
public TemplateCache.MaybeMissingTemplate getTemplate(String name, Locale locale, Object customLookupCondition, String encoding, boolean parseAsFTL) throws IOExceptionRetrieves 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.MaybeMissingTemplateobject that contains theTemplate, or aTemplateCache.MaybeMissingTemplateobject that containsnullas theTemplateand 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 thenamewas malformed according the currentTemplateNameFormat. However, if theTemplateNameFormatisTemplateNameFormat.DEFAULT_2_3_0andConfiguration.getIncompatibleImprovements()is less than 2.4.0, then instead of throwing this exception, aTemplateCache.MaybeMissingTemplatewill 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
@Deprecated public Template getTemplate(String name, Locale locale, String encoding, boolean parseAsFTL) throws IOExceptionDeprecated.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
Deprecated.TheTemplateLoadershould 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 IOExceptionRemoves 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, seeConfiguration.getTemplate(String, Locale, Object, String, boolean, boolean)- Throws:
IOException
-
getFullTemplatePath
@Deprecated 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 thebaseNameortargetNameis malformed according theTemplateNameFormatin use.
-
TemplateCache(TemplateLoader)instead.