Package io.github.dhruv1110.jcachex

Class CacheBuilder<K,​V>

  • Type Parameters:
    K - the type of keys maintained by the cache
    V - the type of mapped values
    public final class CacheBuilder<K,​V>
extends Object
    Fluent builder for creating JCacheX cache instances with enhanced type support.

    This builder provides a convenient, type-safe way to create different types of cache implementations with various configurations. It supports all cache types available in JCacheX and provides sensible defaults for different use cases.

    Basic Usage Examples:

    
 // Simple cache with default settings
 Cache<String, User> cache = CacheBuilder.<String, User>newBuilder()
         .maximumSize(1000L)
         .build();

 // High-performance cache for read-heavy workloads
 Cache<String, Product> productCache = CacheBuilder.<String, Product>newBuilder()
         .maximumSize(5000L)
         .expireAfterWrite(Duration.ofMinutes(30))
         .cacheType(CacheType.READ_ONLY_OPTIMIZED)
         .frequencySketchType(FrequencySketchType.OPTIMIZED)
         .build();

 // Memory-optimized cache for constrained environments
 Cache<String, Data> dataCache = CacheBuilder.<String, Data>newBuilder()
         .maximumSize(2000L)
         .cacheType(CacheType.ALLOCATION_OPTIMIZED)
         .frequencySketchType(FrequencySketchType.NONE)
         .build();

    Cache Types:

    • DEFAULT: Standard cache implementation
    • OPTIMIZED: Advanced eviction with TinyWindowLFU
    • JIT_OPTIMIZED: JIT-friendly implementation
    • ALLOCATION_OPTIMIZED: Minimal allocation overhead
    • LOCALITY_OPTIMIZED: CPU cache-friendly layout
    • ZERO_COPY_OPTIMIZED: Zero-copy operations
    • READ_ONLY_OPTIMIZED: Read-heavy workloads
    • WRITE_HEAVY_OPTIMIZED: Write-intensive workloads
    • JVM_OPTIMIZED: GC-aware optimizations
    • HARDWARE_OPTIMIZED: Hardware-specific optimizations
    • ML_OPTIMIZED: Machine learning-based eviction
    • PROFILED_OPTIMIZED: Development and testing
    Since:
    1.0.0

    • Method Detail

      • newBuilder

        public static <K,​V> CacheBuilder<K,​V> newBuilder()
        Creates a new cache builder.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        a new cache builder instance

      • cacheType

        public CacheBuilder<K,​V> cacheType​(CacheBuilder.CacheType cacheType)
        Sets the cache type to use.
        Parameters:
        cacheType - the cache type
        Returns:
        this builder instance

      • maximumSize

        public CacheBuilder<K,​V> maximumSize​(long maximumSize)
        Sets the maximum number of entries the cache may contain.
        Parameters:
        maximumSize - the maximum size
        Returns:
        this builder instance

      • maximumWeight

        public CacheBuilder<K,​V> maximumWeight​(long maximumWeight)
        Sets the maximum total weight of entries the cache may contain.
        Parameters:
        maximumWeight - the maximum weight
        Returns:
        this builder instance

      • weigher

        public CacheBuilder<K,​V> weigher​(BiFunction<K,​V,​Long> weigher)
        Sets the weigher function used to calculate entry weights.
        Parameters:
        weigher - the weigher function
        Returns:
        this builder instance

      • expireAfterWrite

        public CacheBuilder<K,​V> expireAfterWrite​(Duration duration)
        Sets the duration after which an entry should expire after being written.
        Parameters:
        duration - the expiration duration
        Returns:
        this builder instance

      • expireAfterWrite

        public CacheBuilder<K,​V> expireAfterWrite​(long duration,
                                                TimeUnit unit)
        Sets the duration after which an entry should expire after being written.
        Parameters:
        duration - the duration value
        unit - the time unit
        Returns:
        this builder instance

      • expireAfterAccess

        public CacheBuilder<K,​V> expireAfterAccess​(Duration duration)
        Sets the duration after which an entry should expire after being accessed.
        Parameters:
        duration - the expiration duration
        Returns:
        this builder instance

      • expireAfterAccess

        public CacheBuilder<K,​V> expireAfterAccess​(long duration,
                                                 TimeUnit unit)
        Sets the duration after which an entry should expire after being accessed.
        Parameters:
        duration - the duration value
        unit - the time unit
        Returns:
        this builder instance

      • evictionStrategy

        public CacheBuilder<K,​V> evictionStrategy​(EvictionStrategy<K,​V> evictionStrategy)
        Sets the eviction strategy to use.
        Parameters:
        evictionStrategy - the eviction strategy
        Returns:
        this builder instance

      • frequencySketchType

        public CacheBuilder<K,​V> frequencySketchType​(FrequencySketchType frequencySketchType)
        Sets the frequency sketch type for tracking access patterns.
        Parameters:
        frequencySketchType - the frequency sketch type
        Returns:
        this builder instance

      • weakKeys

        public CacheBuilder<K,​V> weakKeys()
        Enables weak key references.
        Returns:
        this builder instance

      • weakValues

        public CacheBuilder<K,​V> weakValues()
        Enables weak value references.
        Returns:
        this builder instance

      • softValues

        public CacheBuilder<K,​V> softValues()
        Enables soft value references.
        Returns:
        this builder instance

      • loader

        public CacheBuilder<K,​V> loader​(Function<K,​V> loader)
        Sets the loader function for automatic value loading.
        Parameters:
        loader - the loader function
        Returns:
        this builder instance

      • asyncLoader

        public CacheBuilder<K,​V> asyncLoader​(Function<K,​CompletableFuture<V>> asyncLoader)
        Sets the async loader function for automatic value loading.
        Parameters:
        asyncLoader - the async loader function
        Returns:
        this builder instance

      • refreshAfterWrite

        public CacheBuilder<K,​V> refreshAfterWrite​(Duration duration)
        Sets the refresh duration for automatic cache refresh.
        Parameters:
        duration - the refresh duration
        Returns:
        this builder instance

      • recordStats

        public CacheBuilder<K,​V> recordStats()
        Enables statistics recording.
        Returns:
        this builder instance

      • recordStats

        public CacheBuilder<K,​V> recordStats​(boolean recordStats)
        Sets whether to record statistics.
        Parameters:
        recordStats - whether to record statistics
        Returns:
        this builder instance

      • initialCapacity

        public CacheBuilder<K,​V> initialCapacity​(int initialCapacity)
        Sets the initial capacity hint for the cache's internal data structure.
        Parameters:
        initialCapacity - the initial capacity
        Returns:
        this builder instance

      • concurrencyLevel

        public CacheBuilder<K,​V> concurrencyLevel​(int concurrencyLevel)
        Sets the concurrency level hint for the cache's internal data structure.
        Parameters:
        concurrencyLevel - the concurrency level
        Returns:
        this builder instance

      • listener

        public CacheBuilder<K,​V> listener​(CacheEventListener<K,​V> listener)
        Adds an event listener to the cache.
        Parameters:
        listener - the event listener
        Returns:
        this builder instance

      • build

        public Cache<K,​V> build()
        Builds and returns the configured cache instance.
        Returns:
        the configured cache

      • forReadHeavyWorkload

        public static <K,​V> CacheBuilder<K,​V> forReadHeavyWorkload()
        Creates a builder pre-configured for high-performance read workloads.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        a pre-configured builder

      • forWriteHeavyWorkload

        public static <K,​V> CacheBuilder<K,​V> forWriteHeavyWorkload()
        Creates a builder pre-configured for high-performance write workloads.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        a pre-configured builder

      • forMemoryConstrainedEnvironment

        public static <K,​V> CacheBuilder<K,​V> forMemoryConstrainedEnvironment()
        Creates a builder pre-configured for memory-constrained environments.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        a pre-configured builder

      • forHighPerformance

        public static <K,​V> CacheBuilder<K,​V> forHighPerformance()
        Creates a builder pre-configured for high-performance scenarios.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        a pre-configured builder

      • forMachineLearning

        public static <K,​V> CacheBuilder<K,​V> forMachineLearning()
        Creates a builder pre-configured for machine learning workloads.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        a pre-configured builder

      • forDevelopment

        public static <K,​V> CacheBuilder<K,​V> forDevelopment()
        Creates a builder pre-configured for development and testing.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        a pre-configured builder