public final Class Caffeine<K, V>

• automatic loading of entries into the cache, optionally asynchronously
• size-based eviction when a maximum is exceeded based on frequency and recency
• time-based expiration of entries, measured since last access or last write
• asynchronously refresh when the first stale request for an entry occurs
• keys automatically wrapped in weak references
• values automatically wrapped in weak or soft references
• writes propagated to an external resource
• notification of evicted (or otherwise removed) entries
• accumulation of cache access statistics

These features are all optional; caches can be created using all or none of them. By default, cache instances created by Caffeine will not perform any type of eviction.

Usage example:

LoadingCache<Key, Graph> graphs = Caffeine.newBuilder()
      .maximumSize(10_000)
      .expireAfterWrite(Duration.ofMinutes(10))
      .removalListener((Key key, Graph graph, RemovalCause cause) ->
          System.out.printf("Key %s was removed (%s)%n", key, cause))
      .build(key -> createExpensiveGraph(key));

The returned cache is implemented as a hash table with similar performance characteristics to ConcurrentHashMap. The asMap view (and its collection views) have weakly consistent iterators. This means that they are safe for concurrent use, but if other threads modify the cache after the iterator is created, it is undefined which of these changes, if any, are reflected in that iterator. These iterators never throw ConcurrentModificationException.

Entries are automatically evicted from the cache when any of maximumSize, maximumWeight, expireAfter, expireAfterWrite, expireAfterAccess, weakKeys, weakValues, or softValues are requested.

If maximumSize or maximumWeight is requested, entries may be evicted on each cache modification.

If expireAfter, expireAfterWrite, or expireAfterAccess is requested, then entries may be evicted on each cache modification, on occasional cache accesses, or on calls to Cache#cleanUp. A scheduler(Scheduler) may be specified to provide prompt removal of expired entries rather than waiting until activity triggers the periodic maintenance. Expired entries may be counted by Cache#estimatedSize(), but will never be visible to read or write operations.

If weakKeys, weakValues, or softValues are requested, it is possible for a key or value present in the cache to be reclaimed by the garbage collector. Entries with reclaimed keys or values may be removed from the cache on each cache modification, on occasional cache accesses, or on calls to Cache#cleanUp; such entries may be counted in Cache#estimatedSize(), but will never be visible to read or write operations.

Certain cache configurations will result in the accrual of periodic maintenance tasks that will be performed during write operations, or during occasional read operations in the absence of writes. The Cache#cleanUp method of the returned cache will also perform maintenance, but calling it should not be necessary with a high-throughput cache. Only caches built with maximumSize, maximumWeight, expireAfter, expireAfterWrite, expireAfterAccess, weakKeys, weakValues, or softValues perform periodic maintenance.

The caches produced by Caffeine are serializable, and the deserialized caches retain all the configuration properties of the original cache. Note that the serialized form does not include cache contents but only configuration.