Cache Module
 | Provides caching APIs independent of any underlying cache framework |
| Type | JAR |
| Category | |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard |
Description
Why use cache
When you have to execute a process that takes a lot of time to execute but you need to have good response time performances. In addition you need to be manipulating a large data set that cannot be contained fully in memory. Otherwise if it could, you should just use a standard Java Map which is less resource intensive than a Cache object. The advantage of the Cache module is that it has a fixed size and can eject entries out of the cache (old entries for example in a LRU Cache).
For example, the wiki pages are stored in a database, but we create a Java representation of the pages from the database. This is a time-consuming process. In a public wiki the same page could be downloaded by lots of users without being edited. To avoid reloading the page from the database for each user we store the result of the page creation in a cache. When following users ask for the page it is directly taken from the cache.
Use XWiki cache component
The general process is to access CacheManager component, set a CacheConfiguration and create a new cache with it.
Access the Component Manager
See XWiki component tutorial in order to learn how to access a component. The component manager role/interface is org.xwiki.cache.CacheManager.
Create and set CacheConfiguration
To create a new cache we have to create a CacheConfiguration object where we set the cache properties (identifier, maximum size, etc.)
CacheConfiguration cacheConfiguration = new CacheConfiguration();
// Set the configuration identifier. This can be used to overwrite this cache configuration based on configuration file.
// It can also be used for other things like clustering or filesystem cache depending of the implementation.
cacheConfiguration.setConfigurationId("xwiki.store.pagecache");
// Configure cache eviction policy
LRUEvictionConfiguration lru = new LRUEvictionConfiguration();
// The maximum entries the cache can contain. When the cache reaches that any element, the defined eviction
// algorithm kicks in to remove existing cache entries. Set to 1000 entries in this example.
lru.setMaxEntries(1000);
// Configure cache expiration policy
// The time a cache entry will continue to stay in the cache after being last accessed, in seconds. When
// the time is reached, the entry is expired and removed from the cache. In addition, when the cache reaches
// its maximum number of entries, the defined eviction algorithm is used (e.g. LRU) and thus an entry can
// stay less time in the cache than its maximum defined time. Set to 1 hour in this example.
lru.setTimeToLive(3600);
// [Since 7.4M2] The time a cache entry will continue to stay in the cache after being last accessed, in
// seconds. When the time is reached, the entry is expired and removed from the cache. In addition, when
// the cache reaches its maximum number of entries, the defined eviction algorithm is used (e.g. LRU) and
// thus an entry can stay less time in the cache than its maximum defined time. This property replaces the
// timeToLive one. Set to 1 hour in this example.
lru.setMaxIdle(3600);
// [Since 7.4M2] The maximum lifespan of a cache entry, after which the entry is expired and removed from
// the cache, in seconds. In addition, when the cache reaches its maximum number of entries, the defined
// eviction algorithm is used (e.g. LRU) and thus an entry can stay less time in the cache than its maximum
// defined time. Set to 1 hour in this example.
lru.setLifespan(3600);
// Affect eviction cache configuration to cache configuration
cacheConfiguration.put(LRUEvictionConfiguration.CONFIGURATIONID, lru);
Create the cache
Use the cache
The cache works like a basic map, you assign a value to a string key and you can get this value latter using the key.
// add the value to the cache affected to "key" identifier
cache.set("key", value);
// get the value previously stored
MyClass storedValue = cache.get("key");
// remove the entry associated with the provided key from the cache.
cache.remove("key");
Cache Control
The component org.xwiki.cache.CacheControl allow controlling the behavior of some caches generally to indicate that they should be disabled for the current request/thread.
This component is automatically used when the force refresh is used in the browser (when the HTTP Cache-Control value is no-cache).
Advanced use of cache component
Disposable cache entry
When you need to cleanup some resources associated to a cache entry that are not automatically disposed by JAVA garbage collector (like some files), you can be called automatically by the cache manager when an entry is removed or evicted.
For that you need to implement org.xwiki.cache.DisposableCacheValue, when the cached entry is removed form the cache org.xwiki.cache.DisposableCacheValue#dispose() is automatically called.
{
private File file;
public void dispose() throws Exception
{
file.delete();
}
}
Overwrite cache configuration in configuration file (implementation specific)
Cache clients are supposed to assign a cache identifier for each cache used. All cache implementations allow an admin to overwrite the configuration with implementation specific configuration files.
Infinispan
It's possible to overwrite the configuration of any XWiki cache through the file WEB-INF/cache/infinispan/config.xml.
For example to overwrite the configuration of the cache with name xwiki.store.cache.capacity (the one controlling the cache of document) add a local cache configuration with name xwiki.store.cache.capacity. You can look at https://infinispan.org/docs/11.0.x/titles/configuring/configuring.html for more details about Infinispan configuration.
Change default cache component implementation (implementation specific)
When no specific overwrite is assigned to a cache identifier, the cache configuration is first initialized with the default cache configuration and then java configuration is applied to overwrite or add constraints.
Infinispan
The default configuration (and all custom configuration) is located in the file WEB-INF/cache/infinispan/config.xml
Listen to the cache activity
It's possible to register in JAVA a listener to receive any event happening in the cache (value modified, removed, etc...). For that implement the org.xwiki.cache.event.CacheEntryListener and register using org.xwiki.cache.Cache#addCacheEntryListener(CacheEntryListener listener).
