Fork me on GitHub
Oak logo
Built by Maven

Persistent Cache

The document storage optionally uses the persistent cache. The cache acts like an in-memory cache for old revisions, but in addition to keeping the most recently used nodes in memory, it also stores them to disk. That way, many reads from the storage backend (for example MongoDB) are replaced by reads from the local disk. This is specially useful if reads from the local disk are faster than reads from the storage backend. In addition to that, the persistent cache reduces the load on the storage backend.

### OSGi Configuration

The default OSGi configuration of the persistent cache is:

org.apache.jackrabbit.oak.plugins.document.DocumentNodeStoreService
    persistentCache="cache"

Oak version up to 1.4 have the persistent cache disabled by default, which is equivalent with a configuration entry set to an empty String. Starting with Oak 1.6, the persistent cache is enabled by default and can be disabled by setting the configuration entry to "-".

Configuration Options

The persistent cache configuration setting is string with a number of comma separated elements. The first element is the directory where the cache is stored. Example:

"cache"

In this case, the data is stored in the directory “cache”, relative to the repository.home directory. If no repository home directory is configured, the directory is relative to the current working directory. Oak versions prior to 1.6 always resolve to the current working directory and ignore the repository.home configuration. By default, there are at most two files (two generations) with the name “cache-x.data”, where x is an incrementing number (0, 1,…). A file is at most 1 GB by default. If the file is larger, the next file is created, and if there are more than two files, the oldest one is removed. If data from the older file is accessed, it is copied to the latest file. That way, data that is not recently read will eventually be removed.

The following other configuration options are available:

  • Size. A file is at most 1 GB by default. To change maximum size of a file, use “size=x”, where x is the size in MB.

  • Node caching. By default, nodes at all revisions are cached. To disable this option, use “-nodes”.

  • Children caching. By default, the list of children of a node is cached. To disable this option, use “-children”.

  • Diff caching. By default, the list of differences between two revisions is cached. To disable this option, use “-diff”.

  • Compaction. The cache file can be compacted and compressed (at a rate of around 100 MB per second) when it is closed. That way, the disk space is used more efficiently. To enable this option, use “+compact”. (Please note this feature was enabled by default in versions 1.2.1, 1.0.13, and older.)

  • Compression. By default, the cache is compressed, saving space. To disable this option, use “-compress”.

  • Binary caching (removed in Oak 1.10). When using the BlobStore, binaries smaller than 1 MB are stored in the persistent cache by default. The maximum size can be changed using the setting “binary=x”, where x is the size in bytes. To disable the binary cache, use “binary=0”.

Those setting can be appended to the persistent cache configuration string. An example configuration is:

"cache,size\=2048,-compact,-compress"

To disable the persistent cache entirely in Oak 1.6 and newer, use the following configuration:

org.apache.jackrabbit.oak.plugins.document.DocumentNodeStoreService
    persistentCache="-"

Up to Oak version 1.4, either omit the persistentCache entry or set it to an empty String to disable the persistent cache.

Journal cache

Since Oak 1.6.

Diff cache entries can also are stored in a separate persistent cache and configured independently if needed. This can be done in the OSGi configuration like in the following example:

org.apache.jackrabbit.oak.plugins.document.DocumentNodeStoreService
    persistentCache="cache,size\=2048"
    journalCache="diff-cache,size\=1024"

The configuration options are the same as for the persistentCache, but options unrelated to the diff cache type are ignored. The default configuration is journalCache="diff-cache" and can be disabled the same way as the regular persistent cache with a dash: journalCache="-".

Cache statistics

The persistent cache expose access statistics as CacheStatsMBean or via ConsolidatedCacheStatsMBean. Some of the fields exposed by the persistent caches do not have meaningful values. These are: totalLoadTime, averageLoadPenalty, evictionCount, elementCount and maxTotalWeight.

### Dependencies

Internally, the persistent cache uses a key-value store (basically a java.util.Map), which is persisted to disk. The current key-value store backend is the H2 MVStore. This library is only needed if the persistent cache is configured. Version 1.4.185 or newer is needed.

<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2-mvstore</artifactId>
    <version>1.4.185</version>
</dependency>