Ehcache 3 module

Magnolia uses Ehcache 3 for its back-end cache functionality by default. Ehcache is a robust, proven and full-featured cache product which has made it the most widely-used Java cache.

Compared with Ehcache 2, the 3.x line brings important changes and improvements such as full compatibility with javax.cache API (JSR-107), off-heap storage capabilities, a revamped API, persistence, improved performance over Ehcache 2.x and much more.

Installing

<dependency>
  <groupId>info.magnolia.cache</groupId>
  <artifactId>magnolia-cache-ehcache3</artifactId>
</dependency>

Ehcache storage tiers

An Ehcache 3 cache can be organized into storage tiers by storage type:

• Heap storage
• Off heap storage
• Disk storage

Each storage tier can specify how much can be stored in each tier. Ehcache will select the appropriate tier to store a cache entry depending on how frequently it used and Ehcache manages storing cache entries among the storage tiers but you define the storage tiers of your cache in Magnolia. Which storage tiers you use and their sizes will affect the performance of the cache.

Each of the storage types have advantages and disadvantages, and when used in combination can provide a performance-optimized, robust cache.

Heap storage

Cache entries are stored as individual objects in memory on the JVM heap. Entry values are not serialized or deserialized when being stored or retrieved from the cache, so heap storage is the fastest of the Ehcache storage tiers.

On the other hand, heap storage can be slowed down by JVM garbage collection and the amount of entries that can be stored in the heap storage is limited by the overall amount of heap available in the JVM.

Heap storage can be bounded by number of items stored or by an overall size. However, there is a cost associated calculating the size of the cache contents when limiting the heap storage tier by number of entries.

Off heap storage

Off heap storage stores the cache entries in blocks of memory on the JVM heap. Unlike heap storage cache values are serialized to the memory block when stored in the cache and deserialized from the memory block when retrieved. 

The serialization and deserialization add a certain overhead; so off-heap storage is slower than heap storage. Off-heap storage can be limited by an overall size but not by number of entries.

Disk storage

Cache entries are stored as files. Cache values are serialized to the file when stored and deserialized when retrieved. Of the three storage tiers, disk storage is the slowest, though how fast disk storage is will depend on the speed and how dedicated the disk is.

Storage tiers and caches

You can configure your cache to have one or more storage tiers. Ehcache will manage the cache entries, moving "hot" (frequently used) entries to faster storage tiers and "cold" (less frequently used) entries to slower storage tiers.

The following combinations of storage tiers for a cache are possible:

• heap only (single tier)
• off heap only (single tier)
• disk only (single tier)
• heap + off-heap (2 tiers)
• heap + disk (2 tiers)
• heap + off-heap + disk (3 tiers)

While it possible to define a cache with a single storage tier of any type (heap, off-heap or disk), you must always define a heap storage tier when configuring more than one storage tiers for your cache.

Storage tier sizing

When using multiple storage tiers, Ehcache expects that each succeeding tier be larger than the previous tier. In other words, the heap tier must be smaller than the off-heap tier and disk tier and the off-heap tier must be smaller than the disk tier. 

It is possible to use define tiers in different denominations, for example, a heap tier sized by entries and an off heap tier sized by bytes, in this case Ehcache can't ensure that the heap tier is actually smaller than the off-heap tier.

Disk storage location

If you use a disk storage tier in your cache, the cache will store its contents on the file system. You can control the location of the cache files with Magnolia properties and configuration.

By default the location for disk storage is:

${magnolia.cache.startdir}/${magnolia.cache.manager.id}

magnolia.cache.startdir defaults to ${magnolia.home}/cache.

magnolia.cache.manager.id defaults to ${magnolia.app.rootdir}.

See Configuration management for more on configuring Magnolia properties.

You can also set the cache location by setting the property "diskStorePath" for the cache factory configuration at /modules/cache/config/cacheFactory/delegateFactories/cacheFactory.

Setting the diskStorePath property may override the settings of the Magnolia properties magnolia.cache.startdir and magnolia.cache.manager.id.

If diskStorePath is an absolute path, the disk cache files will be stored at its location.

if diskStorePath is a relative path, the disk cache files will be stored at ${magnolia.cache.startdir}/<diskStorePath>.

Cache persistence

The contents of a cache can be saved and restored after restarting Magnolia. Cache persistence thus saves the time for the cache to be repopulated.

Only a cache with a disk storage tier can be persisted, so if you want a persistent cache, only the following cache configurations tiers can be used:

• disk only (single tier)
• heap + disk (2 tiers)
• heap + off-heap + disk (3 tiers)

Configuring a persistent cache

As mentioned, a persistent cache has to have a disk storage tier. The cache can configured to be persistent by setting the property "persistent" for the disk tier configuration /modules/cache/config/cacheFactory/delegateFactories/ehcache3/caches/<cache name>/resourcePoolsBuilder/pools/<disk tier name> to "true".

Configuration

Ehcache has its own configuration options that can be set in /modules/cache/config/cacheFactory/ .

Property	Default value	Description
keyType	none	required The key type for the cache.
valueType	none	required The value type for the cache.
resourceType	HEAP	The type of the cache pool: HEAP , OFFHEAP , or DISK . See Storage tiers in http://www.ehcache.org/documentation/3.0/caching-concepts.html.
resourceUnit	ENTRIES	The size-type applied for the given resource pool. The HEAP pool can be sized by entries (ENTRIES) or by bytes (B, KB, MB, GB, TB, PB). The OFFHEAP and DISK pools are sized by bytes only ( B , KB , MB , GB , TB , PB ).
persistent	false	Persistence of the disk storage pool. Persistence means the cache will survive a JVM restart. Only a DISK tier can set persistent to true. Setting a HEAP or OFFHEAP tier to be persistent will result in an error.
size	10	required The size of the given resource pool.
expiry / create	infinite	Lifetime in seconds for all entries when those are initially added. This does not apply to entries with an explicitly specified time to live (TTL). infinite means that the mapping will never expire.
expiry / update	none	Expiration time in seconds when an existing entry is updated. none means that the expiration time remains unchanged.
expiry / access	none	Expiration time in seconds when an existing entry is accessed. none means that the expiration time remains unchanged.
blockingTimeout	10000	Instructs Ehcache to wait the specified time in milliseconds before attempting to cache the request.  Create the blockingTimeout property in the tree at the same level where the info.magnolia.module.cache.ehcache3.EhCache3Factory class is defined, not inside the <cacheName> node.