Package org.apache.juneau.commons.collections

Class Cache3<K1,K2,K3,V>

java.lang.Object
org.apache.juneau.commons.collections.Cache3<K1,K2,K3,V>
Type Parameters:
K1 - The first key type.
K2 - The second key type.
K3 - The third key type.
V - The value type.
public class Cache3<K1,K2,K3,V> extends Object
Simple in-memory cache for storing and retrieving objects by three-part keys.
Overview:

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

Features:
  • Thread-safe concurrent access without external synchronization
  • Three-part composite key support
  • Automatic cache eviction when maximum size is reached
  • Lazy computation via Function3 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
WEAK Mode Semantics:

CacheMode.WEAK on this class is best-effort, not retention-guaranteed. Each lookup synthesizes an internal Tuple3 composite key that is never exposed to the caller, so that key is reachable only from this cache's own backing WeakHashMap. Consequently a WEAK-mode entry becomes GC-eligible immediately after insertion and may be reclaimed at the very next garbage collection - effectively behaving like CacheMode.NONE once any GC has occurred. This differs from the single-key Cache, where WEAK mode keys directly on the caller's own key and therefore retains an entry for as long as that key remains strongly reachable elsewhere. If guaranteed retention is required, use CacheMode.FULL (the default mode) instead of WEAK. See CacheMode.WEAK for details.

Usage:

// Create a cache with default supplier Cache3<String,String,String,Translation> translationCache = Cache3 .of(String.class, String.class, String.class, Translation.class) .maxSize(500) .supplier((lang, country, key) -> loadTranslation(lang, country, key)) .build(); // Retrieve using default supplier Translation t1 = translationCache.get("en", "US", "greeting"); // Or override the supplier Translation t2 = translationCache.get("fr", "FR", "greeting", () -> customTranslation);

See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Cache3.Builder<K1,K2,K3,V>
    Builder for creating configured Cache3 instances.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Cache3(Cache3.Builder<K1,K2,K3,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(K1 key1, K2 key2, K3 key3)
    Returns true if the cache contains a mapping for the specified key triplet.
    boolean
    containsValue(V value)
    Returns true if the cache contains one or more entries with the specified value.
    static <K1, K2, K3, V>
    Cache3.Builder<K1,K2,K3,V>
    create()
    Creates a new Cache3.Builder for constructing a cache with explicit type parameters.
    V
    get(K1 key1, K2 key2, K3 key3)
    Retrieves a cached value by key triplet using the default supplier.
    V
    get(K1 key1, K2 key2, K3 key3, Supplier<V> supplier)
    Retrieves a cached value by key triplet, 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 <K1, K2, K3, V>
    Cache3.Builder<K1,K2,K3,V>
    of(Class<K1> key1, Class<K2> key2, Class<K3> key3, Class<V> type)
    Creates a new Cache3.Builder for constructing a cache.
    V
    put(K1 key1, K2 key2, K3 key3, V value)
    Associates the specified value with the specified key triplet.
    V
    remove(K1 key1, K2 key2, K3 key3)
    Removes the entry for the specified key triplet 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

    • Cache3

      protected Cache3(Cache3.Builder<K1,K2,K3,V> builder)
      Constructor.
      Parameters:
      builder - The builder containing configuration settings.

  • Method Details

    • create

      public static <K1, K2, K3, V> Cache3.Builder<K1,K2,K3,V> create()
      Creates a new Cache3.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.

      Type Parameters:
      K1 - The first key type.
      K2 - The second key type.
      K3 - The third key type.
      V - The value type.
      Returns:
      A new builder for configuring the cache.

    • of

      public static <K1, K2, K3, V> Cache3.Builder<K1,K2,K3,V> of(Class<K1> key1, Class<K2> key2, Class<K3> key3, Class<V> type)
      Creates a new Cache3.Builder for constructing a cache.
      Type Parameters:
      K1 - The first key type.
      K2 - The second key type.
      K3 - The third key type.
      V - The value type.
      Parameters:
      key1 - The first key type class (used for type safety).
      key2 - The second key type class (used for type safety).
      key3 - The third 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(K1 key1, K2 key2, K3 key3)
      Returns true if the cache contains a mapping for the specified key triplet.
      Parameters:
      key1 - The first key. Can be null (null keys are supported like any other key).
      key2 - The second key. Can be null (null keys are supported like any other key).
      key3 - The third key. Can be null (null keys are supported like any other key).
      Returns:
      true if the cache contains the key triplet.

    • 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(K1 key1, K2 key2, K3 key3)
      Retrieves a cached value by key triplet using the default supplier.
      Parameters:
      key1 - First key component. Can be null (null keys are supported like any other key).
      key2 - Second key component. Can be null (null keys are supported like any other key).
      key3 - Third key component. 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(K1 key1, K2 key2, K3 key3, Supplier<V> supplier)
      Retrieves a cached value by key triplet, computing it if necessary using the provided supplier.
      Parameters:
      key1 - First key component. Can be null (null keys are supported like any other key).
      key2 - Second key component. Can be null (null keys are supported like any other key).
      key3 - Third key component. 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.
      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(K1 key1, K2 key2, K3 key3, V value)
      Associates the specified value with the specified key triplet.
      Parameters:
      key1 - The first key. Can be null (null keys are supported like any other key).
      key2 - The second key. Can be null (null keys are supported like any other key).
      key3 - The third key. Can be null (null keys are supported like any other key).
      value - The value to associate with the key triplet.
      Returns:
      The previous value associated with the key triplet, or null if there was no mapping.

    • remove

      public V remove(K1 key1, K2 key2, K3 key3)
      Removes the entry for the specified key triplet from the cache.
      Parameters:
      key1 - The first key. Can be null (null keys are supported like any other key).
      key2 - The second key. Can be null (null keys are supported like any other key).
      key3 - The third key. Can be null (null keys are supported like any other key).
      Returns:
      The previous value associated with the key triplet, 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.