Module com.github.benmanes.caffeine
Package com.github.benmanes.caffeine.cache

Interface Policy.VarExpiration<K,V>

Type Parameters:
K - the type of keys
V - the type of values
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
    Description
    default @Nullable V
    compute(K key, BiFunction<? super K,? super V,? extends @Nullable V> remappingFunction, Duration duration)
    Attempts to compute a mapping for the specified key and its current mapped value (or null if there is no current mapping).
    default Optional<Duration>
    getExpiresAfter(K key)
    Returns the duration until the entry should be automatically removed.
    OptionalLong
    getExpiresAfter(K key, TimeUnit unit)
    Returns the duration until the entry should be automatically removed.
    Map<K,V>
    oldest(int limit)
    Returns an unmodifiable snapshot Map view of the cache with ordered traversal.
    default <T> T
    oldest(Function<Stream<Policy.CacheEntry<K,V>>,T> mappingFunction)
    Returns the computed result from the ordered traversal of the cache entries.
    @Nullable V
    put(K key, V value, long duration, TimeUnit unit)
    Associates the value with the key in this cache.
    default @Nullable V
    put(K key, V value, Duration duration)
    Associates the value with the key in this cache.
    @Nullable V
    putIfAbsent(K key, V value, long duration, TimeUnit unit)
    Associates the value with the key in this cache if the specified key is not already associated with a value.
    default @Nullable V
    putIfAbsent(K key, V value, Duration duration)
    Associates the value with the key in this cache if the specified key is not already associated with a value.
    void
    setExpiresAfter(K key, long duration, TimeUnit unit)
    Specifies that the entry should be automatically removed from the cache once the duration has elapsed.
    default void
    setExpiresAfter(K key, Duration duration)
    Specifies that the entry should be automatically removed from the cache once the duration has elapsed.
    Map<K,V>
    youngest(int limit)
    Returns an unmodifiable snapshot Map view of the cache with ordered traversal.
    default <T> T
    youngest(Function<Stream<Policy.CacheEntry<K,V>>,T> mappingFunction)
    Returns the computed result from the ordered traversal of the cache entries.

  • Method Details

    • getExpiresAfter

      OptionalLong getExpiresAfter(K key, TimeUnit unit)
      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
      unit - the unit that age is expressed in
      Returns:
      the duration if the entry is present in the cache
      Throws:
      NullPointerException - if the specified key or unit is null

    • getExpiresAfter

      default 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
      Throws:
      NullPointerException - if the specified key is null

    • setExpiresAfter

      void setExpiresAfter(K key, long duration, 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 specified key or unit is null

    • setExpiresAfter

      default void setExpiresAfter(K key, 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
      NullPointerException - if the specified key or duration is null

    • putIfAbsent

      @Nullable V putIfAbsent(K key, V value, long duration, 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 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
      unit - the unit that duration is expressed in
      Returns:
      the previous value associated with the specified key, or null if there was no mapping for the key.
      Throws:
      IllegalArgumentException - if duration is negative
      NullPointerException - if the specified key, value, or unit is null

    • putIfAbsent

      default @Nullable V putIfAbsent(K key, V value, 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 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:
      the previous value associated with the specified key, or null if there was no mapping for the key.
      Throws:
      IllegalArgumentException - if duration is negative
      NullPointerException - if the specified key, value, or duration is null

    • put

      @Nullable V put(K key, V value, long duration, 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 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
      unit - the unit that duration is expressed in
      Returns:
      the previous value associated with key, or null if there was no mapping for key.
      Throws:
      IllegalArgumentException - if duration is negative
      NullPointerException - if the specified key, value, or unit is null

    • put

      default @Nullable V put(K key, V value, 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 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
      Returns:
      the previous value associated with key, or null if there was no mapping for key.
      Throws:
      IllegalArgumentException - if duration is negative
      NullPointerException - if the specified key, value, or duration is null

    • compute

      default @Nullable V compute(K key, BiFunction<? super K,? super V,? extends @Nullable V> remappingFunction, Duration duration)
      Attempts to compute a mapping for the specified key and its current mapped value (or null if there is no current mapping). The entire method invocation is performed atomically. The supplied function is invoked exactly once per invocation of this method. Some attempted update operations on this cache by other threads may be blocked while the computation is in progress, so the computation should be short and simple. This method differs from cache.asMap().compute(key, remappingFunction) by substituting the configured Expiry with the specified duration.

      Warning: the remappingFunction must not attempt to update any other mappings of this cache.

      Parameters:
      key - key with which the specified value is to be associated
      remappingFunction - the function to compute a value
      duration - the length of time from now when the entry should be automatically removed
      Returns:
      the new value associated with the specified key, or null if none
      Throws:
      IllegalArgumentException - if duration is negative
      NullPointerException - if the specified key, remappingFunction, or duration is null
      IllegalStateException - if the computation detectably attempts a recursive update to this cache that would otherwise never complete
      RuntimeException - or Error if the remappingFunction does so, in which case the mapping is unchanged

    • oldest

      Map<K,V> oldest(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 the oldest entry to the youngest
      Throws:
      IllegalArgumentException - if the limit specified is negative

    • oldest

      default <T> T oldest(Function<Stream<Policy.CacheEntry<K,V>>,T> mappingFunction)
      Returns the computed result from the ordered traversal of the cache entries. The oorder 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 computation.

      Usage example: 

      
   List<K> tenOldestKeys = cache.policy().expireAfterVariably().orElseThrow()
       .oldest(stream -> stream.map(Map.Entry::getKey).limit(10).toList());

      Beware that this computation is performed within the eviction policy's exclusive lock, so the computation should be short and simple. While the computation is in progress further eviction maintenance will be halted.

      Type Parameters:
      T - the type of the result of the mappingFunction
      Parameters:
      mappingFunction - the mapping function to compute a value
      Returns:
      the computed value
      Throws:
      NullPointerException - if the mappingFunction is null
      RuntimeException - or Error if the mappingFunction does so

    • youngest

      Map<K,V> youngest(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 the youngest entry to the oldest
      Throws:
      IllegalArgumentException - if the limit specified is negative

    • youngest

      default <T> T youngest(Function<Stream<Policy.CacheEntry<K,V>>,T> mappingFunction)
      Returns the computed result from the ordered traversal of the cache entries. 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 computation.

      Usage example: 

      
   List<K> tenYoungestKeys = cache.policy().expireAfterVariably().orElseThrow()
       .youngest(stream -> stream.map(Map.Entry::getKey).limit(10).toList());

      Beware that this computation is performed within the eviction policy's exclusive lock, so the computation should be short and simple. While the computation is in progress further eviction maintenance will be halted.

      Type Parameters:
      T - the type of the result of the mappingFunction
      Parameters:
      mappingFunction - the mapping function to compute a value
      Returns:
      the computed value
      Throws:
      NullPointerException - if the mappingFunction is null
      RuntimeException - or Error if the mappingFunction does so