Caching is useful for resource intensive tasks, remote data fetching and you should decide what to cache and when the
cache should expire.
Custom caches can be created by getting a cache builder by calling CacheProvider.cacheBuilder() with the type of
objects to be cached. Caches are identified by their namespace, when the builder already created a cache with the
same namespace, the existing cache will be returned.
When the builder is configured using the methods explained in the following sections, a PortaclCache instance is
created by calling its build() method.
Note that caches can be created even when caching is disabled in the portal
configuration, then returned caches will just never actually store anything.
Expiration settings
The cache will always remove old entries once maximumSize (the maximum number of elements in the cache) is reached
and new entries need to be added, but depending on the expireMode entries will also be removed when expireTime
seconds have passed.
The available expireModes are:
-
None: entries will never expire (but can still be removed due to size constraints).
-
Write: entries will be removed expireTime seconds after they have been created or updated.
This mode should be used for data that is costly to retrieve, but will get stale after some time.
-
Access: entries will be removed expireTime seconds after they have last been accessed.
This is the default when no expire mode is specified.
Automatic cache clear
The created cache can be automatically cleared when one of the clearEvents is received via the
eventbus. Common events to clear caches would be
events about creation, updates or deletion of Mesh nodes.
When no eventFilter is specified, the cache will be cleared when any of the clearEvents is received. The
eventFilter can inspect the body of the event to decide whether the cache should be cleared or not (e.g only
when an updated node has a certain schema).
Key mappers
Most methods of the created PortalCache will create a cache key from the
RoutingContext of the current request.
By default the key is created from the language, a hash of the users
roles and the branch of the current
request.
When the builder is told to useCustomKeyParams the configured
custom parameters will also be added to the created cache key.
A custom keyMapper can also be provided when creating a cache. This mapper can ignore the routing context completely
and return any key appropriate for the custom cache. Note that useCustomKeyParams will have no effect when a custom
keyMapper is specified.
Auxiliary disc cache
When the diskCacheRegion() is specified for the builder, a JCS backed cache is created instead of a Caffeine based
one. This requires a cache.ccf configuration
file with a basic configuration, in the config directory of the portal.
The IsEternal, MaxLife and MaxIdle element properties, as well as the MaxObjects cache property will be
overwritten with the above mentioned values passed to the builder.
Example
The following is an example of how to create a custom PortalCache for JsonObject values.
@Inject
public CacheProvider cacheProvider;
private PortalCache<JsonObject> cache;
/* ... */
public void initCache() {
cache = cacheProvider.cacheBuilder(JsonObject.class)
.namespace("cache.custom.users")
.expireTime(60)
.expireMode(ExpireMode.Write)
.clearEvents(MeshEvent.NODE_UPDATED)
.eventFilter(event -> {
return "portal_users".equals(
event.getBodyAsJson().get("schemaName").textValue());
})
.keyMapper(ignoredParam -> "users")
.build();
}