freemarker.cache

Class TemplateCache

java.lang.Object

freemarker.cache.TemplateCache

public class TemplateCache
extends java.lang.Object

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 Classes

Modifier and Type	Class and Description
static class	TemplateCache.MaybeMissingTemplate Used for the return value of getTemplate(String, Locale, Object, String, boolean).

Field Summary

Fields

Modifier and Type	Field and Description
static long	DEFAULT_TEMPLATE_UPDATE_DELAY_MILLIS The default template update delay; see Configuration.setTemplateUpdateDelayMilliseconds(long).

Constructor Summary

Constructors

Constructor and Description
TemplateCache() Deprecated. Use TemplateCache(TemplateLoader) instead. The default loader is useless in most applications, also it can mean a security risk.
TemplateCache(TemplateLoader templateLoader) Deprecated. Use TemplateCache(TemplateLoader, CacheStorage, Configuration) instead.
TemplateCache(TemplateLoader templateLoader, CacheStorage cacheStorage) Deprecated. Use TemplateCache(TemplateLoader, CacheStorage, Configuration) instead.
TemplateCache(TemplateLoader templateLoader, CacheStorage cacheStorage, Configuration config) Same as TemplateCache(TemplateLoader, CacheStorage, TemplateLookupStrategy, TemplateNameFormat, Configuration) with TemplateLookupStrategy.DEFAULT_2_3_0 and TemplateNameFormat.DEFAULT_2_3_0.
TemplateCache(TemplateLoader templateLoader, CacheStorage cacheStorage, TemplateLookupStrategy templateLookupStrategy, TemplateNameFormat templateNameFormat, Configuration config) Same as TemplateCache(TemplateLoader, CacheStorage, TemplateLookupStrategy, TemplateNameFormat, TemplateConfigurationFactory, Configuration) with null for templateConfigurations-s.
TemplateCache(TemplateLoader templateLoader, CacheStorage cacheStorage, TemplateLookupStrategy templateLookupStrategy, TemplateNameFormat templateNameFormat, TemplateConfigurationFactory templateConfigurations, Configuration config)
TemplateCache(TemplateLoader templateLoader, Configuration config) Same as TemplateCache(TemplateLoader, CacheStorage, Configuration) with a new SoftCacheStorage as the 2nd parameter.

Method Summary

Modifier and Type	Method and Description
void	clear() Removes all entries from the cache, forcing reloading of templates on subsequent getTemplate(String, Locale, String, boolean) calls.
protected static TemplateLoader	createLegacyDefaultTemplateLoader() Deprecated. The TemplateLoader 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 java.lang.String	getFullTemplatePath(Environment env, java.lang.String baseName, java.lang.String targetName) Deprecated. Use Environment.toFullTemplateName(String, String) instead, as that can throw MalformedTemplateNameException, and is on a more logical place anyway.
boolean	getLocalizedLookup() Returns if localized template lookup is enabled or not.
TemplateCache.MaybeMissingTemplate	getTemplate(java.lang.String name, java.util.Locale locale, java.lang.Object customLookupCondition, java.lang.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(java.lang.String name, java.util.Locale locale, java.lang.String encoding, boolean parseAsFTL) Deprecated. Use getTemplate(String, Locale, Object, String, boolean), which can return more detailed result when the template is missing.
TemplateConfigurationFactory	getTemplateConfigurations()
TemplateLoader	getTemplateLoader()
TemplateLookupStrategy	getTemplateLookupStrategy()
TemplateNameFormat	getTemplateNameFormat()
void	removeTemplate(java.lang.String name, java.util.Locale locale, java.lang.Object customLookupCondition, java.lang.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(java.lang.String name, java.util.Locale locale, java.lang.String encoding, boolean parse) Same as removeTemplate(String, Locale, Object, String, boolean) with null customLookupCondition.
void	setConfiguration(Configuration config) Deprecated. Use the TemplateCache(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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_TEMPLATE_UPDATE_DELAY_MILLIS

public static final long DEFAULT_TEMPLATE_UPDATE_DELAY_MILLIS

The default template update delay; see Configuration.setTemplateUpdateDelayMilliseconds(long).

Since:

2.3.23

See Also:

Constant Field Values

Constructor Detail

TemplateCache

@Deprecated
public TemplateCache()

Deprecated. Use TemplateCache(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 property user.dir), then from the classpath.

TemplateCache

@Deprecated
public TemplateCache(TemplateLoader templateLoader)

Deprecated. Use TemplateCache(TemplateLoader, CacheStorage, Configuration) instead.

TemplateCache

@Deprecated
public TemplateCache(TemplateLoader templateLoader,
                                  CacheStorage cacheStorage)

Deprecated. Use TemplateCache(TemplateLoader, CacheStorage, Configuration) instead.

TemplateCache

public TemplateCache(TemplateLoader templateLoader,
                     Configuration config)

Same as TemplateCache(TemplateLoader, CacheStorage, Configuration) with a new SoftCacheStorage as the 2nd parameter.

Since:

2.3.21

TemplateCache

public TemplateCache(TemplateLoader templateLoader,
                     CacheStorage cacheStorage,
                     Configuration config)

Same as TemplateCache(TemplateLoader, CacheStorage, TemplateLookupStrategy, TemplateNameFormat, Configuration) with TemplateLookupStrategy.DEFAULT_2_3_0 and TemplateNameFormat.DEFAULT_2_3_0.

Since:

2.3.21

TemplateCache

public TemplateCache(TemplateLoader templateLoader,
                     CacheStorage cacheStorage,
                     TemplateLookupStrategy templateLookupStrategy,
                     TemplateNameFormat templateNameFormat,
                     Configuration config)

Same as TemplateCache(TemplateLoader, CacheStorage, TemplateLookupStrategy, TemplateNameFormat, TemplateConfigurationFactory, Configuration) with null for templateConfigurations-s.

Since:

2.3.22

TemplateCache

public TemplateCache(TemplateLoader templateLoader,
                     CacheStorage cacheStorage,
                     TemplateLookupStrategy templateLookupStrategy,
                     TemplateNameFormat templateNameFormat,
                     TemplateConfigurationFactory templateConfigurations,
                     Configuration config)

Parameters:

templateLoader - The TemplateLoader to use. Can be null, though then every request will result in TemplateNotFoundException.

cacheStorage - The CacheStorage to use. Can't be null.

templateLookupStrategy - The TemplateLookupStrategy to use. Can't be null.

templateNameFormat - The TemplateNameFormat to use. Can't be null.

templateConfigurations - The TemplateConfigurationFactory to use. Can be null (then all templates will use the settings coming from the Configuration as is).

config - The Configuration this cache will be used for. Can be null for backward compatibility, as it can be set with setConfiguration(Configuration) later.

Since:

2.3.24

Method Detail

setConfiguration

@Deprecated
public void setConfiguration(Configuration config)

Deprecated. Use the TemplateCache(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

getTemplateConfigurations

public TemplateConfigurationFactory getTemplateConfigurations()

Since:

2.3.24

getTemplate

public TemplateCache.MaybeMissingTemplate getTemplate(java.lang.String name,
                                                      java.util.Locale locale,
                                                      java.lang.Object customLookupCondition,
                                                      java.lang.String encoding,
                                                      boolean parseAsFTL)
                                               throws java.io.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, except customLookupCondition. For the meaning of the parameters see Configuration.getTemplate(String, Locale, String, boolean).

Returns:

A TemplateCache.MaybeMissingTemplate object that contains the Template, or a TemplateCache.MaybeMissingTemplate object that contains null as the Template and information about the missing template. The return value itself is never null. 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 a TemplateCache.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 the name was malformed according the current TemplateNameFormat. However, if the TemplateNameFormat is TemplateNameFormat.DEFAULT_2_3_0 and Configuration.getIncompatibleImprovements() is less than 2.4.0, then instead of throwing this exception, a TemplateCache.MaybeMissingTemplate will be returned, similarly as if the template were missing (the TemplateCache.MaybeMissingTemplate.getMissingTemplateReason() will describe the real error).

java.io.IOException - If reading the template has failed from a reason other than the template is missing. This method should never be a TemplateNotFoundException, as that condition is indicated in the return value.

Since:

2.3.22

getTemplate

@Deprecated
public Template getTemplate(java.lang.String name,
                                         java.util.Locale locale,
                                         java.lang.String encoding,
                                         boolean parseAsFTL)
                                  throws java.io.IOException

Deprecated. Use getTemplate(String, Locale, Object, String, boolean), which can return more detailed result when the template is missing.

Similar to getTemplate(String, Locale, Object, String, boolean) with null customLookupCondition.

Returns:

TemplateCache.MaybeMissingTemplate.getTemplate() of the getTemplate(String, Locale, Object, String, boolean) return value.

Throws:

java.io.IOException

createLegacyDefaultTemplateLoader

@Deprecated
protected static TemplateLoader createLegacyDefaultTemplateLoader()

Deprecated. The TemplateLoader 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 subsequent getTemplate(String, Locale, String, boolean) calls. If the configured template loader is stateful, then its StatefulTemplateLoader.resetState() method is invoked as well.

removeTemplate

public void removeTemplate(java.lang.String name,
                           java.util.Locale locale,
                           java.lang.String encoding,
                           boolean parse)
                    throws java.io.IOException

Same as removeTemplate(String, Locale, Object, String, boolean) with null customLookupCondition.

Throws:

java.io.IOException

removeTemplate

public void removeTemplate(java.lang.String name,
                           java.util.Locale locale,
                           java.lang.Object customLookupCondition,
                           java.lang.String encoding,
                           boolean parse)
                    throws java.io.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 than setDelay(long) alone does. For the meaning of the parameters, see Configuration.getTemplate(String, Locale, Object, String, boolean, boolean)

Throws:

java.io.IOException

getFullTemplatePath

@Deprecated
public static java.lang.String getFullTemplatePath(Environment env,
                                                                java.lang.String baseName,
                                                                java.lang.String targetName)

Deprecated. Use Environment.toFullTemplateName(String, String) instead, as that can throw MalformedTemplateNameException, and is on a more logical place anyway.

Throws:

java.lang.IllegalArgumentException - If the baseName or targetName is malformed according the TemplateNameFormat in use.