Cache Chaining - Documentation topics on: cache chaining,cache properties,cache providers,cache settings,configuring the dotcms cache,dotcms 3.3,enterprise only,.

Cache Chaining

In the Enterprise version of dotCMS, you may customize each cache region by adding custom cache providers and chaining multiple cache providers together in a specific order to improve performance. This list of cache providers for each cache region, in order, is called the cache chain for that region. The file contains a list of cache chain properties that specify the cache chains for each region.

Please note:

  • Configuration of cache chains is available only in dotCMS Enterprise licensed editions.
    • In dotCMS Community edition, the cache is automatically configured to only use the Guava memory-only cache (and all cache chain properties in the file are ignored).
  • It is strongly recommended that any time you make changes to the file, you do so only via a configuration plugin.

With cache chaining, you may have multiple cache implementations storing the same cache data. For example, you may configure dotCMS to first check local memory cache, then if the item is not found check the local disk cache, then if the item is still not found check a remote service cache. Each of these cache checks are a link in the chain. You can configure the cache providers in any order.

Please select the appropriate sections below for more information:

Cache Chain Properties

The cache chain for any cache region may be specified by adding a cache chain property for that region. The cache chain properties use the following naming convention:



  • The CACHE-REGION-NAME specifies the name of the cache region.
    • See Cache Region Names, below.
  • The CACHE-PROVIDER-CLASS specifies the full class name of the cache provider.
    • See Adding Cache Providers, below.
  • You may specify 1 or more cache providers, in any order.
  • The order of execution of the cache providers for any region is defined by the order they appear in the chain property for that region.
    • Once a key is found in a cache provider, the value will be returned and no following providers will be checked.

For example, in the initial dotCMS configuration, the chain for the contentletcache region (cache.contentletcache.chain) is defined as follows:,

This specifies that for items in the contentletcache region, dotCMS will first check the Guava cache provider (memory cache) for the item, and if the item is not found there then dotCMS will then check the H2 cache provider (disk cache) for the item.

Cache Region Names

To find a list of the cache regions, open the Cache tab in System -> Maintenance and press the Refresh Stats button.

A list of cache regions will be displayed. If any cache regions are using multiple cache providers, those cache regions will be displayed multiple times (once for each cache provider). For example, if you are using the default cache configuration, the contentletcache region will be displayed twice: once for the memory cache (Cache Provider = “guava memory cache”) and once for disk cache (Cache Provider = “h2 cache provider”).

You may create a separate cache chain property for any cache region displayed in the list of cache regions.

Default Cache Chain

The cache.default.chain property specifies the default cache chain. The default cache chain is used as a template for any cache region which does not have it's own cache chain specified; each cache region without its own cache chain property is kept in a separate cache region, but uses the the default cache chain for its region. The initial dotCMS configuration defines the following default chain:

Uncacheable Data and Content

Some types of data and content can not be written to and retrieved properly from any location except memory, and so should not be stored to any form of cache other than a memory-only cache. The main type of user content with this limitation is Velocity macros; all velocity macro files (files ending in .vm) are automatically cached in the velocitymemoryonlycache region, and the cache.velocitymemoryonlycache.chain property is configured to ensure that the macros are not cached to disk.

Important: Do not add any cache provider to the cache.velocitymemoryonlycache.chain property that writes to any location other than memory. You are free to add different memory-only cache providers (such as the Timed Memory Cache) to improve performance; but if you include a cache provider that writes to disk or another storage medium it may prevent your pages from rendering properly.

If you have existing Velocity files (.vtl) that contain Velocity macros, you may encounter problems rendering your Velocity macros after restarting your server. To prevent this problem, you have two options:

  1. Keep all your velocity macros in Velocity Macro (.vm) files, separate from the rest of your Velocity code (.vtl files), or
  2. Configure your system so that all your Velocity code is cached to memory only.

To implement the first option, simply separate all your Velocity macros into files with .vm extensions (leaving the non-macro Velocity code in your .vtl files). dotCMS will automatically cache all files with a .vm extension in the velocitymemoryonlycache.

To implement the second option, change the default value of the cache.velocitycache.chain property to use memory-only cache providers, as in the example below:

Other Memory-Only Cache Regions

The following cache regions may also only be stored in memory cache. These cache regions may be configured to use Guava cache or Timed Memory, but should not be configured to use H2 cache, Redis, or custom cache providers:

  • cache.xmltoolcache.chain

Selecting Cache Providers

Built-in Cache Providers

The dotCMS distribution includes the following cache providers. Click the links in the table for more information about each cache provider.

CacheCache LocationCache Provider Class Name
Guava cacheMemory
RedisExternal Cache
Timed MemoryMemory

Please also see the Troubleshooting section, below, for information on using the Test Cache Provider](test-cache-provider).

Adding Cache Providers

In addition to the built-in providers, you may also add your own cache providers. To add a new cache provider to dotCMS, do the following:

  1. Add the custom cache provider implementation through a static plugin or an OSGI plugin.
  2. In the new cache provider class, extend and implement the methods defined in the abstract class.
  3. Add the new cache provider class to the cache chain properties of all cache regions that you want to use the new cache provider.

Troubleshooting Cache Chains

You may troubleshoot your cache chain configuration both by disabling cache regions, and by logging information about the use of each cache within your cache chain using the Test Cache Provider.

Disabling Cache Regions

When troubleshooting caching, it may be useful to disable specific cache regions. When you disable a cache region, any attempts to access data in that cache region bypass the cache, retrieving the data directly from the dotCMS content sote.

Important: Disabling cache regions can cause significant performance degradation. Cache regions should only be disabled for troubleshooting purposes, and should not be disabled on production sites unless absolutely necessary.

You may disable any cache region by setting the cache size configuration for that region to 0.


The Test Cache Provider

The Test Cache Provider is a special cache provider which logs messages to the log file whenever it is accessed. To monitor any other cache provider in your cache chain, simply insert the Test Cache Provider into the cache chain before the cache provider you wish to monitor. A message will then be logged every time an item is sent to the monitored cache provider.


  • The Test cache provider does not actually cache any data.
    • The Test cache provider always passes all data through, so all data sent to the Test Cache Provider is automatically passed to the next cache provider in the chain.
  • The Test cache provider reduces cache performance.
    • Since the Test cache provider performs additional logging, cache performance should not be evaluated with the Test cache provider in the cache chain.
    • The Test cache provider should not be used in a production environment.

For more information, please see the Test Cache Provider documentation.