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 Enterprise, XWiki Enterprise Manager |
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 that 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();
// Set maximum size of the cache as 1000 entries
lru.setMaxEntries(1000);
// Set the maximum time to live without being used to 1 hour
lru.setTimeToLive(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");
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 of evicted.
For that you need to implements org.xwiki.cache.DisposableCacheValue, when the cachen 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
To overwrite the configuration xwiki.store.cache.capacity (the one controlling the cache of document) add a named <namedCache> with name xwiki.store.cache.capacity in WEB-INF/cache/infinispan/config.xml file. You can look at https://docs.jboss.org/author/display/ISPN/Home for more details.
OSCache
To overwrite the configuration xwiki.store.cache.capacity (the one controlling the cache of the document) put a file named xwiki.store.cache.capacity.properties with OSCache configuration in it in the WEB-INF/cache/oscache/ folder. You can look at the http://www.opensymphony.com/oscache/wiki/Documentation.html for more details.
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
JBossCache
The default configuration files are:
- WEB-INF/cache/jbosscache/default.xml
- WEB-INF/cache/jbosscache/default-local.xml
OSCache
The default configuration files are:
- WEB-INF/cache/oscache/default.properties
- WEB-INF/cache/oscache/default-local.properties
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).
