Cache Module

The Cache Module provides caching APIs which are independent of any underlying cache framework. The main advantages of using cache are:

  • the possibility to handle large data sets that usually cannot be fully loaded in memory; this is possible because the Cache module has a fixed size and old entries can be evicted from cache.
  • improved performance for processes that take more time to execute.
  • avoidance of repeated retrieving of wiki pages from the database when their content is rarely modified.

The source code is available on GitHub.

The Cache Component

The general process of using the Cache component consists of 3 main steps.

Access the CacheManager Component

The component manager interface is org.xwiki.cache.CacheManager and it can be accessed using the components engine. The process is detailed by the XWiki component tutorial on

Create a New Cache

To create a new cache you first need to define a CacheConfiguration object as follows: CacheConfiguration cacheConfiguration = new CacheConfiguration();

Next, you have to set the cache object properties like identifier, capacity and eviction policy. The identifier can be used to overwrite the cache configuration based on a configuration file:


For the eviction policy, you need to create an LRUEvictionConfiguration object:

LRUEvictionConfiguration lru = new LRUEvictionConfiguration();

The LRUEvictionConfiguration class is a helper for the EntryEvictionConfiguration.Algorithm#NONE cache algorithm which handles the eviction of the least recently used entry when thresholds are hit.

Next, you have to set the maximum cache size for example to 1000 entries and the maximum time to live without being used to 1 hour:


The final step is to affect the eviction cache configuration:

cacheConfiguration.put(LRUEvictionConfiguration.CONFIGURATIONID, lru);

Use the New Cache

To create you new cache object, use the <T> Cache<T> createNewCache(CacheConfiguration config) method as follows:

Cache<MyCacheClass> cache = cacheManager.createNewCache(cacheConfiguration);

Next, add a value to the "key" identifier for the cache affected,

cache.set("key", value);

retrieve the previously stored value

MyCacheClass storedValue = cache.get("key");

and remove the entry associated with the provided key from the cache:


Cache Configuration Files

When there is no specific overwrite assigned to a cache identifier, the priority for the cache configuration initialization is:

  • the default cache configuration 
  • the Java configuration


  • The default configuration file is "webapps/xwiki/WEB-INF/cache/infinispan/config.xml"
  • The official Infinispan documentation is available here

When having multiple XWiki web applications running in the same servlet container, make sure to update the jmxDomain value found under the globalJmxStatistics tag in order to have a unique name. The default value is org.xwiki.infinispan. 


  • The default configuration files are located under "webapps/xwiki/WEB-INF/cache/jbosscache/"
  • The official JBossCache documentation is available here


  • The default configuration files are located under "webapps/xwiki/WEB-INF/cache/oscache/"
  • The official JBossCache documentation is available here

Documentation References


Related Pages

Trying to decide between Cloud and On Premise? See the comparison on the XWiki Help Center.

Search this space