Package io.github.dhruv1110.jcachex

Class CacheConfig.Builder<K,​V>

  • Type Parameters:
    K - the type of keys maintained by the cache
    V - the type of mapped values
    Enclosing class:
    CacheConfig<K,​V>
    public static class CacheConfig.Builder<K,​V>
extends Object
    Builder class for constructing CacheConfig instances.

    This builder follows the fluent interface pattern, allowing method chaining for convenient configuration setup.

    Usage Example:

    
 CacheConfig<String, User> config = CacheConfig.<String, User>builder()
         .maximumSize(1000L)
         .expireAfterWrite(Duration.ofMinutes(30))
         .recordStats(true)
         .addListener(new MyEventListener())
         .build();

    • Constructor Detail

      • Builder

        public Builder()

    • Method Detail

      • maximumSize

        public CacheConfig.Builder<K,​V> maximumSize​(Long maximumSize)
        Sets the maximum number of entries the cache may contain.

        When this limit is exceeded, the cache will evict entries according to the configured eviction strategy.

        Parameters:
        maximumSize - the maximum size, must be positive
        Returns:
        this builder instance
        Throws:
        IllegalArgumentException - if maximumSize is not positive

      • maximumWeight

        public CacheConfig.Builder<K,​V> maximumWeight​(Long maximumWeight)
        Sets the maximum total weight of entries the cache may contain.

        This requires a weigher function to be set. When this limit is exceeded, the cache will evict entries according to the configured eviction strategy.

        Parameters:
        maximumWeight - the maximum weight, must be positive
        Returns:
        this builder instance
        Throws:
        IllegalArgumentException - if maximumWeight is not positive

      • weigher

        public CacheConfig.Builder<K,​V> weigher​(BiFunction<K,​V,​Long> weigher)
        Sets the weigher function used to calculate entry weights.

        This is required when using maximumWeight(Long).

        Example:

        
 .weigher((key, value) -> value.toString().length())
        Parameters:
        weigher - the weigher function
        Returns:
        this builder instance

      • expireAfterWrite

        public CacheConfig.Builder<K,​V> expireAfterWrite​(Duration duration)
        Sets the duration after which an entry should be automatically removed from the cache once the duration has elapsed after the entry's creation or last update.
        Parameters:
        duration - the expiration duration, must not be negative
        Returns:
        this builder instance
        Throws:
        IllegalArgumentException - if duration is negative

      • expireAfterWrite

        public CacheConfig.Builder<K,​V> expireAfterWrite​(long duration,
                                                       TimeUnit unit)
        Sets the duration after which an entry should be automatically removed from the cache once the duration has elapsed after the entry's creation or last update.
        Parameters:
        duration - the expiration duration, must not be negative
        unit - the time unit of the duration argument
        Returns:
        this builder instance
        Throws:
        IllegalArgumentException - if duration is negative

      • expireAfterAccess

        public CacheConfig.Builder<K,​V> expireAfterAccess​(Duration duration)
        Sets the duration after which an entry should be automatically removed from the cache once the duration has elapsed after the entry's creation, last update, or last access.
        Parameters:
        duration - the expiration duration, must not be negative
        Returns:
        this builder instance
        Throws:
        IllegalArgumentException - if duration is negative

      • expireAfterAccess

        public CacheConfig.Builder<K,​V> expireAfterAccess​(long duration,
                                                        TimeUnit unit)
        Sets the duration after which an entry should be automatically removed from the cache once the duration has elapsed after the entry's creation, last update, or last access.
        Parameters:
        duration - the expiration duration, must not be negative
        unit - the time unit of the duration argument
        Returns:
        this builder instance
        Throws:
        IllegalArgumentException - if duration is negative

      • evictionStrategy

        public CacheConfig.Builder<K,​V> evictionStrategy​(EvictionStrategy<K,​V> evictionStrategy)
        Sets the eviction strategy used to determine which entries to remove when the cache size or weight limits are exceeded.

        If not set, the cache will use LRU (Least Recently Used) eviction by default.

        Parameters:
        evictionStrategy - the eviction strategy to use
        Returns:
        this builder instance

      • weakKeys

        public CacheConfig.Builder<K,​V> weakKeys​(boolean weakKeys)
        Configures the cache to store keys using weak references.

        This allows keys to be garbage collected when they are not referenced elsewhere in the application.

        Parameters:
        weakKeys - true to enable weak key references
        Returns:
        this builder instance

      • weakValues

        public CacheConfig.Builder<K,​V> weakValues​(boolean weakValues)
        Configures the cache to store values using weak references.

        This allows values to be garbage collected when they are not referenced elsewhere in the application.

        Parameters:
        weakValues - true to enable weak value references
        Returns:
        this builder instance

      • softValues

        public CacheConfig.Builder<K,​V> softValues​(boolean softValues)
        Configures the cache to store values using soft references.

        This allows values to be garbage collected when memory is low.

        Parameters:
        softValues - true to enable soft value references
        Returns:
        this builder instance

      • loader

        public CacheConfig.Builder<K,​V> loader​(Function<K,​V> loader)
        Sets the function used to load values synchronously when not present in cache.

        This enables the cache to automatically load missing values on demand.

        Example:

        
 .loader(key -> userService.findById(key))
        Parameters:
        loader - the loader function
        Returns:
        this builder instance

      • asyncLoader

        public CacheConfig.Builder<K,​V> asyncLoader​(Function<K,​CompletableFuture<V>> asyncLoader)
        Sets the function used to load values asynchronously when not present in cache.

        This enables the cache to automatically load missing values on demand without blocking the calling thread.

        Example:

        
 .asyncLoader(key -> CompletableFuture.supplyAsync(() -> userService.findById(key)))
        Parameters:
        asyncLoader - the async loader function
        Returns:
        this builder instance

      • refreshAfterWrite

        public CacheConfig.Builder<K,​V> refreshAfterWrite​(Duration duration)
        Sets the duration after which an entry should be automatically refreshed once the duration has elapsed after the entry's creation or last update.

        This requires a loader function to be set. Refresh operations happen asynchronously and do not block cache access.

        Parameters:
        duration - the refresh duration, must not be negative
        Returns:
        this builder instance
        Throws:
        IllegalArgumentException - if duration is negative

      • recordStats

        public CacheConfig.Builder<K,​V> recordStats​(boolean recordStats)
        Sets whether statistics should be recorded for this cache.

        Statistics include hit/miss rates, eviction counts, and load times. Enabling statistics has a small performance overhead.

        Parameters:
        recordStats - true to enable statistics recording
        Returns:
        this builder instance

      • initialCapacity

        public CacheConfig.Builder<K,​V> initialCapacity​(int initialCapacity)
        Sets the initial capacity of the cache's internal data structure.

        This is a performance hint and does not limit the cache size.

        Parameters:
        initialCapacity - the initial capacity, must be positive
        Returns:
        this builder instance
        Throws:
        IllegalArgumentException - if initialCapacity is not positive

      • concurrencyLevel

        public CacheConfig.Builder<K,​V> concurrencyLevel​(int concurrencyLevel)
        Sets the concurrency level for the cache's internal data structure.

        This is a performance hint that indicates the expected number of concurrent threads that will modify the cache.

        Parameters:
        concurrencyLevel - the concurrency level, must be positive
        Returns:
        this builder instance
        Throws:
        IllegalArgumentException - if concurrencyLevel is not positive

      • directory

        public CacheConfig.Builder<K,​V> directory​(String directory)
        Sets the directory path for persistent cache storage.

        This is currently reserved for future use and does not affect cache behavior in the current implementation.

        Parameters:
        directory - the directory path
        Returns:
        this builder instance

      • addListener

        public CacheConfig.Builder<K,​V> addListener​(CacheEventListener<K,​V> listener)
        Adds an event listener to receive notifications about cache operations.

        Multiple listeners can be added and all will receive events.

        Example:

        
 .addListener(new CacheEventListener<String, User>() {
     &#64;Override
     public void onPut(String key, User value) {
         logger.info("Added user: " + key);
     }
     // ... other methods
 })
        Parameters:
        listener - the event listener to add
        Returns:
        this builder instance