Package org.atlanmod.commons.cache

Interface CacheBuilder<K,​V>

  • Type Parameters:
    K - the base key type for Caches created by this builder
    V - the base value type for Cache created by this builder
    public interface CacheBuilder<K,​V>
    A builder of Cache instances.

    • Method Detail

      • empty

        @Nonnull
static <K,​V> Cache<K,​V> empty()
        Returns an immutable empty Cache that does nothing.
        Type Parameters:
        K - the type of keys maintained by this cache
        V - the type of mapped values
        Returns:
        a new cache

      • builder

        @Nonnull
static CacheBuilder<Object,​Object> builder()
        Creates a new CacheBuilder with default settings, including strong keys, strong values, and no automatic eviction of any kind.
        Returns:
        a new builder

      • recordStats

        @Nonnull
CacheBuilder<K,​V> recordStats()
        Enables the accumulation of CacheStats during the operation of the cache.

        Without this Cache.stats() will return zero for all statistics. Note that recording statistics requires bookkeeping to be performed with each operation, and thus imposes a performance penalty on cache operation.

        Returns:
        this builder (for chaining)

      • initialCapacity

        @Nonnull
CacheBuilder<K,​V> initialCapacity​(@Nonnegative
                                        int initialCapacity)
        Sets the minimum total size for the internal data structures.

        Providing a large enough estimate at construction time avoids the need for expensive resizing operations later, but setting this value unnecessarily high wastes memory.

        Parameters:
        initialCapacity - minimum total size for the internal data structures
        Returns:
        this builder instance
        Throws:
        IllegalArgumentException - if initialCapacity is negative
        IllegalStateException - if an initial capacity was already set

      • maximumSize

        @Nonnull
CacheBuilder<K,​V> maximumSize​(@Nonnegative
                                    long maximumSize)
        Specifies the maximum number of entries the cache may contain.

        Note that the cache may evict an entry before this limit is exceeded or temporarily exceed the threshold while evicting. As the cache size grows close to the maximum, the cache evicts entries that are less likely to be used again. For example, the cache may evict an entry because it hasn't been used recently or very often.

        When size is zero, elements will be evicted immediately after being loaded into the cache. This can be useful in testing, or to disable caching temporarily without a code change.

        This feature cannot be used in conjunction with maximumWeight(long, java.util.function.ToIntBiFunction<? super K1, ? extends V1>).

        Parameters:
        maximumSize - the maximum size of the cache
        Returns:
        this builder (for chaining)
        Throws:
        IllegalArgumentException - if maximumSize is negative
        IllegalStateException - if a maximum size or weight was already set

      • maximumWeight

        <K1 extends K,​V1 extends V> CacheBuilder<K,​V> maximumWeight​(@Nonnegative
                                                                        long maximumWeight,
                                                                        ToIntBiFunction<? super K1,​? extends V1> weigher)
        Specifies the maximum weight of entries the cache may contain.

        Weight is determined using the ToIntBiFunction specified with weigher. Weights are measured and recorded when entries are inserted into or updated in the cache, and are thus effectively static during the lifetime of a cache entry.

        Note that the cache may evict an entry before this limit is exceeded or temporarily exceed the threshold while evicting. As the cache size grows close to the maximum, the cache evicts entries that are less likely to be used again. For example, the cache may evict an entry because it hasn't been used recently or very often.

        When maximumWeight is zero, elements will be evicted immediately after being loaded into cache. This can be useful in testing, or to disable caching temporarily without a code change.

        Note that weight is only used to determine whether the cache is over capacity; it has no effect on selecting which entry should be evicted next.

        This feature cannot be used in conjunction with maximumSize(long).

        Parameters:
        maximumWeight - the maximum total weight of entries the cache may contain
        weigher - the weigher to use in calculating the weight of cache entries
        Returns:
        this builder (for chaining)
        Throws:
        IllegalArgumentException - if maximumWeight is negative
        IllegalStateException - if a maximum weight or size was already set

      • weakKeys

        @Nonnull
CacheBuilder<K,​V> weakKeys()
        Specifies that each key (not value) stored in the cache should be wrapped in a WeakReference (by default, strong references are used).

        WARNING: when this method is used, the resulting cache will use identity (==) comparison to determine equality of keys.

        Returns:
        this builder (for chaining)
        Throws:
        IllegalStateException - if the key strength was already set or the writer was set

      • weakValues

        @Nonnull
CacheBuilder<K,​V> weakValues()
        Specifies that each value (not key) stored in the cache should be wrapped in a WeakReference (by default, strong references are used).

        Weak values will be garbage collected once they are weakly reachable. This makes them a poor candidate for caching; consider softValues() instead.

        WARNING: when this method is used, the resulting cache will use identity (==) comparison to determine equality of values.

        Entries with values that have been garbage collected may be counted in Cache.size(), but will never be visible to read or write operations; such entries are cleaned up as part of the routine maintenance described in the class javadoc.

        Returns:
        this builder instance
        Throws:
        IllegalStateException - if the value strength was already set

      • softValues

        @Nonnull
CacheBuilder<K,​V> softValues()
        Specifies that each value (not key) stored in the cache should be wrapped in a SoftReference (by default, strong references are used).

        Softly-referenced objects will be garbage-collected in a globally least-recently-used manner, in response to memory demand.

        WARNING: when this method is used, the resulting cache will use identity (==) comparison to determine equality of values.

        Returns:
        this builder (for chaining)
        Throws:
        IllegalStateException - if the value strength was already set

      • build

        @Nonnull
<K1 extends K,​V1 extends V> Cache<K1,​V1> build()
        Builds a Cache which does not automatically load values when keys are requested.

        Consider build(Function) instead, if it is feasible to implement a CacheLoader.

        Type Parameters:
        K1 - the key type of the cache
        V1 - the value type of the cache
        Returns:
        a new cache

      • build

        @Nonnull
<K1 extends K,​V1 extends V> Cache<K1,​V1> build​(Function<? super K1,​? extends V1> mappingFunction)
        Builds a Cache, which either returns an already-loaded value for a given key or atomically computes or retrieves it using the supplied Function. If another thread is currently loading the value for this key, simply waits for that thread to finish and returns its loaded value. Note that multiple threads can concurrently load values for distinct keys.
        Type Parameters:
        K1 - the key type of the loader
        V1 - the value type of the loader
        Parameters:
        mappingFunction - the function used to obtain new values
        Returns:
        a new cache