A builder of
LoadingCache and
Cache instances having any combination of the
following features:
- automatic loading of entries into the cache
- least-recently-used eviction when a maximum size is exceeded
- time-based expiration of entries, measured since last access or last write
- keys automatically wrapped in
WeakReference references
- values automatically wrapped in
WeakReference or
SoftReference references
- 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 graphs = CacheBuilder.newBuilder()});
}
Or equivalently,
// In real life this would come from a command-line flag or config file});
}
The returned cache is implemented as a hash table with similar performance characteristics to
ConcurrentHashMap. It 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.
Note: by default, the returned cache uses equality comparisons (the
Object#equals method) to determine equality for keys or values. However, if
#weakKeys was specified, the cache uses identity (
==) comparisons instead for keys.
Likewise, if
#weakValues or
#softValues was specified, the cache uses identity
comparisons for values.
Entries are automatically evicted from the cache when any of
#maximumSize(long),
#maximumWeight(long),
#expireAfterWrite,
#expireAfterAccess,
#weakKeys,
#weakValues, or
#softValues are
requested.
If
#maximumSize(long) or
#maximumWeight(long) 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.