Package org.apache.juneau.commons.collections

Class Cache<K,V>

java.lang.Object
org.apache.juneau.commons.collections.Cache<K,V>
Type Parameters:
K - The key type. Can be an array type for content-based key matching.
V - The value type.
public class Cache<K,V> extends Object
Simple in-memory cache for storing and retrieving objects by key.
Overview:

This class uses ConcurrentHashMap internally to provide a thread-safe caching layer with automatic value computation, cache eviction, and statistics tracking. It's designed for caching expensive-to-compute or frequently-accessed objects to improve performance.

Features:
  • Thread-safe concurrent access without external synchronization
  • Automatic cache eviction when maximum size is reached
  • Lazy computation via Supplier pattern
  • Default supplier support for simplified access
  • Built-in hit/miss statistics tracking
  • Optional logging of cache statistics on JVM shutdown
  • Can be disabled entirely via builder or system property
  • Array Support: Arrays can be used as keys with proper content-based hashing and equality
Usage:

// Create a cache with default supplier Cache<String,Pattern> patternCache = Cache .of(String.class, Pattern.class) .maxSize(100) .supplier(Pattern::compile) .build(); // Retrieve using default supplier Pattern pattern1 = patternCache.get("[a-z]+"); // Or override the supplier Pattern pattern2 = patternCache.get("[0-9]+", () -> Pattern.compile("[0-9]+", Pattern.CASE_INSENSITIVE));

Array Support:

Unlike standard HashMap which uses identity-based equality for array keys, this class properly handles arrays using content-based comparison:

// Arrays work correctly as keys Cache<String[],Result> cache = Cache.of(String[].class, Result.class).build(); cache.get(new String[]{"a", "b"}, () -> computeResult()); Result r = cache.get(new String[]{"a", "b"}, () -> computeResult()); // Cache hit!

Cache Behavior:
  • When a key is requested:
    • If the key exists in the cache, the cached value is returned (cache hit)
    • If the key doesn't exist, the supplier is invoked to compute the value
    • The computed value is stored in the cache and returned (cache miss)
  • When the cache exceeds Cache.Builder.maxSize(int), the entire cache is cleared
  • If the cache is disabled, the supplier is always invoked without caching
  • Null keys always bypass the cache and invoke the supplier
Environment Variables:

The following system properties can be used to configure default cache behavior:

  • juneau.cache.mode - Cache mode: NONE/WEAK/FULL (default: FULL, case-insensitive)
  • juneau.cache.maxSize - Maximum cache size before eviction (default: 1000)
  • juneau.cache.logOnExit - Log cache statistics on shutdown (default: false)
Thread Safety:

This class is thread-safe and can be safely used from multiple threads without external synchronization. However, note that when the cache is cleared due to exceeding max size, there's a small window where multiple threads might compute the same value. This is acceptable for most use cases as it only affects performance, not correctness.

Performance Considerations:
Examples:

// Simple cache with defaults using of() Cache<String,Integer> cache = Cache.of(String.class, Integer.class).build(); // Cache with custom configuration using of() Cache<Class<?>,ClassMeta> classMetaCache = Cache .of(Class.class, ClassMeta.class) .maxSize(500) .logOnExit("ClassMeta") .build(); // Complex generics using create() Cache<Class<?>,List<AnnotationInfo<Annotation>>> annotationsCache = Cache.<Class<?>,List<AnnotationInfo<Annotation>>>create() .supplier(this::findClassAnnotations) .build(); // Disabled cache for testing Cache<String,Object> disabledCache = Cache .of(String.class, Object.class) .disableCaching() .build();

See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Cache.Builder<K,V>
    Builder for creating configured Cache instances.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Cache(Cache.Builder<K,V> builder)
    Constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    cleanup()
    Cleans up thread-local storage for the current thread.
    void
    clear()
    Removes all entries from the cache.
    boolean
    containsKey(K key)
    Returns true if the cache contains a mapping for the specified key.
    boolean
    containsValue(V value)
    Returns true if the cache contains one or more entries with the specified value.
    static <K, V> Cache.Builder<K,V>
    create()
    Creates a new Cache.Builder for constructing a cache with explicit type parameters.
    V
    get(K key)
    Retrieves a cached value by key using the default supplier.
    V
    get(K key, Supplier<V> supplier)
    Retrieves a cached value by key, computing it if necessary using the provided supplier.
    int
    getCacheHits()
    Returns the total number of cache hits since this cache was created.
    boolean
    isEmpty()
    Returns true if the cache contains no entries.
    static <K, V> Cache.Builder<K,V>
    of(Class<K> key, Class<V> type)
    Creates a new Cache.Builder for constructing a cache.
    V
    put(K key, V value)
    Associates the specified value with the specified key in this cache.
    V
    remove(K key)
    Removes the entry for the specified key from the cache.
    int
    size()
    Returns the number of entries in the cache.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Cache

      protected Cache(Cache.Builder<K,V> builder)
      Constructor.
      Parameters:
      builder - The builder containing configuration settings.

  • Method Details

    • create

      public static <K, V> Cache.Builder<K,V> create()
      Creates a new Cache.Builder for constructing a cache with explicit type parameters.

      This variant allows you to specify the cache's generic types explicitly without passing the class objects, which is useful when working with complex parameterized types.

      Example:

      // Working with complex generic types Cache<Class<?>,List<AnnotationInfo<Annotation>>> cache = Cache.<Class<?>,List<AnnotationInfo<Annotation>>>create() .supplier(key -> findAnnotations(key)) .build();

      Type Parameters:
      K - The key type.
      V - The value type.
      Returns:
      A new builder for configuring the cache.

    • of

      public static <K, V> Cache.Builder<K,V> of(Class<K> key, Class<V> type)
      Creates a new Cache.Builder for constructing a cache.
      Example:

      Cache<String,Pattern> cache = Cache .of(String.class, Pattern.class) .maxSize(100) .build();

      Type Parameters:
      K - The key type.
      V - The value type.
      Parameters:
      key - The key type class (used for type safety).
      type - The value type class.
      Returns:
      A new builder for configuring the cache.

    • clear

      public void clear()
      Removes all entries from the cache.

    • cleanup

      public void cleanup()
      Cleans up thread-local storage for the current thread.

      This method should be called when a thread is finished using this cache to prevent memory leaks in thread pool environments where threads are reused. Only has an effect if this cache was created with thread-local mode enabled.

    • containsKey

      public boolean containsKey(K key)
      Returns true if the cache contains a mapping for the specified key.
      Parameters:
      key - The key to check. Can be null (null keys are supported like any other key).
      Returns:
      true if the cache contains the key.

    • containsValue

      public boolean containsValue(V value)
      Returns true if the cache contains one or more entries with the specified value.
      Parameters:
      value - The value to check. Can be null, in which case this method returns false (the cache never stores null values).
      Returns:
      true if the cache contains the value.

    • get

      public V get(K key)
      Retrieves a cached value by key using the default supplier.

      This method uses the default supplier configured via Cache.Builder.supplier(Function). If no default supplier was configured, this method will throw a NullPointerException.

      Example:

      Cache<String,Pattern> cache = Cache .of(String.class, Pattern.class) .supplier(Pattern::compile) .build(); // Uses default supplier Pattern p = cache.get("[0-9]+");

      Parameters:
      key - The cache key. Can be null (null keys are supported like any other key).
      Returns:
      The cached or computed value. May be null if the supplier returns null.
      Throws:
      NullPointerException - if no default supplier was configured.

    • get

      public V get(K key, Supplier<V> supplier)
      Retrieves a cached value by key, computing it if necessary using the provided supplier.

      This method implements the cache-aside pattern:

      1. If the key exists in the cache, return the cached value (cache hit)
      2. If the key doesn't exist, invoke the supplier to compute the value
      3. Store the computed value in the cache using ConcurrentHashMap.putIfAbsent(Object, Object)
      4. Return the value
      Behavior:
      • If the cache is disabled, always invokes the supplier without caching
      • If the cache exceeds Cache.Builder.maxSize(int), clears all entries before storing the new value
      • Thread-safe: Multiple threads can safely call this method concurrently
      • The supplier may be called multiple times for the same key in concurrent scenarios (due to ConcurrentHashMap.putIfAbsent(Object, Object) semantics)
      • Array Keys: Arrays are matched by content, not identity
      Example:

      Cache<String,Pattern> cache = Cache.of(String.class, Pattern.class).build(); // First call: compiles pattern and caches it Pattern p1 = cache.get("[0-9]+", () -> Pattern.compile("[0-9]+")); // Second call: returns cached pattern instantly Pattern p2 = cache.get("[0-9]+", () -> Pattern.compile("[0-9]+")); assert p1 == p2; // Same instance

      Parameters:
      key - The cache key. Can be null (null keys are supported like any other key).
      supplier - The supplier to compute the value if it's not in the cache. Must not be null or an IllegalArgumentException is thrown.
      Returns:
      The cached or computed value. May be null if the supplier returns null.

    • getCacheHits

      public int getCacheHits()
      Returns the total number of cache hits since this cache was created.

      A cache hit occurs when get(Object) or get(Object, Supplier) finds an existing cached value for the requested key, avoiding the need to invoke the supplier.

      Cache Effectiveness:

      You can calculate the cache hit ratio using:

      int hits = cache.getCacheHits(); int misses = cache.size(); int total = hits + misses; double hitRatio = (double) hits / total; // 0.0 to 1.0

      Notes:
      • This counter is never reset, even when clear() is called
      • Thread-safe using LongAdder
      • Returns 0 if the cache is disabled
      Returns:
      The total number of cache hits since creation.

    • isEmpty

      public boolean isEmpty()
      Returns true if the cache contains no entries.
      Returns:
      true if the cache is empty.

    • put

      public V put(K key, V value)
      Associates the specified value with the specified key in this cache.
      Parameters:
      key - The cache key. Can be null (null keys are supported like any other key).
      value - The value to associate with the key.
      Returns:
      The previous value associated with the key, or null if there was no mapping.

    • remove

      public V remove(K key)
      Removes the entry for the specified key from the cache.
      Parameters:
      key - The key to remove. Can be null (null keys are supported like any other key).
      Returns:
      The previous value associated with the key, or null if there was no mapping.

    • size

      public int size()
      Returns the number of entries in the cache.
      Returns:
      The number of cached entries.