Time Invalidated Cache

This feature is available starting from 3.0PR22Q2.

Introduction

A Time Invalidated Cache is a type of cache that can be used where performance is required and the cache must be invalidated after a specified period of time. It has lazy initialization, that means, a key will not be computed until it has been read.

Creation of Cache and initialization

To initialize a cache, TimeInvalidatedCache builder should be used:

• `newBuilder()` static initialization method will create the `TimeInvalidatedCacheBuilder`.
• `name("cacheName")` sets the name of the cache, it is required, used for logging
• `expireAfterDuration(Duration duration)` method allows setting a `Duration` object as the duration after which all keys will be evicted and considered expired in the cache. If not invoked, it will default to 1 minute.
• `build(loader)` call that should contain a lambda function to compute the value for each given key, if no value, return null. This will return the initialized cache.

Usage:

TimeInvalidatedCache<KeyType, ValueType> cache = TimeInvalidatedCache
    .newBuilder()
    .name("cacheName") // Sets the name of the cache
    .expireAfterDuration(Duration.ofMinutes(5)) // Could be any Duration, not necessarily in minutes. If not executed, 1 minute default is assumed
    .build(key -> generateKeyValue(key)) // This is a lambda that initializes the key if it expired or is the first time is read

How to get values from the cache

get will return the value given a key, and getAll will return a map(key-value) for a given collection of keys. Will return the value corresponding to the key, or null if the computed value is null.

In case of getAll, it will return a map with key-value, if the value is null, it will not appear in the returned map.

Both functions will throw the following exceptions:

• NullPointerException: if the specified key is null

Usage:

ValueType value = cache.get(key); // Returns the value corresponding to the given key. 
Map<KeyType, ValueType> values = cache.getAll(keys); // keys is a Collection of keys

Get or else default to

It is also possible to provide a default mappingFunction, this function receives a key or a set of key, depending if we are dealing with get or getAll function, and returns a value(which will be used instead if not found in cache and couldn't be computed), it will be a Map of KeyType, ValueType of values if using getAll.

cache.get("testKey", (key) -> "testDefaultValue"); // returns the value corresponding to testKey from cache or from computed cache function if not null. If that is null, it will return "testDefaultValue".
 
cache.getAll(testKeys,
        (keys) -> keys.stream().collect(Collectors.toMap(key -> key, key -> key + "Value")))
// Same as above, each key that's not found in the cache or couldn't be computed, is computed using the mapping function provided to the getAll as second argument

How to programatically invalidate the cache:

cache.invalidate(key); // Invalidates a single key in the cache, next time is retrieved it will be recomputed
cache.invalidateAll(); // Invalidates all the keys in the cache, next time any is retrieved it will be recomputed