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
- Uncacheable Data and Content
- 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:
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:
- Keep all your velocity macros in Velocity Macro (.vm) files, separate from the rest of your Velocity code (.vtl files), or
- 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 Caffeine cache, Guava cache, or Timed Memory, Hazelcast cache (embedded cache), but should NOT be configured to use H2 cache, Redis, Hazelcast cache (client cache), 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.
|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.