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.
long calculateExpiryTime(K key, V value, long loadTime, @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.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.
nullvalues: If the loader returns a
nullvalue, the expiry policy will be called, regardless of the
Cache2kBuilder.permitNullValues(boolean)setting. If the expiry policy returns a
ExpiryTimeValues.NOWthe entry will be removed. If the expiry policy returns a different time value, a
NullPointerExceptionwill be propagated if
nullvalues are not permitted.
Loader exceptionsThe 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 less parameter. 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.
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.
currentEntry- entry representing the current mapping, if there is a value present.
nullif 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.
- the time of expiry in millis since epoch.
ExpiryTimeValues.NOWif it should not cached. If
Cache2kBuilder.refreshAhead(boolean)is enabled the return value
ExpiryTimeValues.NOWwill 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.
- See Also: