com.github.benmanes.caffeine.cache

Interface Policy.VarExpiration<K,V>

Enclosing interface:

Policy<K,V>

public static interface Policy.VarExpiration<K,V>

The low-level operations for a cache with a variable expiration policy.

Method Summary

Modifier and Type	Method and Description
default @NonNull Optional<Duration>	getExpiresAfter(K key) Returns the duration until the entry should be automatically removed.
@NonNull OptionalLong	getExpiresAfter(K key, @NonNull TimeUnit unit) Returns the duration until the entry should be automatically removed.
@NonNull Map<K,V>	oldest(@NonNegative int limit) Returns an unmodifiable snapshot Map view of the cache with ordered traversal.
default void	put(K key, V value, @NonNull Duration duration) Associates the value with the key in this cache.
default void	put(K key, V value, @NonNegative long duration, @NonNull TimeUnit unit) Associates the value with the key in this cache.
default boolean	putIfAbsent(K key, V value, @NonNull Duration duration) Associates the value with the key in this cache if the specified key is not already associated with a value.
default boolean	putIfAbsent(K key, V value, @NonNegative long duration, @NonNull TimeUnit unit) Associates the value with the key in this cache if the specified key is not already associated with a value.
default void	setExpiresAfter(K key, @NonNull Duration duration) Specifies that the entry should be automatically removed from the cache once the duration has elapsed.
void	setExpiresAfter(K key, @NonNegative long duration, @NonNull TimeUnit unit) Specifies that the entry should be automatically removed from the cache once the duration has elapsed.
@NonNull Map<K,V>	youngest(@NonNegative int limit) Returns an unmodifiable snapshot Map view of the cache with ordered traversal.

Method Detail

getExpiresAfter

@NonNull OptionalLong getExpiresAfter(K key,
                                      @NonNull TimeUnit unit)

Returns the duration until the entry should be automatically removed. The expiration policy determines when the entry's duration is reset.

This method is scheduled for removal in version 3.0.0.

Parameters:

key - the key for the entry being queried

unit - the unit that age is expressed in

Returns:

the duration if the entry is present in the cache

getExpiresAfter

default @NonNull Optional<Duration> getExpiresAfter(K key)

Returns the duration until the entry should be automatically removed. The expiration policy determines when the entry's duration is reset.

Parameters:

key - the key for the entry being queried

Returns:

the duration if the entry is present in the cache

setExpiresAfter

void setExpiresAfter(K key,
                     @NonNegative long duration,
                     @NonNull TimeUnit unit)

Specifies that the entry should be automatically removed from the cache once the duration has elapsed. The expiration policy determines when the entry's age is reset.

Parameters:

key - the key for the entry being set

duration - the length of time from now when the entry should be automatically removed

unit - the unit that duration is expressed in

Throws:

IllegalArgumentException - if duration is negative

NullPointerException - if the unit is null

setExpiresAfter

default void setExpiresAfter(K key,
                             @NonNull Duration duration)

Specifies that the entry should be automatically removed from the cache once the duration has elapsed. The expiration policy determines when the entry's age is reset.

Parameters:

key - the key for the entry being set

duration - the length of time from now when the entry should be automatically removed

Throws:

IllegalArgumentException - if duration is negative

putIfAbsent

default boolean putIfAbsent(K key,
                            V value,
                            @NonNegative long duration,
                            @NonNull TimeUnit unit)

Associates the value with the key in this cache if the specified key is not already associated with a value. This method differs from Map.putIfAbsent(K, V) by substituting the configured Expiry with the specified write duration, has no effect on the duration if the entry was present, and returns the success rather than a value.

This method is scheduled for removal in version 3.0.0.

Parameters:

key - the key with which the specified value is to be associated

value - value to be associated with the specified key

duration - the length of time from now when the entry should be automatically removed

unit - the unit that duration is expressed in

Returns:

true if this cache did not already contain the specified entry

Throws:

IllegalArgumentException - if duration is negative

putIfAbsent

default boolean putIfAbsent(K key,
                            V value,
                            @NonNull Duration duration)

Associates the value with the key in this cache if the specified key is not already associated with a value. This method differs from Map.putIfAbsent(K, V) by substituting the configured Expiry with the specified write duration, has no effect on the duration if the entry was present, and returns the success rather than a value.

Parameters:

key - the key with which the specified value is to be associated

value - value to be associated with the specified key

duration - the length of time from now when the entry should be automatically removed

Returns:

true if this cache did not already contain the specified entry

Throws:

IllegalArgumentException - if duration is negative

put

default void put(K key,
                 V value,
                 @NonNegative long duration,
                 @NonNull TimeUnit unit)

Associates the value with the key in this cache. If the cache previously contained a value associated with the key, the old value is replaced by the new value. This method differs from Cache.put(K, V) by substituting the configured Expiry with the specified write duration.

This method is scheduled for removal in version 3.0.0.

Parameters:

key - the key with which the specified value is to be associated

value - value to be associated with the specified key

duration - the length of time from now when the entry should be automatically removed

unit - the unit that duration is expressed in

Throws:

IllegalArgumentException - if duration is negative

NullPointerException - if the specified key or value is null

put

default void put(K key,
                 V value,
                 @NonNull Duration duration)

Associates the value with the key in this cache. If the cache previously contained a value associated with the key, the old value is replaced by the new value. This method differs from Cache.put(K, V) by substituting the configured Expiry with the specified write duration.

Parameters:

key - the key with which the specified value is to be associated

value - value to be associated with the specified key

duration - the length of time from now when the entry should be automatically removed

Throws:

IllegalArgumentException - if duration is negative

oldest

@NonNull Map<K,V> oldest(@NonNegative int limit)

Returns an unmodifiable snapshot Map view of the cache with ordered traversal. The order of iteration is from the entries most likely to expire (oldest) to the entries least likely to expire (youngest). This order is determined by the expiration policy's best guess at the time of creating this snapshot view.

Beware that obtaining the mappings is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the entries.

Parameters:

limit - the maximum size of the returned map (use Integer.MAX_VALUE to disregard the limit)

Returns:

a snapshot view of the cache from oldest entry to the youngest

youngest

@NonNull Map<K,V> youngest(@NonNegative int limit)

Returns an unmodifiable snapshot Map view of the cache with ordered traversal. The order of iteration is from the entries least likely to expire (youngest) to the entries most likely to expire (oldest). This order is determined by the expiration policy's best guess at the time of creating this snapshot view.

Beware that obtaining the mappings is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the entries.

Parameters:

limit - the maximum size of the returned map (use Integer.MAX_VALUE to disregard the limit)

Returns:

a snapshot view of the cache from youngest entry to the oldest