Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
This page explains how to cache arbitrary objects in Magnolia. You can cache basically every object. This takes caching well beyond page and page fragment caching.
Required modules
The functionality for caching arbitrary objects is provided by at least two modules.
- Module
magnolia-cache-core
which defines the cache API. - A second module which implements the API. Magnolia provides two implementations based on established third-party libraries for the low-level functions.
magnolia-cache-ehcache
is the default implementation which uses Ehcache.magnolia-cache-ehcache3
is the default implementation which uses Ehcache3.magnolia-cache-memcached
is a high-performance, distributed memory object caching system which uses Memcached.
Things to note about arbitrary object caching
Speed up services
The main reason to cache objects is to serve data faster and to save resources (cpu, memory, network load, etc.). For instance, use object caching when there is heavy request on a Magnolia "service" which must provide data from a remote source.
Assure data validity
When delivering cached data you will probably need a mechanism to ensure cached data is valid and not outdated! How to handle this depends on the use case.
Restrict the lifetime of cached objects
When putting objects to the cache you can restrict their lifetime. In this case, instead of checking the validity of cached objects, you can simply let them expire over time.
Configure the cache
Magnolia allows to configure a cache factory specifically for each cache. For example you could have a specific configuration for fooBarCache
. When no specific configuration is defined, the default
factory configuration is used.
Configuration differs depending on which version of Ehcache you use.
Ehcache
This is an example of how to configure a cache using Ehcache 2. Here you will find documentation of all configuration options.
Extend the default
factory and override the persistence strategy with none
. This persistence strategy allows to cache non-serializable objects.
Node name | Value |
---|---|
modules | |
cache | |
config | |
cacheFactory | |
caches | |
default | |
fooBarCache | |
extends | ../default |
timeToLiveSeconds | 300 |
persistence | |
strategy | none |
The
/modules/cache/config/cacheFactory/caches/fooBarCache
node defines the cache name. fooBarCache
is the "name" of the cache which was also used above when acquiring the Cache object within Java code.
Ehcache3
This is an example of how to configure a cache using Ehcache 3. Here you will find documentation of all configuration options.
Extend the default
factory and override the persistence strategy for disk
set to the value false
. This persistence strategy allows to cache non-serializable objects.
Node name | Value |
---|---|
modules | |
cache | |
config | |
cacheFactory | |
delegateFactories | |
default | |
fooBarCache | |
resourcePoolsBuilder | |
pools | |
disk | |
persistent | false |
extends | ../default |
timeToLiveSeconds | 300 |
The
/modules/cache/config/cacheFactory/delegateFactories/fooBarCache
node defines the cache name. fooBarCache
is the "name" of the cache which was also used above when acquiring the Cache object within Java code.
Get the cache
Achieve an instance of Cache. This is your cache to operate on. Give it a name which must be unique within the system.
Example:
import javax.inject.Inject; import javax.inject.Provider; import info.magnolia.module.cache.Cache; import info.magnolia.module.cache.inject.CacheFactoryProvider; public class MyClass { private final Provider<CacheFactoryProvider> cacheFactoryProvider; @Inject public MyClass(Provider<CacheFactoryProvider> cacheFactoryProvider){ this.cacheFactoryProvider = cacheFactoryProvider; } public void fooBar(){ Cache cache = cacheFactoryProvider.get().get().getCache("fooBarCache"); } }
- Lines 2, 4-6: Inject CacheFactoryProvider and keep it as a final member of your class.
- Line 9: Fetch the Cache with its name. The cache provider will always return the same instance once it has been created.
All subsequent actions - adding, reading and removing objects - are applied on this Cache
object.
Cache Interface
public interface Cache { boolean hasElement(Object key); void put(Object key, Object value); void put(Object key, Object value, int timeToLiveInSeconds); Object get(Object key); Object getQuiet(Object key); void remove(Object key); void clear(); String getName(); int getSize(); Collection<Object> getKeys(); }
Put to cache
Cache knows two methods to append objects.
void put(Object key, Object value); void put(Object key, Object value, int timeToLiveInSeconds);
Arguments:
key | required The identifier of the object to cache |
value | required The object to cache |
timeToLiveInSeconds | optional The lifetime of the cached object in seconds. Tip: The lifetime also can be configured globally, and you can configure a flush policy to clear the cache when some condition is met, or you may want to delete cached objects programmatically (see #remove and #clear below). |
Example:
public class MyClass { public Object put(Object key, Object value){ Cache cache = cacheFactoryProvider.get().get().getCache("fooBarCache"); cache.put(key, value); return value; } public Object put(Object key, Object value, int timeToLiveInSeconds){ Cache cache = cacheFactoryProvider.get().get().getCache("fooBarCache"); cache.put(key, value, timeToLiveInSeconds); return value; } }
Retrieve from cache
There are two methods to retrieve an object from cache.
Object get(Object key); Object getQuiet(Object key);
get
Returns an object from the cache and blocks all the requests for the same key.
Example:
public JsonNode getData(String productId) throws Exception { Cache cache = cacheFactoryProvider.get().get().getCache(CACHEKEY); try { JsonNode jsonNode = (JsonNode) cache.get(productId); if (jsonNode != null) { return jsonNode; } else { jsonNode = readJson(productId); cache.put(productId, jsonNode); return jsonNode; } } catch (Exception e) { cache.put(productId, null); //unblock cache! throw e; } }
Use #get
when you are unsure whether the desired object is already cached. If the object is not yet cached, you should acquire it by other means and add it to the cache.
It is good practice to call #get
and #put
within the same associated try-catch-finally block for the same cache key.
If there is no object for a key, add null
to the cache anyway. This way you can ensure that the service doesn't try to read data for a key without an existing value more than one time
getQuiet
Returns an object from the cache but does NOT block requests for the same key.
Use #getQuiet
to acquire objects which are already cached.
This method is used more to "observe" or manage cached objects than to fetch a specific object. The Magnolia Cache Browser app is using #getQuiet, for instance.
Example:
public List getCachedObjects() { List<Object> cachedObjects = new ArrayList<>(); Cache cache = cacheFactoryProvider.get().get().getCache(NAME_OF_CACHE); Collection<Object> keys = cache.getKeys(); for (Object key : keys) { Object value = cache.getQuiet(key); if (value != null) { cachedObjects.add(value); } } return cachedObjects; }
Line 8: Uses #getQuiet
Delete from cache
Remove a single item
Cache cache = cacheFactoryProvider.get().get().getCache("fooBarCache"); cache.remove("fb-90270240-xyz");
Clear complete cache
#clear
deletes all items of a specific Cache which is identified by its "name"
cacheFactoryProvider.get().get().getCache("fooBarCache").clear()