TemplateCache (FreeMarker 2.3.23 API)
Date: 2015-07-05

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
    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)`
    `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
    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 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.
    `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 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

          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

          public TemplateCache(TemplateLoader templateLoader)

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

    - #### TemplateCache

          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)

      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`.
        `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.22

  - ### Method Detail

    - #### setConfiguration

          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

    - #### 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

          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

          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

      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 `getTemplate(TemplateLoader, String, Locale, Object, String, boolean)`.
      Throws:
        `IOException`

    - #### getFullTemplatePath

          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.