Package org.apache.juneau.commons.collections

Class Cache.Builder<K,V>

java.lang.Object
org.apache.juneau.commons.collections.Cache.Builder<K,V>
Type Parameters:
K - The key type.
V - The value type.
Enclosing class:
Cache<K,V>
public static class Cache.Builder<K,V> extends Object
Builder for creating configured Cache instances.
Example:

// Using of() for simple types Cache<String,Pattern> cache1 = Cache .of(String.class, Pattern.class) .maxSize(200) .logOnExit("Pattern") .build(); // Using create() for complex generics Cache<Class<?>,List<Method>> cache2 = Cache.<Class<?>,List<Method>>create() .supplier(this::findMethods) .build();

See Also:

  • Method Details

    • build

      public Cache<K,V> build()
      Builds a new Cache instance with the configured settings.
      Returns:
      A new immutable Cache instance.

    • cacheMode

      public Cache.Builder<K,V> cacheMode(CacheMode value)
      Sets the caching mode for this cache.

      Available modes:

      Example:

      // No caching for testing Cache<String,Object> cache1 = Cache.of(String.class, Object.class) .cacheMode(CacheMode.NONE) .build(); // Weak caching for Class metadata Cache<Class<?>,ClassMeta> cache2 = Cache.of(Class.class, ClassMeta.class) .cacheMode(CacheMode.WEAK) .build(); // Full caching (default) Cache<String,Pattern> cache3 = Cache.of(String.class, Pattern.class) .cacheMode(CacheMode.FULL) .build();

      Parameters:
      value - The caching mode.
      Returns:
      This object for method chaining.

    • logOnExit

      public Cache.Builder<K,V> logOnExit(boolean value, String idValue)
      Conditionally enables logging of cache statistics when the JVM exits.

      When enabled, the cache will register a shutdown hook that logs the cache name, total cache hits, and total cache misses (size of cache) to help analyze cache effectiveness.

      Parameters:
      value - Whether to enable logging on exit.
      idValue - The identifier to use in the log message.
      Returns:
      This object for method chaining.

    • logOnExit

      public Cache.Builder<K,V> logOnExit(String value)
      Enables logging of cache statistics when the JVM exits.

      When enabled, the cache will register a shutdown hook that logs the cache name, total cache hits, and total cache misses (size of cache) to help analyze cache effectiveness.

      Example output:

      Pattern cache: hits=1523, misses: 47

      This is useful for:

      • Performance tuning and identifying caching opportunities
      • Determining optimal max size values
      • Monitoring cache efficiency in production
      Parameters:
      value - The identifier to use in the log message.
      Returns:
      This object for method chaining.

    • maxSize

      public Cache.Builder<K,V> maxSize(int value)
      Specifies the maximum number of entries allowed in this cache.

      When the cache size exceeds this value, the entire cache is cleared to make room for new entries. This is a simple eviction strategy that avoids the overhead of LRU/LFU tracking.

      Default value: 1000 (or value of system property juneau.cache.maxSize)

      Notes:
      • Setting this too low may cause excessive cache clearing and reduce effectiveness
      • Setting this too high may consume excessive memory
      • For unbounded caching, use Integer.MAX_VALUE (not recommended for production)
      Parameters:
      value - The maximum number of cache entries. Must be positive.
      Returns:
      This object for method chaining.

    • supplier

      public Cache.Builder<K,V> supplier(Function<K,V> value)
      Specifies the default supplier function for computing values when keys are not found.

      This supplier will be used by Cache.get(Object) when a key is not in the cache. Individual lookups can override this supplier using Cache.get(Object, Supplier).

      Example:

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

      Parameters:
      value - The default supplier function. Can be null.
      Returns:
      This object for method chaining.

    • threadLocal

      public Cache.Builder<K,V> threadLocal()
      Enables thread-local caching.

      When enabled, each thread gets its own separate cache instance. This is useful for thread-unsafe objects like MessageFormat that need to be cached per thread.

      This is a shortcut for wrapping a cache in a ThreadLocal, but provides a cleaner API.

      Example:

      // Thread-local cache for MessageFormat instances Cache<String,MessageFormat> cache = Cache .of(String.class, MessageFormat.class) .maxSize(100) .threadLocal() .build();

      This is equivalent to:

      ThreadLocal<Cache<String,MessageFormat>> cache = ThreadLocal.withInitial(() -> Cache .of(String.class, MessageFormat.class) .maxSize(100) .build());

      Returns:
      This object for method chaining.

    • weak

      public Cache.Builder<K,V> weak()
      Sets the caching mode to WEAK.

      This is a shortcut for calling cacheMode(CacheMode.WEAK).

      Weak caching uses WeakHashMap for storage, allowing cache entries to be garbage collected when keys are no longer strongly referenced elsewhere.

      Example:

      // Weak caching for Class metadata Cache<Class<?>,ClassMeta> cache = Cache.of(Class.class, ClassMeta.class) .weak() .build();

      Returns:
      This object for method chaining.
      See Also: