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 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
`static class` `TemplateCache.MaybeMissingTemplate` Used for the return value of `getTemplate(String, Locale, Object, String, boolean)`.

### Field Summary

Fields
`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

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
`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 String` `getFullTemplatePath(Environment env, String baseName, 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(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. 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(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)` 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't be `null`.
  `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(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`, 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).
  `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(String name,
                                             Locale locale,
                                             String encoding,
                                             boolean parseAsFTL)
                                      throws 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:
  `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(String name,
                               Locale locale,
                               String encoding,
                               boolean parse)
                        throws IOException

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

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 than `setDelay(long)` alone does. For the meaning of the parameters, see `Configuration.getTemplate(String, Locale, Object, String, boolean, boolean)`

Throws:
  `IOException`

#### getFullTemplatePath

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

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

Throws:
  `IllegalArgumentException` - If the `baseName` or `targetName` is malformed according the `TemplateNameFormat` in use.