Cache Library
Contents
This library is used for basic caching of resources in memory. It will automatically evict old entries when the cache is full. To start using this library, add the following dependency to your build.gradle file:
dependencies {
include 'com.enonic.lib:lib-cache:2.2.0'
}Usage
To use this library in your JavaScript code, you first need to require it in your controller:
var cacheLib = require('/lib/cache');Then you will need to create a new cache with some settings. You can create multiple caches in your application.
With the way XP triggers your controller, the new cache needs to be created outside the scope of any exported request handler. If it is created inside, for example, exports.get(), you will only create a temporary cache on each request. |
var cache = cacheLib.newCache({
size: 100, (1)
expire: 3600 (2)
});| 1 | Maximum number of items in the cache before it will evict the oldest. |
| 2 | Number of seconds the items will be in the cache before it’s evicted. |
From here on you can now use the cache functions on the cache. To get (or populate if not exists) items you can do like this:
var item = cache.get('my-key', function() { (1)
return fetchSomethingHeavy(); (2)
});| 1 | Get function will either get the item if exists, or call the function to populate the cache. |
| 2 | Here you will do the actual population of the cache entry. |
API
Here’s the API methods that is defined in this library.
newCache
This will create a new cache instance.
Parameters
-
config(object) Configuration for the cache.-
size(number) Size of the cache (in number of items). -
expire(number) If set, each item will be automatically purged from the cache after a set period, in seconds, has elapsed since the item’s initial creation, or the most recent update of its value.
-
Examples
var cache = cacheLib.newCache({
size: 100,
expire: 3600
});Cache.get
This function will get (or populate) the named item from cache.
Parameters
-
key(string) Cache key to get. -
fetcher(function) Function to call if item does not exists. This needs to return what to cache.
Examples
var item = cache.get('my-key', function() {
return fetchSomethingHeavy();
});Cache.getIfPresent
This function will get the named item from cache if its set, otherwise it returns null.
Parameters
-
key(string) Cache key to get.
Examples
var item = cache.getIfPresent('my-key');Cache.put
This function will store the provided value for the named key in the cache, regardless if its previously set or not.
Parameters
-
key(string) Cache key to update. -
value(object) Value to store in the cache.
Examples
cache.put('my-key' , 'my-value');Cache.getSize
This will return the number of items currently in the cache.
Examples
var size = cache.getSize();Cache.remove
Removes an entry, identified by its key, from the cache. If the key is not found in the cache, no changes are made.
Parameter
-
key(string) Cache key to remove.
Examples
cache.remove('my-key');Cache.removePattern
Removes multiple entries, identified by a regular expression, from the cache. If the regex pattern does not match with any existing key, no changes are made.
Parameter
-
keyRegex(string) Regular expression pattern to match with keys to be removed.
Examples
cache.removePattern('product.*');Compatibility
This library is also a drop-in replacement for the library in Enonic XP released before 6.11.0. It can be used directly since it will work by using /lib/cache, /lib/xp/cache and /site/lib/xp/cache.
The remove and removePattern functions are only available since version 1.1.0
The getIfPresent and put functions are only available since version 2.2.0
