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. dotCMS configuration properties contain 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 Caffine memory-only cache (and all cache chain properties in the config properties are ignored).
• CaffineCache is misspelt - this was not intentional but it is important when referencing the this cache provider to specify the misspelt com.dotmarketing.business.cache.provider.caffine.CaffineCache. If you “fix” the spelling, it will not work.

With cache chaining, you may have multiple cache implementations storing the same cache data. Order matters and you want your chain to try the fastest caches first and then fall back to slower caches. 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 redis cache. Each of these cache checks are a link in the chain.

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:

cache.CACHE-REGION-NAME.chain=CACHE-PROVIDER-CLASS-1,CACHE-PROVIDER-CLASS-2, ...

Where:

• 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:

cache.contentletcache.chain=com.dotmarketing.business.cache.provider.caffine.CaffineCache,com.dotmarketing.business.cache.provider.h22.H22Cache

This specifies that for items in the contentletcache region, dotCMS will first check the Caffine cache provider (memory cache) for the item, and if the item is not found there then dotCMS will then check the H22 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 = “caffine memory cache”) and once for disk cache (Cache Provider = “h22 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:

cache.default.chain=com.dotmarketing.business.cache.provider.caffine.CaffineCache

Memory-Only Cache Regions

The following cache regions may only be stored in memory cache. These cache regions may be configured to use Caffine cache, or Timed Memory, but should NOT be configured to use H2 cache, Redis, or custom cache providers (unless the custom cache provider implements a memory-only cache):

• cache.xmltoolcache.chain

Persistent Caching of Velocity Resources

Velocity is handled by the cache region Velocity2, which includes raw code and macros, all of which are cleared and reconstituted on flush. Additionally, when any file that matches the pattern dot_velocity_macros.* is modified, this also flushes and refreshes the cache.

You may cache this region to either memory-only cache or persistent cache (including disk cache, Redis, or custom cache providers).

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.

Please also see the Troubleshooting section, below, for information on using the 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, 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 com.dotmarketing.business.cache.provider.CacheProvider 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.

cache.fileassetmetadatacache.size=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.

Important:

• 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.