arrow-down

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.clear

This will clear all entries from the cache.

Examples

cache.clear();

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


Contents

Contents