public interface ExpiryPolicy<K,V> extends ExpiryTimeValues
For some expiry calculations it is useful to know the previous entry, e.g. to detect whether the stored data was updated. If a previous value is present in the cache, it is passed to this method. Expired old entries will be passed in also, if still present in the cache.
The expiry policy is also used for refresh ahead, determining the time when an entry should be automatically refreshed.
long calculateExpiryTime(K key, V value, long loadTime, CacheEntry<K,V> oldEntry)
By default expiry itself happens lenient, which means the expiry happens
zero or some milliseconds after the obtained time. If sharp expiry is requested,
the value will not be returned any more by the cache when the point in time is reached.
The cache parameters
Cache2kBuilder.refreshAhead(boolean) influence the behaviour.
It is also possible to request a sharp timeout for some entries. This is done
by returning a negative time value, see the further comments for the return
Inserts or updates: It is possible to return different expiry times for inserts or updates. An update can be detected by the presence of the old entry.
Calling cache operations: It is illegal to call any cache methods from this method. The outcome is undefined and it can cause a deadlock.
Calling time:The method is called from the cache, whenever a cache entry is updated. However, it is legal that the cache calls the method at arbitrary times during the entry lifecycle.
null values: If the loader returns a
null value, the expiry
policy will be called, regardless of the
If the expiry policy returns a
ExpiryTimeValues.NO_CACHE the entry will be removed. If the expiry
policy returns a different time value, a
NullPointerException will be propagated
null values are not permitted.
API rationale: The recently loaded or inserted data is not passed in via a cache entry object. Using a cache entry is desirable for API design reasons to have a thinner interface. But the "real" entry can only be filled after the expiry policy is done, passing in an entry object would mean to build a temporary object, increasing GC load. Second, the properties that are needed by the implementation are available directly. The downside, OTOH, 4-arity breaks Java 8 lambdas.
key- the cache key used for inserting or loading
value- the value to be cached. May be
nullif the loader returns
null, regardless of the
loadTime- The time the entry was inserted or loaded. If a loader was used, this is the time before the loader was called.
oldEntry- entry representing the current mapping, if there is a value present. If the old entry holds an exception, this is
null. Expired entries will be passed in as well if still in the cache.
ExpiryTimeValues.NO_CACHEif it should not cached. If
Cache2kBuilder.refreshAhead(boolean)is enabled the return value
ExpiryTimeValues.NO_CACHEwill remove the entry from the cache and trigger an immediate refresh. The return value
ExpiryTimeValues.ETERNALmeans that there is no specific expiry time known or needed. The effective expiry duration will never be longer than the configured expiry value via
Cache2kBuilder.expireAfterWrite(long, TimeUnit). If a negative value is returned, the negated value will be the expiry time used, but sharp expiry is requested. Use
Expiry.toSharpTime(long)to have a more expressive code. Switching on
Cache2kBuilder.sharpExpiry(boolean)means always sharp expiry.
cache2k API documentation. Copyright © 2000–2019 headissue GmbH, Munich.