Package org.cache2k.expiry

Interface ExpiryPolicy<K,V>

All Superinterfaces:

DataAware<K,V>, ExpiryTimeValues

public interface ExpiryPolicy<K,V>
extends ExpiryTimeValues, DataAware<K,V>

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.

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, NOW, REFRESH

Method Summary

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

Method Detail

calculateExpiryTime

long calculateExpiryTime(K key,
                         @Nullable
                         V value,
                         long startTime,
                         @Nullable
                         @Nullable CacheEntry<K,V> currentEntry)

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: Calling other cache methods may cause errors or deadlocks.

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

Loader exceptions

The expiry policy is only called for a successful load operation.

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 fewer parameters. But the "real" entry can only be filled after the expiry policy has been run, 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. Time values: For performance reasons the long type is used to represent the time and not an object. Also, it allows a simple offset calculation.

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.

startTime - The time the operation started. If the cache used the loader to retrieve the value this is the time before the load was started

currentEntry - entry representing the current mapping. null if there is no current mapping, or, if the previous load operation had thrown an exception. This can be used for adapting the expiry time to the amount of data changes.

Returns:

the time of expiry in millis since epoch. ExpiryTimeValues.NOW if it should not be cached. If Cache2kBuilder.refreshAhead(boolean) is enabled the return value ExpiryTimeValues.NOW will 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()