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 dotmarketing-config.properties file contains a list of cache chain properties that specify the cache chains for each region.
- 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 Caffeine memory-only cache (and all cache chain properties in the dotmarketing-config.properties file are ignored).
- It is strongly recommended that all changes to the dotmarketing-config.properties file be made through a properties file extension.
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.
- Cache Chain Properties
- Memory-Only Cache Regions
- Selecting Cache Providers
- Troubleshooting Cache Chains
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 Caffeine 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 = “caffeine 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
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:
Memory-Only Cache Regions
The following cache regions may only be stored in memory cache. These cache regions may be configured to use Caffeine cache, Guava cache, Timed Memory, Hazelcast cache (embedded cache), but should NOT be configured to use H2 cache, Redis, Hazelcast cache (client cache), or custom cache providers (unless the custom cache provider implements a memory-only cache):
Important: Persistent Caching of Velocity Cache Regions
There are two cache regions used for Velocity code:
You may cache both velocity cache regions to either memory-only cache or persistent cache (including disk cache, hazelcast, or Redis, or custom cache providers). However it is important that when you cache the
velocitycache region to a persistent cache you must also cache the
velocitymacrocache to the same persistent cache.
If you add a persistent cache to the cache chain for the
velocitycache region but you do not add the same persistent cache to the cache chain for the
velocitymacrocache region, your velocity macros may not be maintained when you restart your system, and after a restart you may need to manually flush your cache before your Velocity macros will work properly.
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.
|Cache||Cache Location||Cache Provider Class Name|
|Caffeine cache||Memory Only|
|Guava cache||Memory Only|
|Hazelcast (embedded) cache||Memory Only|
|Hazelcast (client) cache||External Cache Service|
|Redis cache||External Cache Service|
|Timed Memory||Memory Only|
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, do the following:
- Add the custom cache provider implementation through a static plugin or an OSGI plugin.
- In the new cache provider class, extend and implement the methods defined in the com.dotmarketing.business.cache.provider.CacheProvider abstract class.
- 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
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.