public final Class CacheBuilder<K, V>

Prefer Caffeine over Guava's caching API

The successor to Guava's caching API is Caffeine. Its API is designed to make it a nearly drop-in replacement -- though it requires Java 8 APIs, is not available for Android or GWT/j2cl, and may have different (usually better) behavior when multiple threads attempt concurrent mutations. Its equivalent to CacheBuilder is its Caffeine class. Caffeine offers better performance, more features (including asynchronous loading), and fewer bugs.

Caffeine defines its own interfaces (Cache, LoadingCache, CacheLoader, etc.), so you can use Caffeine without needing to use any Guava types. Caffeine's types are better than Guava's, especially for their deep support for asynchronous operations. But if you want to migrate to Caffeine with minimal code changes, you can use its CaffeinatedGuava adapter class, which lets you build a Guava Cache or a Guava LoadingCache backed by a Guava CacheLoader.

Caffeine's API for asynchronous operations uses CompletableFuture: AsyncLoadingCache.get returns a CompletableFuture, and implementations of AsyncCacheLoader.asyncLoad must return a CompletableFuture. Users of Guava's com.google.common.util.concurrent.ListenableFuture can adapt between the two Future types by using net.javacrumbs.futureconverter.java8guava.FutureConverter.

More on CacheBuilder

• automatic loading of entries into the cache
• least-recently-used eviction when a maximum size is exceeded (note that the cache is divided into segments, each of which does LRU internally)
• time-based expiration of entries, measured since last access or last write
• keys automatically wrapped in WeakReference
• values automatically wrapped in WeakReference or SoftReference
• 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 CacheBuilder will not perform any type of eviction.

Usage example:

LoadingCache<Key, Graph> graphs = CacheBuilder.newBuilder()
    .maximumSize(10000)
    .expireAfterWrite(Duration.ofMinutes(10))
    .removalListener(MY_LISTENER)
    .build(
        new CacheLoader<Key, Graph>() {
          public Graph load(Key key) throws AnyException {
            return createExpensiveGraph(key);
          }
        });

Or equivalently,

// In real life this would come from a command-line flag or config file
String spec = "maximumSize=10000,expireAfterWrite=10m";

LoadingCache<Key, Graph> graphs = CacheBuilder.from(spec)
    .removalListener(MY_LISTENER)
    .build(
        new CacheLoader<Key, Graph>() {
          public Graph load(Key key) throws AnyException {
            return createExpensiveGraph(key);
          }
        });

The returned cache implements all optional operations of the LoadingCache and Cache interfaces. 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, expireAfterWrite, expireAfterAccess, weakKeys, weakValues, or softValues are requested.

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

If expireAfterWrite or expireAfterAccess is requested entries may be evicted on each cache modification, on occasional cache accesses, or on calls to Cache#cleanUp. Expired entries may be counted by Cache#size, 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#size, but will never be visible to read or write operations.

Certain cache configurations will result in the accrual of periodic maintenance tasks which 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 removalListener, expireAfterWrite, expireAfterAccess, weakKeys, weakValues, or softValues perform periodic maintenance.

The caches produced by CacheBuilder 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.

See the Guava User Guide article on caching for a higher-level explanation.