org.cache2k.expiry

Interface ExpiryPolicy<K,V>

All Superinterfaces:

ExpiryTimeValues

public interface ExpiryPolicy<K,V>
extends ExpiryTimeValues

A custom policy which allows to calculate a dynamic expiry time for an entry after an insert or update.

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.

Since:

0.20

Author:

Jens Wilke

See Also:

cache2k user guide - Expiry and Refresh, Cache2kBuilder.expiryPolicy(ExpiryPolicy), Cache2kBuilder.refreshAhead(boolean), Cache2kBuilder.expireAfterWrite(long, TimeUnit)

Field Summary

Fields inherited from interface org.cache2k.expiry.ExpiryTimeValues

ETERNAL, NEUTRAL, NO_CACHE, NOW, REFRESH

Method Summary

Modifier and Type	Method and Description
long	calculateExpiryTime(K key, V value, long loadTime, CacheEntry<K,V> oldEntry) Returns the time of expiry in milliseconds since epoch.

Method Detail

calculateExpiryTime

long calculateExpiryTime(K key,
                         V value,
                         long loadTime,
                         CacheEntry<K,V> oldEntry)

Returns the time of expiry in milliseconds since epoch.

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.sharpExpiry(boolean) and 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 value below.

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 Cache2kBuilder.permitNullValues(boolean) setting. 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 if 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.

Parameters:

key - the cache key used for inserting or loading

value - the value to be cached. May be null if the loader returns null, regardless of the Cache2kBuilder.permitNullValues(boolean) setting.

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.

Returns:

time the time of expiry in millis since epoch. ExpiryTimeValues.NO_CACHE if it should not cached. If Cache2kBuilder.refreshAhead(boolean) is enabled the return value ExpiryTimeValues.NO_CACHE will remove the entry from the cache and trigger an immediate refresh. The return value ExpiryTimeValues.ETERNAL means 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.

See Also:

ValueWithExpiryTime.getCacheExpiryTime()