 | Provides caching APIs independent of any underlying cache framework |
| Type | components |
| Category | |
| Developed by | Unknown |
| Rating | |
| License | Unknown |
Description
Why use cache
When you have to execute a pretty long process very often.
For example the wiki pages are stored in a database, but create a java representation of this page from the database. This is a very long process. In a public wiki the same page could be downloaded by lots of users without being edited. To avoid recreating 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 will be directly taken from the cache.
If we don't do this the general process from the user asking for a page to the page being rendered in the browser could take a lot more time.
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. Both JBossCache and OSCache allow an admin to overwrite the configuration with implementation specific configuration files.
JBossCache
To overwrite the configuration xwiki.store.cache.capacity (the one controlling the cache of document) put a file named xwiki.store.cache.capacity.xml with JBossCache configuration in WEB-INF/cache/jbosscache/ folder. You can look at http://www.jboss.org/community/wiki/JBossCacheOfficialDocumentation 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 JBossCache 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.
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).
