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

Interface Policy.FixedExpiration<K,V>

Type Parameters:
K - the type of keys
V - the type of values
Enclosing interface:
Policy<K,V>
public static interface Policy.FixedExpiration<K,V>
The low-level operations for a cache with a fixed expiration policy.

  • Method Summary

    Modifier and Type
    Method
    Description
    default Optional<Duration>
    ageOf(K key)
    Returns the age of the entry based on the expiration policy.
    OptionalLong
    ageOf(K key, TimeUnit unit)
    Returns the age of the entry based on the expiration policy.
    default Duration
    getExpiresAfter()
    Returns the fixed duration used to determine if an entry should be automatically removed due to elapsing this time bound.
    long
    getExpiresAfter(TimeUnit unit)
    Returns the fixed duration used to determine if an entry should be automatically removed due to elapsing this time bound.
    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.
    void
    setExpiresAfter(long duration, TimeUnit unit)
    Specifies that each entry should be automatically removed from the cache once a fixed duration has elapsed.
    default void
    setExpiresAfter(Duration duration)
    Specifies that each entry should be automatically removed from the cache once a fixed 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

    • ageOf

      OptionalLong ageOf(K key, TimeUnit unit)
      Returns the age of the entry based on the expiration policy. The entry's age is the cache's estimate of the amount of time since the entry's expiration was last reset.

      An expiration policy uses the age to determine if an entry is fresh or stale by comparing it to the freshness lifetime. This is calculated as fresh = freshnessLifetime > age where freshnessLifetime = expires - currentTime.

      Parameters:
      key - the key for the entry being queried
      unit - the unit that age is expressed in
      Returns:
      the age if the entry is present in the cache
      Throws:
      NullPointerException - if the specified key is null

    • ageOf

      default Optional<Duration> ageOf(K key)
      Returns the age of the entry based on the expiration policy. The entry's age is the cache's estimate of the amount of time since the entry's expiration was last reset.

      An expiration policy uses the age to determine if an entry is fresh or stale by comparing it to the freshness lifetime. This is calculated as fresh = freshnessLifetime > age where freshnessLifetime = expires - currentTime.

      Parameters:
      key - the key for the entry being queried
      Returns:
      the age if the entry is present in the cache
      Throws:
      NullPointerException - if the specified key is null

    • getExpiresAfter

      long getExpiresAfter(TimeUnit unit)
      Returns the fixed duration used to determine if an entry should be automatically removed due to elapsing this time bound. An entry is considered fresh if its age is less than this duration, and stale otherwise. The expiration policy determines when the entry's age is reset.
      Parameters:
      unit - the unit that duration is expressed in
      Returns:
      the length of time after which an entry should be automatically removed
      Throws:
      NullPointerException - if the unit is null

    • getExpiresAfter

      default Duration getExpiresAfter()
      Returns the fixed duration used to determine if an entry should be automatically removed due to elapsing this time bound. An entry is considered fresh if its age is less than this duration, and stale otherwise. The expiration policy determines when the entry's age is reset.
      Returns:
      the length of time after which an entry should be automatically removed

    • setExpiresAfter

      void setExpiresAfter(long duration, TimeUnit unit)
      Specifies that each entry should be automatically removed from the cache once a fixed duration has elapsed. The expiration policy determines when the entry's age is reset.
      Parameters:
      duration - the length of time after which an 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(Duration duration)
      Specifies that each entry should be automatically removed from the cache once a fixed duration has elapsed. The expiration policy determines when the entry's age is reset.
      Parameters:
      duration - the length of time after which an entry should be automatically removed
      Throws:
      IllegalArgumentException - if duration is negative
      NullPointerException - if the duration is null

    • 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().expireAfterWrite().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().expireAfterWrite().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