Cache

Magnolia Cache module provides caching functionality to the rest of Magnolia web application. This documentation describes new cache module available in Magnolia 3.6 and higher.

Installing Module

Module is installed by default. To restore default configuration, delete /modules/cache node and restart your server.

Uninstalling Module

Remove the /modules/cache node and its subnodes. Shutdown Magnolia, remove module jar from WEB-INF/lib and start up Magnolia again.

Usage & Details

The central piece of the cache module is cache filter that orchestrates all the different pieces. Other then that cache module has following different parts:
  • Cache Policies
  • Flush Policies
  • Executors
The default cache implementation uses as its backend EHCache. Underlying cache engine can be changed by implementing info.magnolia.module.cache.Cache interface and by implementing info.magnolia.module.cache.CacheFactory interface. Cache factory can be configured at admin interface in /modules/cache/config/cacheFactory/class. For the default cache implementation using EHCache underneath, you can change various of its parameters at /modules/cache/config/cacheFactory/defaultCacheConfiguration

Cache Policies

Cache policies serve as an instrument to instruct cache how to handle every and each request that comes to it. Two different kinds of cache policies can configured:
  • Server cache policy
  • Client (browser) cache policy
Server cache policy controls server caching behaviour, while client cache policy instructs browser cache via various header settings.

Server cache policy

  • Configured at /modules/cache/config/configurations/default/cachePolicy
  • Default implementation checks if the content exists in the EHCase store and requests caching if not found.

Client cache policy

  • configured at /modules/cache/config/configurations/browserCachePolicy
  • Default implementation (info.magnolia.module.cache.browsercachepolicy.FixedDuration) instructs browser to cache the given item for fixed period of time (30 minutes). The time can be changed by setting expirationMinutes node data value.
  • Other policy provided by default is info.magnolia.module.cache.browsercachepolicy.Never. This is effectively no-op policy not instructructing browser to do anything. This policy can be set by replacing value of class element of the browserCachePolicy.

Flush Policy

  • Flush policy is asynchronously informed about every content change on given instance, be it change induced by activation, import or content editing. The policy can then decide whether cache needs to be flushed partially or completely or not at all.

Executors

Default cache implementation delivers following different executors:
  • Store
  • Bypass
  • UseCache
Executors can be configured at /modules/cache/config/configurations/executors Each of the executors is also responsible for configuring expiration headers.

Store executor

Multiplexes the output stream and stores the content in the cache.

UseCache executor

Retrieves cached item from the cache and streams it back to client.

Bypass

Effectively no-op executor. Doesn't trigger caching of the content and doesn't try to serve it from the cache either. This is useful for content that can't or should not be cached.

How it all works

When requests arrives at the cache filter, filter passes request first to currently configured browserCachePolicy (so in case content have not been modified and client already has it, magnolia can respond with just *304 - Not Modified*), then to currently configured server cache Policy asking for what to do with the request. Cache policy returns to filter expected behaviour after analysing the request. Based on expected behaviour cache filter then invokes appropriate executor. This setting allows for adding/removing executors and making use of them just by exchanging current cache policy for new one.

Flush policy on the other hand is completely independent from this chain and reacts on content changes rather then while serving content.

What is cached and what is not

By default, the following URLs are cached:
  • on a public instance: everything except /.magnolia/*
  • on an author instance: all static resources /.resources/* (if the magnolia.develop property is set to false)
If you are developing and testing a new module and you need to disable caching of static resources as well, change the value of the magnolia.develop property in your magnolia.properties file to true.

For more complex configurations, you'll need to tweak the configuration under the /config/configuration/default/cachePolicy/voters node in the admin interface.

Flushing the cache

There are a couple of different ways to flush the cache:
  • shutdown Magnolia, delete the cache directory, restart.
  • enable JMX (it is enabled by default on some application servers), connect to the server using jconsole or use your server's own JMX administration interface if provided, find the bean called net.sf.ehcache.CacheManager bean, and invoke the flush() operation of the default instance of the cache.
Note that the cache is not aware of the web application context, so when changing the context of a previously deployed application, you need to flush the cache to make sure served pages do not contains absolute links still pointing to old context path.